Download invoices

When working with invoices, it is important to differentiate between:

• Legal invoice file: the final official file that was delivered (issued invoices) or received (received invoices).
• Original invoice file: the first file received by B2Brouter for that invoice (for issued invoices, this is typically an imported source file; for received invoices, this is the invoice received from the issuer).
• Exporting an invoice to a specific format: B2Brouter generates a document from the invoice data (it may differ from the legal/original file).
• Attachments: additional files linked to the invoice (PDFs, etc.). Attachments are not the invoice itself.

Depending on what you need, you will either:

• Call a direct download endpoint (for example, /invoices/{INVOICE_ID}/as/original or /invoices/{INVOICE_ID}/as/legal), or
• Use a download path returned in the invoice JSON (for example, download_legal_url or attachments[].link).

GET /invoices/{id}/as/legal returns the archived legal document (e.g. the signed and timestamped version) as stored, without regenerating it. Like /as/original, this call does not generate a billable transaction — see Transaction: View_as.

For an unattended process, such as an archive, a periodic synchronisation or the export of a whole history, call /invoices/{INVOICE_ID}/as/legal directly. It needs the invoice id only, it works for issued and for received invoices, and it avoids the pitfalls of download_legal_url described below. Export your invoice history shows the complete loop.

Prerequisites

• An API key with access to the invoice’s project/account.
• The internal B2Brouter invoice.id (you can obtain it from list endpoints).

Step 1: Get the invoice payload (optional but recommended)

Call Get invoice to retrieve the invoice JSON and locate the relevant fields:

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

This endpoint returns JSON only

The invoice endpoint does not serve the invoice as a file. On API versions 2025-10-13 and later, GET /invoices/{INVOICE_ID}.xml answers 406 Not Acceptable with the error code not_acceptable, and an Accept: application/xml header is ignored: the response is JSON anyway. To get the XML or the PDF of an invoice, use the download routes described below.

Issued invoices: legal file via download_legal_url (IssuedInvoice / IssuedSelfInvoice)

After an issued invoice is sent, the response includes download_legal_url, which points to the legal file delivered to the receiver (for example, the exact XML submitted to a network/platform, or the legal PDF).

The field has a value only for issued invoices (IssuedInvoice and IssuedSelfInvoice), and only once the invoice has been sent. In every other case, including every received invoice, the field is present with the value null (API version 2025-01-01 omits it). A null does not mean that the file is missing: for a received invoice, download it with /invoices/{INVOICE_ID}/as/original or /invoices/{INVOICE_ID}/as/legal, described below. Check the value of the field, not its presence.

download_legal_url is a relative path (not a full URL), for example:

{
  "invoice": {
    "download_legal_url": "/attachments/download/{ATTACHMENT_ID}/{FILENAME}"
  }
}

Use the path exactly as returned:

• {ATTACHMENT_ID} is the internal id of the stored file. It has no relation to the invoice id, the invoice number, the series or the date, and it cannot be calculated on your side.
• {FILENAME} is checked: the right id with a different filename answers 404 Not Found.

Received invoices: original/legal file via /invoices/{id}/as/original

For received invoices, the original file is also the legal file. Download it directly with:

GET /invoices/{INVOICE_ID}/as/original

Issued or received invoices: legal file via /invoices/{id}/as/legal

As a one-step alternative to download_legal_url, you can call /invoices/{INVOICE_ID}/as/legal directly for either issued or received invoices. It returns the archived legal document (e.g. the signed and timestamped version) as stored, without regenerating it:

GET /invoices/{INVOICE_ID}/as/legal

If the invoice has no legal document yet, for example an issued invoice that has not been sent, the call answers 422 with an error message that says so.

Attachments (both issued and received): attachments[].link

The invoice JSON can include an attachments array. Each entry contains a link you can use to download the stored attachment.

attachments[].link is a relative path (not a full URL), for example:

{
  "invoice": {
    "attachments": [
      {
        "link": "/attachments/download/{ATTACHMENT_ID}/{FILENAME}",
        "content_type": "application/pdf"
      }
    ]
  }
}

attachments[].link follows the same rule as download_legal_url: use it exactly as returned. The numeric segment is the id of the stored file and cannot be derived from the invoice, and the filename segment is checked.

For a deeper explanation of attachments and legal PDFs, see: Manage invoice attachments.

Step 2: Download the file

The URL fields returned by the API (download_legal_url, attachments[].link) are relative paths. Prefix them with your environment base URL, and change nothing else in the path.

Download using download_legal_url (issued invoices, legal)

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

Download using attachments[].link (attachments)

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

Download using /invoices/{id}/as/original (original)

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}'

Download using /invoices/{id}/as/legal (legal)

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

Notes

• For received invoices, /invoices/{INVOICE_ID}/as/original returns the file received from the issuer (original = legal).
• For received invoices, download_legal_url is null. That is expected: use /invoices/{INVOICE_ID}/as/original or /invoices/{INVOICE_ID}/as/legal.
• GET /invoices/{INVOICE_ID} returns JSON only. The invoice file comes from the download routes, not from a format suffix on this call.
• For issued invoices, /invoices/{INVOICE_ID}/as/original only works when the invoice has an original file (for example, imported XML). If the invoice was created directly from a JSON payload, there may be no original file to download.
• /invoices/{INVOICE_ID}/as/legal works for both issued and received invoices and does not require a prior call to fetch download_legal_url.
• Neither /as/original nor /as/legal generates a billable transaction, since no document regeneration takes place. See Transaction: View_as.

Related endpoints

• Get invoice
• Get an invoice with a specific document type
• Get received invoice (list)