Enviar facturas a Chorus Pro

En Francia, todas las facturas a clientes del sector público deben enviarse electrónicamente a través de Chorus Pro, el portal oficial de facturación electrónica B2G del gobierno (Decreto n.° 2016-1478). Desde abril de 2020, esto se aplica a toda administración central, regional y local, tanto si eres una empresa francesa como un proveedor internacional.

Esta guía te muestra cómo usar la API de B2Brouter para:

1. Configurar tu cuenta de empresa (staging y producción).
2. Buscar entidades públicas por SIRET en el Directorio de B2Brouter.
3. Crear contacts de clientes y unidades organizativas.
4. Generar, enviar y rastrear tus facturas a través de Chorus Pro.
5. Descargar el archivo XML exacto enviado y confirmar la recepción.

Requisitos previos

• Empresa francesa con un número de TVA/SIRET válido.
• Entorno de pruebas (staging)
  • Regístrate en app-staging.b2brouter.net para probar la API.
  • Una vez registrado, abre un ticket de soporte en staging para solicitar tu clave API y permisos.
• Integración en producción y suscripción eDocExchange
  • Para pasar a producción, regístrate en app.b2brouter.net.
  • Suscríbete a un producto eDocExchange o contacta con nuestro equipo de ventas en https://www.b2brouter.net/global/contact/ para hablar sobre los planes, firmar tu contrato y recibir soporte de integración dedicado.

Obtener credenciales de la API

1. Inicia sesión en tu cuenta de B2Brouter.
2. Ve a la pestaña Developers.
3. Selecciona API Keys.
4. Haz clic en el icono del portapapeles para obtener tu token de API.

Identificador obligatorio: SIRET, no SIREN

Para facturar a través de Chorus Pro, tanto la empresa emisora como el cliente (la administración) deben identificarse con un SIRET (cin_scheme="0009"), nunca con un SIREN:

• Empresa emisora: si el país de la empresa es fr, hay que informar cin_value con un SIRET no vacío y cin_scheme igual a 9 ("0009"). Si falta el SIRET, o cin_scheme es distinto de 9, la factura no se envía.
• Cliente: el destinatario también debe identificarse con SIRET. Sin este identificador, la creación del contacto falla con el error “Chorus needs the SIRET identifier of the client”.

Coherencia jerárquica: aunque la facturación siempre es de SIRET a SIRET, la cuenta o contacto no debe ser “plano” a nivel SIRET. Mantén la misma jerarquía que en el circuito DGFiP: una matriz SIREN con el SIRET modelado como unidad organizativa (UO) (parent_id + cin_scheme="0009") bajo esa matriz (consulta Estructura de la cuenta). Si tu empresa ya tiene una cuenta de B2Brouter con matriz SIREN, crea el SIRET emisor como UO bajo esa matriz en lugar de una cuenta nueva independiente.

Recuperar o crear tu cuenta de empresa

1. Recuperar tu ID de 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 una cuenta de empresa (si es necesario)

Informa cin_scheme: "0009" y cin_value con el SIRET (14 dígitos) del establecimiento emisor. Es obligatorio para Chorus Pro: sin SIRET, o con cin_scheme distinto de 9, el envío de la factura falla.

Si tu empresa ya tiene una cuenta de B2Brouter a nivel de matriz SIREN (por ejemplo, para DGFiP), no crees una cuenta nueva e independiente con este SIRET: créala como UO con parent_id apuntando a la matriz, siguiendo los mismos pasos que Crear unidades organizativas en la guía DGFiP. El ejemplo siguiente es para una empresa que todavía no tiene ninguna cuenta en B2Brouter.

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,
      "cin_scheme": "0009",
      "cin_value": "45888033200017",
      "name": "Exemplar SAS",
      "address": "10 Rue Imaginaire",
      "city": "Paris",
      "postalcode": "75001",
      "province": "Île-de-France",
      "email": "john.doe@example.com"
    }
  }'

Verificar la información del destinatario

Puedes comprobar si el destinatario existe en nuestro directorio público:

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'

Esta consulta ya devuelve las unidades organizativas (códigos de servicio) existentes de la entidad en el directorio de Chorus Pro. No hace falta que las crees tú mismo como contacto: usa el cin1_scheme/cin1_value que ya aparece en el directorio.

Crear un contact

Versiones anteriores a 2025-10-13

Usa client en lugar de contact y /projects/{id}/clients.json en lugar de /accounts/{id}/contacts.

Al crear un cliente francés:

• Usa cin_value para el número SIRET-CODE. Es obligatorio: sin SIRET, Chorus Pro rechaza la factura con el error “Chorus needs the SIRET identifier of the client”.
• Usa cin_scheme para identificar la lista de Schemes. SIRET-CODE es 0009; no se acepta un SIREN (0002).
• transport_type_code debe ser fr.chorus.
• document_type_code debe 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 contact de unidad organizativa

Para facturar a un departamento o servicio específico, crea un sub-contact bajo la entidad principal usando parent_id e incluye el “código de servicio” 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 y enviar una factura

Al facturar a un cliente francés, asegúrate de proporcionar todos los campos obligatorios, incluyendo:

• number, date y due_date
• Al menos una invoice_lines_attributes con taxes_attributes
• contact_id o un objeto contact completo
• ponumber para identificar la referencia del pedido
• buyer_reference con el cin1_value (Code Service) para identificar el departamento destinatario

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

Comprobar el estado de la factura

Comprobar el estado de una única 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'

Comprobar el estado de varias facturas

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'

Actualizaciones de estado en tiempo real con webhooks

En lugar de hacer polling, suscríbete a notificaciones push mediante webhooks. Cada vez que cambie el estado de una factura, B2Brouter enviará un HTTP POST a tu endpoint.

Webhooks de estado de factura - Referencia de la API

Descargar el XML original de la factura

Después del envío, la respuesta de GET /invoices/{id} incluye un campo download_legal_url. Úsalo para obtener el archivo XML exacto enviado 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'

Como alternativa en un solo paso, puedes llamar directamente a GET /invoices/{id}/as/legal, sin obtener antes download_legal_url del payload de la factura. Devuelve el documento legal archivado tal como está almacenado y no genera ninguna transacción facturable — consulta Descargar facturas y Transaction: View_as.

Marcar la factura como confirmada

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'

Guías relacionadas

• DGFiP – Facturación electrónica y e-Reporting: circuito B2B doméstico francés, con un modelo de identificadores distinto (matriz SIREN + unidades organizativas SIRET).

Para más ayuda:

• Referencia de la API
• Soporte