Send invoices to Chorus Pro

In France, all invoices to public-sector clients must be submitted electronically via Chorus Pro, the government’s official B2G e-invoicing portal (Decree No. 2016-1478). Since April 2020, this applies to every central, regional and local administration—whether you’re a French company or an international supplier.

This guide shows you how to use the B2Brouter API to:

1. Set up your company account (staging & production).
2. Lookup public entities by SIRET in the B2Brouter Directory.
3. Create customer and organizational-unit contacts.
4. Generate, send, and track your invoices via Chorus Pro.
5. Download the exact XML file submitted and acknowledge.

Prerequisites

• French company with a valid VAT/SIRET number.
• Testing environment (staging)
  • Register at app-staging.b2brouter.net to try out the API.
  • Once registered, open a Support Ticket in staging to request your API key and permissions.
• Production integration & eDocExchange subscription
  • To go live, register at app.b2brouter.net.
  • Subscribe to an eDocExchange Product or contact our Sales team at https://www.b2brouter.net/global/contact/ to discuss plans, sign your contract, and receive dedicated integration support.

Obtaining API Credentials

1. Log in to your B2Brouter account.
2. Go to the Developers tab.
3. Select API Keys.
4. Click on the clipboard icon to retrieve your API token.

Retrieve or Create Your Company Account

1. Retrieve your Company ID

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts?offset=0&limit=25' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

2. Create a Company Account (if needed)

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts \
  --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 '{
    "account": {
      "country": "fr",
      "rounding_method": "half_up",
      "tin_value": "FR46458880332",
      "tin_scheme": 9957,
      "name": "Exemplar SAS",
      "address": "10 Rue Imaginaire",
      "city": "Paris",
      "postalcode": "75001",
      "province": "Île-de-France",
      "email": "john.doe@example.com"
    }
  }'

Verify recipient information

You can check if the recipient exists in our public directory:

curl --request GET \
  --url https://api-staging.b2brouter.net/directory/fr/0009/13001533200013 \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json'

Create a Contact

Versions prior to 2025-10-13

Use client instead of contact and /projects/{id}/clients.json instead of /accounts/{id}/contacts.

When creating a French customer:

• Use cin_value for SIRET-CODE number.
• Use cin_scheme to identify the Schemes Codelist. SIRET-CODE is 0009.
• transport_type_code should be fr.chorus.
• document_type_code should be xml.ubl.invoice.chorus.

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/contacts \
  --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 '{
    "contact": {
      "language": "en",
      "is_client": true,
      "is_provider": true,
      "terms": "custom",
      "public_sector": true,
      "name": "UNIVERSITE D AIX MARSEILLE",
      "address": "58 BD CHARLES LIVON",
      "city": "MARSEILLE 7",
      "postalcode": "13007",
      "country": "fr",
      "currency": "EUR",
      "transport_type_code": "fr.chorus",
      "document_type_code": "xml.ubl.invoice.chorus",
      "cin_value": "13001533200013",
      "cin_scheme": "0009"
    }
  }'

Create an Organizational Unit Contact

To bill a specific department or service, create a sub-contact under the main entity using parent_id and include the Chorus Pro “service code” (cin1_scheme / cin1_value).

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/contacts \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "contact": {
      "parent_id":   1313228381,
      "name":        "Factures marché FCM ROP cadre A2",
      "address":     "58 BD CHARLES LIVON",
      "city":        "MARSEILLE 7",
      "postalcode":  "13007",
      "country":     "fr",
      "cin1_scheme": "8017",
      "cin1_value":  "ESR_MISSION_FACTURES_DEPLACEMENTS"
    }
  }'

Create and Send an Invoice

When invoicing a French customer, ensure you provide all required fields including:

• number, date and due_date
• At least one invoice_lines_attributes with taxes_attributes
• contact_id or a complete contact object
• ponumber to identify the Order reference
• buyer_reference with the cin1_value (Code Service) to identify the target department

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'content-type: application/json' \
  --data '{
    "send_after_import": true,
    "invoice": {
      "type": "IssuedInvoice",
      "contact_id": 1313228399,
      "bank_account": {
        "type": "iban",
        "iban": "FR7630006000011234567890189"
      },
      "terms": "custom",
      "invoice_lines_attributes": [
        {
          "unit": 5,
          "quantity": 135,
          "price": 25,
          "description": "Cocktail Dinatoire",
          "taxes_attributes": [
            { "name": "TVA", "category": "S", "percent": 10 }
          ],
          "article_code": "14",
          "position": 1
        }
      ],
      "number": "00002",
      "date": "2025-06-18",
      "due_date": "2025-07-18",
      "currency": "EUR",
      "ponumber": "0123456",
      "buyer_reference": "ESR_MISSION_FACTURES_DEPLACEMENTS"
    }
  }'

Check Invoice Status

Check Single Invoice Status

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'

Check Multiple Invoices Status

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices?offset=0&limit=25&state_updated_at_from=2025-06-12' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Real-Time Status Updates with Webhooks

Instead of polling, subscribe to push notifications via webhooks. Whenever an invoice state changes, B2Brouter will send an HTTP POST to your endpoint.

Invoice Status WebHooks - API Reference

Download the Original Invoice XML

After sending, the GET /invoices/{id} response includes a download_legal_url field. Use it to fetch the exact XML file submitted to Chorus Pro:

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}' \
  --header 'Accept: application/xml'

Mark Invoice as Acknowledged

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

For further help:

• API Reference
• Support