Skip to main content

​
Overview

To send or receive e-invoices, an organization needs to be registered on the e-invoicing network. Tesouro API allows you to automatically register your organizations on the PEPPOL e-invoicing network in just a few minutes. Once done, all e-invoices sent to the organization via PEPPOL will arrive directly to the organization’s accounts payable in Tesouro.

​
Requirements

  • The organization must be from a supported country.
  • The organization must not already be registered in PEPPOL through another platform.
Tesouro cannot provide e-invoicing to organizations that are already registered in PEPPOL. Such organizations need to terminate their registration at the previous PEPPOL access point before they can use e-invoicing via the Tesouro platform.

​
Considerations

Sandbox noteE-invoicing connections and organization PEPPOL IDs created in the sandbox environment are erased periodically and should be considered temporary. Other organization data in the sandbox - users, e-invoices, and so on - is preserved.

​
Roles and permissions

The /einvoicing-connections* endpoints mentioned in this guide can be called both with app tokens and organization user tokens. Organization users do not need any special permissions.

​
Register an organization in PEPPOL

Depending on the organization’s country, you can register the organization in PEPPOL using its business number or VAT number or both. Refer to the list of supported schemes.
If an organization has both the business number and VAT number, which one to use for PEPPOL registration?The country-specific regulations are as follows:
  • Belgium Peppol authority requires using the business number (KBO/BCE number) as the primary identifier.
  • Dutch Peppol authority recommends registering both KVK and VAT number.
In general, an organization can register multiple PEPPOL identifiers. This increases the organization’s discoverability on the PEPPOL network, and allows other businesses to send e-invoices to the organization using any of the registered identifiers. However, it comes with an additional maintenance burden to keep all of the registered identifiers up-to-date.
PEPPOL registration is usually immediate. Upon successful registration, the organization is added to the public PEPPOL directory at https://directory.peppol.eu/ (production) or https://test-directory.peppol.eu/ (sandbox). You can confirm the organization’s registration by looking it up in the corresponding directory.
Organization information in the PEPPOL directory

​
Register using VAT ID

If the organization’s VAT number has been added as a VAT ID in Tesouro, you can register the organization in PEPPOL using this VAT ID. To do this, call POST /einvoicing-connections and specify the UUID of the organization’s VAT ID and the address to be listed in the pubic PEPPOL directory. The address would typically be the same as the address specified in the organization object, but can be different if needed. 
curl -X POST 'https://api.sandbox.tesouro.com/v1/einvoicing-connections' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
        "address": {
            "address_line1": "Flughafenstrasse 52",
            "address_line2": "",
            "city": "Berlin",
            "country": "DE",
            "postal_code": "10115",
            "state": ""
        },
        "entity_vat_id_id": "d31b36f2-6148-4cd6-97d3-1fd90b5b0e7d"
    }'
  • The address of PEPPOL registration cannot be changed.
  • Tesouro does not validate addresses, VAT numbers, and business numbers for PEPPOL registration. You are responsible for the accuracy of the organization information.
The network scheme name for PEPPOL registration is inferred from the address.country specified in this request (rather than from the country of the VAT ID object). For example, DE:VAT for Germany or NL:VAT for the Netherlands. The PEPPOL ID assigned to the organization will be:
  • 9925:BE<vat number digits> for Belgium organizations, e.g. 9925:BE0123456789
  • 9944:NL<vat number> for Dutch organizations, e.g. 9944:NL123456789B12
  • 9930:DE<vat number digits> for German organizations, e.g. 9930:DE123456789
Note down the credentials[].id value returned in the response - you will need it later when creating e-invoices on behalf of this organization. 
{
  "id": "26835886-86f2-4020-ac62-07f423175ae9",
  "created_at": "2025-03-15T09:30:00Z",
  "updated_at": "2025-03-15T09:30:00Z",
  "address": {
    ...
  },
  "credentials": [
    {
      "id": "48d29385-e458-40ff-9429-7a857620d5db",
      "created_at": "2024-03-15T09:30:00Z",
      "updated_at": "2024-03-15T09:30:00Z",
      "einvoicing_connection_id": "26835886-86f2-4020-ac62-07f423175ae9",
      "network_credentials_identifier": "DE123456789",
      "network_credentials_schema": "DE:VAT"
    }
  ],
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "legal_name": "Acme GmbH",
  "status": "active",
  "provider_id": "343409"
}

​
Register other identifiers

