Send e-invoices

Overview

Creating e-invoices in Monite is similar to creating regular invoices, with a few key differences.

One of the differences is that e-invoices go through additional statuses - issuing and (optionally) failed.

Before you begin

This guide assumes that:

• Both the entity (sender) and the counterpart (recipient) are from the supported countries.
• The entity has completed e-invoicing onboarding in Monite.
• Counterparts are already registered in the PEPPOL network through their access point of choice.
• The entity knows the counterpart’s PEPPOL ID.

How to create and send an e-invoice

1. Specify the counterpart’s PEPPOL ID

Before creating an e-invoice, the entity needs to specify the PEPPOL ID of its counterpart. Counterpart PEPPOL IDs can be filled in even before the entity has completed e-invoicing onboarding.

We assume that the counterparts have communicated their PEPPOL IDs to the entity in advance.

You can specify counterpart PEPPOL IDs in two ways:

• Specify the PEPPOL ID directly
• Add from VAT ID

If a counterpart has several PEPPOL IDs with different schemes, you can add them all and later have the entity users choose the PEPPOL ID to send the e-invoice to.

Specify PEPPOL ID directly

Companies usually share their PEPPOL IDs in the format <code>:<identifier>, such as 9930:DE087095777. To add this identifier to a counterpart, do the following:

1. Split the string by :.

   • The first element – a 4-digit number – is the scheme code. Use this table to convert this code to the scheme name.
   • The second element is the identifier.

2. Call POST /counterparts/{counterpart_id}/einvoicing_credentials. In the request body, provide the scheme name and identifier obtained on the previous step:

1
curl -X POST 'https://api.sandbox.monite.com/v1/counterparts/104db...443/einvoicing_credentials' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-ID: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "network_schema": "DE:VAT",
8
       "network_identifier": "DE087095777"
9
     }'

The response contains a Monite id assigned the counterpart’s PEPPOL ID. Note down this id - you will need it later when creating e-invoices for this counterpart.

1
{
2
  "id": "a0bb9d89-9064-4af8-affa-3be052d07594",
3
  "network_identifier": "DE087095777",
4
  "network_schema": "DE:VAT"
5
}

Add from VAT ID

If the counterpart has a VAT ID defined and you know that the counterpart is registered in PEPPOL using this VAT ID, you can send the id of the VAT ID object in the request to POST /counterparts/{counterpart_id}/einvoicing_credentials:

1
curl -X POST 'https://api.sandbox.monite.com/v1/counterparts/104db...443/einvoicing_credentials' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-ID: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "counterpart_vat_id_id": "ad01f529-0e93-4ee7-88b1-e67f1afee1a8"
8
     }'

In this case, Monite infers the scheme name (network_schema) of the PEPPOL ID from the country of the VAT ID object.

The response contains a Monite id assigned the counterpart’s PEPPOL ID. Note down this id - you will need it later when creating e-invoices for this counterpart.

1
{
2
  "id": "a0bb9d89-9064-4af8-affa-3be052d07594",
3
  "network_identifier": "087095777",
4
  "network_schema": "DE:VAT"
5
}

2. Create an e-invoice

Create a new draft invoice in the usual way, but with the following additional fields:

Example:

1
{
2
  "type": "invoice",
3
  "currency": "EUR",
4
  "counterpart_id": "104db547-6aa6-4e22-ad25-c2809ccbf443",
5
  "line_items": [
6
    ...
7
  ],
8
  ...
9
  "is_invoice": true,
10
  "network_credentials_id": "3c33e8af-d093-42d7-9269-66b32a679060",
11
  "counterpart_einvoicing_credentials_id": "a0bb9d89-9064-4af8-affa-3be052d07594"
12
}

The response returns the full invoice data, along with the PEPPOL ID details of the entity and counterpart:

1
{
2
  "id": "457fed28-7434-4578-8a01-ddcf51eed463",
3
  "type": "invoice",
4
  "status": "draft",
5
  ...
6
  "is_einvoice": true,
7
  "einvoice_error_comment": null,
8
  "network_credentials": {
9
    "id": "3c33e8af-d093-42d7-9269-66b32a679060",
10
    "network_identifier": "123456789",
11
    "network_schema": "DE:VAT"
12
  },
13
  "counterpart_network_credentials": {
14
    "id": "a0bb9d89-9064-4af8-affa-3be052d07594",
15
    "network_identifier": "087095777",
16
    "network_schema": "DE:VAT"
17
  }
18
}

3. Send an e-invoice

After a draft invoice has been finalized, call POST /receivables/{receivable_id}/issue to send the e-invoice through the e-invoicing network.

When an invoice has is_einvoice=true, the /receivables/{receivable_id}/issue endpoint works as follows:

1. Monite checks if the counterpart’s PEPPOL ID exists on the PEPPOL network. If not, /issue returns an HTTP 409 error containing a substring “No action taken”. The invoice remains in the draft status.

   Sample error if counterpart's PEPPOL ID is invalid

   1
   {
   2
     "error": {
   3
       "message": "An error occurred while sending E-invoice: {'errors': [{'source': 'routing', 'details': 'No action taken'}], 'guid': '4540dbdd-702e-48a2-9a0a-43affc68b63a'}"
   4
     }
   5
   }

2. Monite checks if all data required for an e-invoice is filled in. If not, /issue returns an HTTP 409 error and the invoice remains in the draft status.

   Users can fill in the missing data and attempt to send the e-invoice again.

   Sample error in case of incomplete e-invoice data

   1
   {
   2
     "error": {
   3
       "message": "An error occurred while sending E-invoice: {'errors': [{'source': '[:accountingSupplierParty]', 'details': 'Sending an invoice with VAT (or a taxExemptReason), but sender has no VAT number'}]}"
   4
     }
   5
   }

3. If the previous checks succeed, /issue returns HTTP 200 OK. The invoice is moved from the draft to issuing status, and the receivable.issuing webhook is triggered.

4. Monite attemts to send the document to the counterpart through the e-invoicing network.

5. If the e-invoice is successfully sent (that is, successfully routed to the counterpart’s PEPPOL access point):

   • Invoice status becomes issued and the receivable.issued webhook is triggered.
   • The rest of the invoice lifecycle applies as usual.

6. If the invoice failed to be sent via e-invoicing:

   • Invoice status becomes failed and the receivable.failed webhook is triggered.
   • The error message from the e-invoicing network is saved to the einvoice_error_comment field of the invoice.

Credit notes and e-invoicing

Credit notes inherit e-invoicing details (such as the counterpart’s PEPPOL ID) from the invoice they are based on. If the original invoice was configured for e-invoicing delivery, the credit note will also be sent via e-invoicing, and vice versa.

Like e-invoices, credit notes go through additional statuses when sent via e-invoicing.

Test e-invoicing

In the sandbox environment, send e-invoices and credit notes to the following test counterparts:

Dutch Peppol authority has additional guidelines for e-invoice testing in the Netherlands, in particular:

Sensitive data

In accordance with AVG/GDPR regulations test messages should not contain any references to personal information.

Any content of messages sent via the Peppol test infrastructure referring to personal information must be redacted or faked.

Limitations

• Units of measure in e-invoices are sent as the generic C62 code (“one”, “unit”) instead of the specific codes (such as hour, kg, or meter).