Managing Companies

This guide explains how to create, update, and manage company profiles in Recommand for Peppol document exchange using the Recommand API.

Overview

A company in Recommand represents a business entity that can send or receive Peppol documents. Each company must be registered before it can participate in document exchange.

Prerequisites

A Recommand account with API access
Your API key and secret
Your team ID

Retrieving Your Team ID

Your team ID is required for most company management operations. You can find it in the Recommand dashboard under Account > API Keys.

Listing Companies

To retrieve all companies associated with your team using the list companies endpoint:

async function listCompanies(teamId) {
  const response = await fetch(
    `https://peppol.recommand.eu/api/peppol/${teamId}/companies`,
    {
      headers: {
        Authorization:
          "Basic " +
          Buffer.from("your_api_key:your_api_secret").toString("base64"),
      },
    }
  );

  const result = await response.json();
  return result.companies;
}

// Example usage
const companies = await listCompanies("your_team_id");
companies.forEach((company) => {
  console.log(`${company.name} (${company.id})`);
});

javascript

Creating a Company

To create a new company using the create company endpoint. When creating a new company, it is automatically registered in the Peppol network. If the company is already registered through another provider, this will fail. Companies that are registered with the Belgian government portal Hermes (as is the case for most Belgian companies) are automatically migrated over to Recommand.