This approach can be used to register an organization’s business number (such as Dutch KVK) as its PEPPOL identifier. If you have not created an e-invoicing connection for the organization yet, create one by calling POST /einvoicing-connections. In the request body, specify the organization’s address to be listed in the public PEPPOL directory. This address would typically be the same as the address specified in the organization object, but can be different if needed. 
curl -X POST 'https://api.sandbox.tesouro.com/v1/einvoicing-connections' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
        "address": {
            "address_line1": "Valeriusplein 122",
            "address_line2": "",
            "city": "Amsterdam",
            "country": "NL",
            "postal_code": "1075 BH",
            "state": ""
        }
    }'
This returns a Tesouro-assigned id of the e-invoicing network connection: 
{
  "id": "26835886-86f2-4020-ac62-07f423175ae9",
  ...
  "address": { ... },
  "credentials": [],
  "entity_id": "cde53f99-af05-41ac-a90b-f72c5b19a605",
  "legal_name": "Acme",
  "provider_id": "343409",
  "status": "pending"
}
Next, call POST /einvoicing-connections/{connection_id}/network-credentials and specify the PEPPOL scheme name and the organization’s identifier corresponding to that scheme: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/einvoicing-connections/26835...ae9/network-credentials' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
        "network_credentials_schema": "NL:KVK",
        "network_credentials_identifier": "12345678"
    }'
If the registration is successful, Tesouro returns an internal id of the organization’s PEPPOL identifier. You will need this id later when creating e-invoices on behalf of the organization. 
{
  "id": "8aad8984-cefa-423f-a371-8207d9cb2ad9",
  ...
  "einvoicing_connection_id": "26835886-86f2-4020-ac62-07f423175ae9",
  "network_credentials_identifier": "12345678",
  "network_credentials_schema": "NL:KVK"
}
The PEPPOL ID of the organization will be: 
<code>:<network_credentials_identifier>
where <code> is the ICD code corresponding to the network_credentials_schema used.

​
Registration errors

If the same VAT ID or business number is already registered in PEPPOL, the abovementioned API calls return an HTTP 422 error. You can usually encounter this error in the sandbox environment when trying to register random test identifiers that are already registered by other participants. 422 status is also returned if the specified identifier has incorrect length or format.
PEPPOL identifier already registered:
{
  "errors": [
    {
      "source": "identifier",
      "details": "already exists on the test PEPPOL network"
    }
  ]
}

{
  "errors": [
    {
      "source": "identifier",
      "details": "identifier '9930:DE123456789' already exists for mode 'pilot', usage 'usage_send_and_receive'"
    }
  ]
}
Incorrect identifier length:
{
  "errors": [
    {
      "source": "identifier",
      "details": "identifier '12345' ('0106:12345') does not match format '^\\d{6,9}$'"
    }
  ]
}

​
Check e-invoicing onboarding status

Organization registration in PEPPOL is usually immediate. After at least one PEPPOL identifier has been registered, the status of the e-invoicing connection will be active. This means the organization can both send and receive e-invoices. To check e-invoicing status, call GET /einvoicing-connections/{connection_id} and examine the status value in the response: 
{
  ...
  "address": { ... },
  "credentials": [
    {
      ...
      "network_credentials_identifier": "DE12345678",
      "network_credentials_schema": "DE:VAT"
    }
  ],
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "legal_name": "Acme GmbH",
  "status": "active",
  "provider_id": "12345"
}
The status can be pending if you called POST /einvoicing-connections with only address and did not register any PEPPOL identifier afterwards. This is indicated by an empty credentials array in the e-invoicing connection object. To resolve the issue, call POST /einvoicing-connections/{connection_id}/network-credentials to register a PEPPOL identifier for the organization. If the status is inactive or failed, contact us for assistance.

​
Update or remove a PEPPOL ID

Currently there is no way to update or remove existing PEPPOL IDs of an organization. As a workaround, you can delete the e-invoicing connection and re-create it with the correct PEPPOL IDs. However, this temporarily terminates the organization’s PEPPOL registration which may be undesirable.

​
Offboarding: Deregister an organization from PEPPOL

If an organization is no longer your customer or does not want to use e-invoicing through the Tesouro platform, you can offboard this organization by deleting its e-invoicing connection. To do this, call DELETE /einvoicing-connections/{einvoicing_connection_id}. This terminates the organization’s registration in PEPPOL, deletes its PEPPOL IDs, and removes the organization from the PEPPOL directory. The organization will no longer receive PEPPOL e-invoices into the Tesouro platform, and cannot send e-invoices as well. Deregistration is usually immediate but may take up to one hour.

​
What’s next

Once an organization has been registered in the PEPPOL network, it can: