Enviar factures a Chorus Pro

A França, totes les factures dirigides a clients del sector públic s’han de presentar electrònicament a través de Chorus Pro, el portal oficial de facturació electrònica B2G del govern (Decret núm. 2016-1478). Des de l’abril de 2020, això s’aplica a totes les administracions centrals, regionals i locals, tant si sou una empresa francesa com un proveïdor internacional.

Aquesta guia mostra com utilitzar l’API de B2Brouter per:

1. Configurar el compte de la vostra empresa (staging i producció).
2. Cercar entitats públiques per SIRET al directori de B2Brouter.
3. Crear contactes de client i d’unitat organitzativa.
4. Generar, enviar i fer seguiment de les vostres factures a través de Chorus Pro.
5. Descarregar el fitxer XML exacte enviat i marcar-lo com a reconegut.

Prerequisits

• Empresa francesa amb un número de VAT/SIRET vàlid.
• Entorn de proves (staging)
  • Registreu-vos a app-staging.b2brouter.net per provar l’API.
  • Un cop registrats, obriu un tiquet de suport a staging per demanar la vostra clau API i permisos.
• Integració en producció i subscripció eDocExchange
  • Per passar a producció, registreu-vos a app.b2brouter.net.
  • Subscriviu-vos a un producte eDocExchange o contacteu amb el nostre equip comercial a https://www.b2brouter.net/global/contact/ per comentar els plans, signar el contracte i rebre suport d’integració dedicat.

Obtenir credencials API

1. Inicieu sessió al vostre compte de B2Brouter.
2. Aneu a la pestanya Developers.
3. Seleccioneu API Keys.
4. Feu clic a la icona del porta-retalls per recuperar el vostre token API.

Recuperar o crear el compte de la vostra empresa

1. Recuperar l’ID de l’empresa

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. Crear un compte d’empresa (si cal)

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

Verificar la informació del destinatari

Podeu comprovar si el destinatari existeix al nostre directori públic:

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'

Crear un contacte

Versions anteriors a 2025-10-13

Feu servir client en lloc de contact i /projects/{id}/clients.json en lloc de /accounts/{id}/contacts.

Quan creeu un client francès:

• Feu servir cin_value per al número SIRET-CODE.
• Feu servir cin_scheme per identificar la llista de codis d’esquemes. SIRET-CODE és 0009.
• transport_type_code hauria de ser fr.chorus.
• document_type_code hauria de ser 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"
    }
  }'

Crear un contacte d’unitat organitzativa

Per facturar a un departament o servei específic, creeu un subcontacte sota l’entitat principal amb parent_id i incloeu el “codi de servei” de Chorus Pro (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"
    }
  }'

Crear i enviar una factura

Quan factureu a un client francès, assegureu-vos de proporcionar tots els camps obligatoris, incloent-hi:

• number, date i due_date
• Almenys un invoice_lines_attributes amb taxes_attributes
• contact_id o bé un objecte contact complet
• ponumber per identificar la referència de la comanda
• buyer_reference amb el cin1_value (Code Service) per identificar el departament de destí

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

Comprovar l’estat de la factura

Comprovar l’estat d’una sola factura

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'

Comprovar l’estat de diverses factures

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'

Actualitzacions d’estat en temps real amb webhooks

En lloc de fer polling, podeu subscriure-us a notificacions push mitjançant webhooks. Cada vegada que canviï l’estat d’una factura, B2Brouter enviarà un HTTP POST al vostre endpoint.

Invoice Status WebHooks - API Reference

Descarregar l’XML original de la factura

Després de l’enviament, la resposta de GET /invoices/{id} inclou un camp download_legal_url. Feu-lo servir per obtenir el fitxer XML exacte enviat a 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'

Marcar la factura com a reconeguda

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'

Per a més ajuda:

• API Reference
• Support