async function createCompany(teamId, companyData) {
  const response = await fetch(
    `https://peppol.recommand.eu/api/peppol/${teamId}/companies`,
    {
      method: "POST",
      headers: {
        Authorization:
          "Basic " +
          Buffer.from("your_api_key:your_api_secret").toString("base64"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify(companyData),
    }
  );

  return response.json();
}

// Example usage
const newCompany = await createCompany("your_team_id", {
  name: "ACME Corporation",
  address: "123 Main Street",
  postalCode: "1000",
  city: "Brussels",
  country: "BE",
  enterpriseNumber: "0123456789",
  vatNumber: "BE0123456789",
});

if (newCompany.success) {
  console.log(`Company created with ID: ${newCompany.company.id}`);
} else {
  console.error("Failed to create company:", newCompany.errors);
}

javascript

Company Fields

Field	Description	Required	Example
`name`	Company name	Yes	`"ACME Corporation"`
`address`	Street address	Yes	`"123 Main Street"`
`postalCode`	Postal/zip code	Yes	`"1000"`
`city`	City	Yes	`"Brussels"`
`country`	Country code (currently only BE supported)	Yes	`"BE"`
`enterpriseNumber`	Belgian enterprise number	No	`"0123456789"`
`vatNumber`	VAT registration number	No	`"BE0123456789"`

Retrieving a Company

To get details about a specific company using the get company endpoint:

async function getCompany(teamId, companyId) {
  const response = await fetch(
    `https://peppol.recommand.eu/api/peppol/${teamId}/companies/${companyId}`,
    {
      headers: {
        Authorization:
          "Basic " +
          Buffer.from("your_api_key:your_api_secret").toString("base64"),
      },
    }
  );

  return response.json();
}

// Example usage
const companyDetails = await getCompany("your_team_id", "company_id");
if (companyDetails.success) {
  console.log(companyDetails.company);
} else {
  console.error("Failed to retrieve company:", companyDetails.errors);
}

javascript

Updating a Company

To update an existing company using the update company endpoint:

async function updateCompany(teamId, companyId, updatedData) {
  const response = await fetch(
    `https://peppol.recommand.eu/api/peppol/${teamId}/companies/${companyId}`,
    {
      method: "PUT",
      headers: {
        Authorization:
          "Basic " +
          Buffer.from("your_api_key:your_api_secret").toString("base64"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify(updatedData),
    }
  );

  return response.json();
}

// Example usage
const updateResult = await updateCompany("your_team_id", "company_id", {
  name: "ACME Corporation Updated",
  address: "456 New Street",
  postalCode: "1000",
  city: "Brussels",
  country: "BE",
  enterpriseNumber: "0123456789",
  vatNumber: "BE0123456789",
});

if (updateResult.success) {
  console.log("Company updated successfully");
} else {
  console.error("Failed to update company:", updateResult.errors);
}

javascript

Deleting a Company

To delete a company using the delete company endpoint:

async function deleteCompany(teamId, companyId) {
  const response = await fetch(
    `https://peppol.recommand.eu/api/peppol/${teamId}/companies/${companyId}`,
    {
      method: "DELETE",
      headers: {
        Authorization:
          "Basic " +
          Buffer.from("your_api_key:your_api_secret").toString("base64"),
      },
    }
  );

  return response.json();
}

// Example usage
const deleteResult = await deleteCompany("your_team_id", "company_id");
if (deleteResult.success) {
  console.log("Company deleted successfully");
} else {
  console.error("Failed to delete company:", deleteResult.errors);
}

javascript

Complete Example: Company Management

Here's a full example of creating, updating, and managing companies:

// Setup authentication
const API_KEY = "your_api_key";
const API_SECRET = "your_api_secret";
const TEAM_ID = "your_team_id";
const auth =
  "Basic " + Buffer.from(`${API_KEY}:${API_SECRET}`).toString("base64");
const baseUrl = "https://peppol.recommand.eu/api/peppol";

// Create a new company
async function createCompany() {
  const response = await fetch(`${baseUrl}/${TEAM_ID}/companies`, {
    method: "POST",
    headers: {
      Authorization: auth,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Test Company",
      address: "123 Test Street",
      postalCode: "1000",
      city: "Brussels",
      country: "BE",
      enterpriseNumber: "0123456789",
      vatNumber: "BE0123456789",
    }),
  });

  const result = await response.json();
  if (result.success) {
    console.log(`Company created with ID: ${result.company.id}`);
    return result.company.id;
  } else {
    console.error("Failed to create company:", result.errors);
    return null;
  }
}

// List all companies
async function listCompanies() {
  const response = await fetch(`${baseUrl}/${TEAM_ID}/companies`, {
    headers: { Authorization: auth },
  });

  const result = await response.json();
  if (result.success) {
    console.log("Companies:");
    result.companies.forEach((company) => {
      console.log(`- ${company.name} (${company.id})`);
    });
    return result.companies;
  } else {
    console.error("Failed to list companies:", result.errors);
    return [];
  }
}

// Update a company
async function updateCompany(companyId) {
  const response = await fetch(`${baseUrl}/${TEAM_ID}/companies/${companyId}`, {
    method: "PUT",
    headers: {
      Authorization: auth,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Updated Test Company",
      address: "456 Updated Street",
      postalCode: "1000",
      city: "Brussels",
      country: "BE",
      enterpriseNumber: "0123456789",
      vatNumber: "BE0123456789",
    }),
  });

  const result = await response.json();
  if (result.success) {
    console.log("Company updated successfully");
    return true;
  } else {
    console.error("Failed to update company:", result.errors);
    return false;
  }
}

// Delete a company
async function deleteCompany(companyId) {
  const response = await fetch(`${baseUrl}/${TEAM_ID}/companies/${companyId}`, {
    method: "DELETE",
    headers: { Authorization: auth },
  });

  const result = await response.json();
  if (result.success) {
    console.log("Company deleted successfully");
    return true;
  } else {
    console.error("Failed to delete company:", result.errors);
    return false;
  }
}

// Example workflow
async function manageCompanies() {
  // List existing companies
  console.log("Existing companies:");
  await listCompanies();

  // Create a new company
  console.log("\nCreating a new company...");
  const companyId = await createCompany();
  if (!companyId) return;

  // List companies again to see the new one
  console.log("\nUpdated company list:");
  await listCompanies();

  // Update the company
  console.log("\nUpdating the company...");
  await updateCompany(companyId);

  // List companies again to see the update
  console.log("\nAfter update:");
  await listCompanies();

  // Delete the company
  console.log("\nDeleting the company...");
  await deleteCompany(companyId);

  // Final company list
  console.log("\nFinal company list:");
  await listCompanies();
}

// Run the workflow
manageCompanies().catch((error) => {
  console.error("Error in company management workflow:", error);
});

javascript

Best Practices

Check Peppol Registration: Before creating a company, check if the company is already registered in the Peppol network.
Validate data: Ensure company information is accurate before creating or updating
Handle errors: Implement proper error handling for API responses
Check before delete: Ensure a company is not in use before deleting it
Limit company creation: Create only the companies you need to avoid clutter

Documentation

API Reference

Documentation

API Reference

Overview

Prerequisites

Retrieving Your Team ID

Listing Companies

Creating a Company

Company Fields

Retrieving a Company

Updating a Company

Deleting a Company

Complete Example: Company Management

Best Practices

Next Steps