Receive integrate and manage recieved invoices

This guide explains how to:

• Receive invoices through different channels (Peppol, email, b2brouter, uploads).
• Integrate received invoices in your system (JSON, PDF, original file).
• Manage invoice lifecycle (acknowledge, accept/refuse/paid, etc.).

Prerequisites

• A company with a valid Taxcode Identifier (TIN) or Company Identifier (CIN).
• A registered account on B2Brouter’s test environment: Register Here
• API permissions (Request via a support ticket: Open a Ticket)
• In case of doubt about the registration process, please refer to the User Guide.

If you still need to create the account or enable reception transports, follow:

• Getting started (account setup): https://developer.b2brouter.net/docs/setting_up_guide#/
• Transports guide: https://developer.b2brouter.net/docs/transports_guide/

Key concepts (avoid ID confusion)

• ACCOUNT_ID is used only in /accounts/{ACCOUNT_ID}/... endpoints.
• INVOICE_ID is the invoice identifier used in /invoices/{INVOICE_ID}... endpoints.
• In a received invoice, invoice.contact is the issuer/supplier (not your own account).

1) Ingest received invoices

1.1 Import a received invoice file (XML) (optional)

If you already have the received invoice file (for example, for testing, migrations, or backfills), you can import it with Import an invoice from a file. Use the query param issued=false to import it as a ReceivedInvoice.

It is also possible to generate a received invoice with JSON using the call Create an invoice, remember to inform "type": "ReceivedInvoice" when doing so.

1.2 Receive invoices through transports

Once transports are enabled for the account, invoices will arrive automatically (for example from Peppol or email).

2) List received invoices

Example request:

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices?type=ReceivedInvoice' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Sample response (excerpt):

{
  "invoices": [
    {
      "id": 105337,
      "number": "2",
      "state": "new",
      "total": 107.1,
      "currency": "EUR"
    },
    {
      "id": 105332,
      "number": "1",
      "state": "received",
      "total": 178.5,
      "currency": "EUR"
    }
  ],
  "total_count": 2,
  "offset": 0,
  "limit": 25
}

Received invoices may have different status: invoices imported will appear in state “new” and the ones received through different transports will normally appear in state “received”. They could also have “invalid” state if there is any validation issue.

To check all the available invoice states use the endpoint List of available invoice status.

3) Get invoice details

To get the invoice in JSON format use the Get an invoice endpoint. Add a Query Param to include lines information:

Example request:

curl --request GET \
  --url 'https://api-staging.b2brouter.net/invoices/{INVOICE_ID}?include=lines' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

4) Download the original invoice file

To download the original legal invoice that has been received:

Example request:

curl --request GET \
  --url https://api-staging.b2brouter.net/invoices/{INVOICE_ID}/as/original \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

You can also use document_type_code as pdf.invoice to generate a PDF view, or any other document_type_code from Get document types to get the invoice in any electronic invoice format.

5) Acknowledge the invoice

Use the endpoint Mark an invoice as acknowledged to prevent the invoice from being listed when getting the list of received invoices.

6) Switch invoice state

Switch the invoice state to inform the sender that you have “accepted”, “refused”, or “paid” the invoice. You can also mark the invoice as “annotated” for internal tracking purposes.

Use the Switch invoice state endpoint. You can add the Body Param reason to specify the reason of the rejection. If the invoice came from email, add the body param "commit": "with_mail" to inform the sender.

Example request:

curl --request POST \
  --url https://api-staging.b2brouter.net/invoices/{INVOICE_ID}/mark_as \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "state": "refused",
    "reason": "Missing PO number"
  }'

Sample Response:

204 No Content

For more details, consult the API Reference.