Envoyer des factures à Chorus Pro

En France, toutes les factures adressées à des clients du secteur public doivent être soumises électroniquement via Chorus Pro, le portail officiel de facturation électronique B2G du gouvernement (décret n° 2016-1478). Depuis avril 2020, cela s’applique à toutes les administrations centrales, régionales et locales, que vous soyez une entreprise française ou un fournisseur international.

Ce guide montre comment utiliser l’API B2Brouter pour :

configurer le compte de votre entreprise (staging et production) ;
rechercher des entités publiques par SIRET dans le répertoire B2Brouter ;
créer des contacts clients et des contacts d’unités organisationnelles ;
générer, envoyer et suivre vos factures via Chorus Pro ;
télécharger le fichier XML exact soumis et l’accuser réception.

Prérequis

Entreprise française avec un numéro de TVA / SIRET valide.
Environnement de test (staging)
- Inscrivez-vous sur app-staging.b2brouter.net pour tester l’API.
- Une fois inscrit, ouvrez un ticket de support dans l’environnement de staging pour demander votre clé API et vos permissions.
Intégration de production et abonnement eDocExchange
- Pour passer en production, inscrivez-vous sur app.b2brouter.net.
- Souscrivez à un produit eDocExchange ou contactez notre équipe Sales via https://www.b2brouter.net/global/contact/ pour discuter des offres, signer votre contrat et bénéficier d’un accompagnement d’intégration dédié.

Obtenir les identifiants API

Connectez-vous à votre compte B2Brouter.
Allez dans l’onglet Developers.
Sélectionnez API Keys.
Cliquez sur l’icône clipboard pour récupérer votre token API.

Récupérer ou créer le compte de votre entreprise

1. Récupérer l’identifiant de votre entreprise

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. Créer un compte entreprise (si nécessaire)

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

Vérifier les informations du destinataire

Vous pouvez vérifier si le destinataire existe dans notre répertoire public :

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'

Créer un contact

Lors de la création d’un client français :

utilisez cin_value pour le numéro SIRET-CODE ;
utilisez cin_scheme pour identifier le Schemes Codelist. Le SIRET-CODE correspond à 0009 ;
transport_type_code doit être fr.chorus ;
document_type_code doit être 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"
    }
  }'

Créer un contact d’unité organisationnelle

Pour facturer un département ou un service spécifique, créez un sous-contact sous l’entité principale à l’aide de parent_id et incluez le « code service » 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"
    }
  }'

Créer et envoyer une facture

Lors de la facturation d’un client français, veillez à fournir tous les champs requis, notamment :

number, date et due_date
au moins un invoice_lines_attributes avec taxes_attributes
contact_id ou un objet contact complet
ponumber pour identifier la référence de commande
buyer_reference avec la valeur cin1_value (Code Service) pour identifier le service destinataire

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

Vérifier le statut de la facture

Vérifier le statut d’une facture

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'

Vérifier le statut de plusieurs 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'

Mises à jour de statut en temps réel avec les webhooks

Au lieu d’interroger l’API en boucle, abonnez-vous à des notifications push via des webhooks. Chaque fois que l’état d’une facture change, B2Brouter enverra un HTTP POST à votre point de terminaison.

Invoice Status WebHooks - API Reference

Télécharger le XML original de la facture

Après l’envoi, la réponse de GET /invoices/{id} inclut un champ download_legal_url. Utilisez-le pour récupérer le fichier XML exact soumis à 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'

Marquer la facture comme reconnue

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'

Pour aller plus loin :