DGFiP e-Invoicing i e-Reporting

Des del setembre de 2026, totes les empreses franceses han de rebre les seves factures a través d’una plataforma certificada, i les grans empreses i les ETI també hi han d’emetre les factures i declarar-hi les dades de TVA. Les PME i les microempreses ho hauran de fer a partir del setembre de 2027. B2Brouter ho simplifica: tu envies les dades de la factura amb una crida REST API, i B2Brouter s’encarrega del registre al PPF, la generació del document (UBL/CII/Factur-X), l’encaminament cap als teus clients i la declaració fiscal a la DGFiP, tot des d’una sola integració.

B2Brouter és una Plateforme Agréée (PA) certificada per a la reforma francesa de facturació electrònica de la DGFiP. Connecta’t via REST API i B2Brouter gestionarà per tu tota la capa de compliance:

Què fa B2Brouter per tu	Detalls
Registre al PPF	Publica automàticament el teu SIREN/SIRET a l’Annuaire quan actives el servei
Flux 1: facturació electrònica B2B	Genera UBL/CII/Factur-X, transmet al PPF i encaminа a la plataforma del receptor
Flux 6: cicle de vida de la factura	Gestiona els missatges d’estat CDAR (Déposée, Reçue, Approuvée, Refusée, Encaissée)
Flux 10: e-Reporting	Agrega operacions B2C i B2B transfrontereres (intra-UE i extra-UE) en Ledgers enviats al PPF amb la periodicitat que determina el vat_regime del teu Tax Report Setting
Recepció Peppol (esquema 0225)	Rep factures de qualsevol plataforma francesa o connectada a Peppol
Generació de documents	Tu envies dades de factura en JSON i B2Brouter genera el document UBL/CII/Factur-X compliant i el transmet al PPF. No cal que generis XML pel teu compte
Formats d’entrada	JSON REST API, Factur-X PDF/A-3 (amb CII XML incrustat), UBL 2.1 XML, CII XML
Arxiu legal	Tots els documents transmesos (factures, tax reports, missatges CDAR) s’emmagatzemen a B2Brouter durant el període legal obligatori de 10 anys. No cal cap infraestructura addicional al teu costat

El camí fins a la teva primera factura: crear el teu compte → activar DGFiP → crear un contacte → emetre la factura.

---

Context normatiu: La reforma francesa de facturació electrònica estableix que totes les empreses franceses han d’utilitzar una Plateforme Agréée (PA) certificada per transmetre factures i declarar dades de TVA a la DGFiP a partir del setembre de 2026 (setembre de 2027 per a l’emissió i l’e-reporting de les PME i microempreses). Des del 21 de febrer de 2026, l’art. 289 bis del CGI només preveu les plateformes agréées: el PPF (Portail Public de Facturation) de l’Estat ja no n’és una alternativa. Com a PA certificada, B2Brouter gestiona completament la connexió amb el PPF en nom teu: sense SFTP, sense certificats electrònics i sense cap integració directa amb el PPF.

Per a qui és aquesta guia?

Hi ha dos casos d’ús principals per integrar-se amb B2Brouter per a la facturació electrònica a França:

eDocExchange: per a empreses o grups d’empreses que integren directament el seu programari de gestió (ERP, plataforma comptable) amb B2Brouter. El procés d’onboarding (creació del compte, configuració de Tax Report Settings) normalment es fa una vegada per empresa des de la interfície web. L’operativa del dia a dia, com emetre factures i seguir-ne el cicle de vida, es fa via API. Per afegir més comptes d’empresa al teu grup d’integració, només cal seguir el mateix assistent d’onboarding des del mateix usuari de B2Brouter; no cal cap crida API separada.

eDocSync: per a vendors de programari i proveïdors ERP que volen oferir compliment DGFiP als seus clients des del seu propi producte. És el model white-label / embedded / marque blanche de B2Brouter: B2Brouter opera completament en segon pla, els clients finals només interactuen amb la interfície del vendor i no saben que B2Brouter hi és al darrere. El vendor és responsable del provisionament de comptes, l’enviament de factures i el seguiment del cicle de vida via l’API de B2Brouter. Els clients finals no necessiten login ni subscripció a B2Brouter.

Per a eDocSync, el volum de provisionament de comptes determina el pla adequat:

• Poques empreses (model reseller): afegeix cada empresa client com a compte dins del teu grup d’integració de B2Brouter des de la interfície web, seguint l’assistent estàndard. Funciona bé per a desenes d’empreses i comparteix una única API key.
• 100+ empreses: contacta amb el nostre equip comercial o obre un ticket de suport per parlar d’un pla eDocSync dedicat amb provisionament massiu.

En tots dos casos, totes les funcionalitats de compliance específiques de França (registre a l’Annuaire, transmissió Flux 1/6/10, cicle de vida CDAR) funcionen igual.

B2Brouter és una Plateforme Agréée: t’integres amb B2Brouter; no és un relay ni un connector cap a una altra PA. Si el teu SIREN ja està registrat amb una altra PA, activar el Tax Report Setting sobre el compte SIREN falla: et cal un codi de migració (consulta Canviar de PA). Per portar només un establiment i conservar aquell registre existent, consulta l’Escenari 2 a Estructura del compte. No pots utilitzar B2Brouter com a passarel·la per enviar factures sota la certificació d’una altra PA.

Encaminament a destinataris d’altres PA: quan el receptor està registrat amb una PA diferent, B2Brouter encamina la factura utilitzant el model estàndard Peppol de quatre cantonades (C2 → C3): el punt d’accés Peppol de B2Brouter (C2) consulta l’adreça Peppol del destinatari a l’Annuaire i entrega el document al punt d’accés del comprador (C3), independentment de quina PA utilitzi. No cal cap configuració extra al teu costat.

Entorns de prova: utilitza sandbox per a les primeres proves d’API i validació de payloads. Al sandbox les escriptures a l’Annuaire de la DGFiP se simulen: activar una Tax Report Setting no registra res al PPF, i per tant no et calen identificadors registrats al PPF. Ara bé, el SIREN i el SIRET han de superar igualment el dígit de control, perquè el sandbox corre a l’entorn de producció. Només staging accepta qualsevol número de 9 o 14 xifres. Per a proves completes end-to-end amb l’entorn QAS (qualification) de la DGFiP, utilitza l’entorn staging de B2Brouter, tal com s’explica a continuació.

Primera vegada amb l’API? Comença per la introducció a l’API: entorns, clau d’API i primera petició.

---

Abans de començar: tria el teu entorn

Entorn	App de B2Brouter	API de B2Brouter	Portal Chorus Pro
Producció	app.b2brouter.net	https://api.b2brouter.net	chorus-pro.gouv.fr
Staging (proves)	app-staging.b2brouter.net	https://api-staging.b2brouter.net	qualif.chorus-pro.gouv.fr

No barregis entorns. Producció utilitza números SIREN/SIRET reals i connecta amb l’Annuaire de producció de la DGFiP. Staging utilitza identificadors ficticis de prova i connecta amb l’entorn QAS de la DGFiP. API keys, comptes i contactes no es comparteixen entre entorns.

Opció A: Pilot en producció

El pilot a producció ja no està disponible, va finalitzar el dia 01.09.2026.

Registra’t a app.b2brouter.net per començar una integració en producció. Quan activis el DGFiP Tax Report Setting, el SIREN/SIRET de la teva empresa es publicarà a l’Annuaire real del PPF i serà visible per qualsevol plataforma de l’ecosistema francès de facturació electrònica.

Aquesta opció és per a factures B2B reals. Durant el pilot, abans del setembre de 2026, la DGFiP havia de netejar els registres del període QAS abans de l’entrada en vigor de la reforma, de manera que les factures enviades durant el pilot no generaven obligacions de compliment. És el millor punt de partida si ja has escollit B2Brouter i vols provar la integració completa amb dades reals de la teva empresa.

Opció B: Staging (recomanat per a avaluació)

Registra’t a app-staging.b2brouter.net per utilitzar l’entorn de proves de B2Brouter, connectat a l’entorn QAS de la DGFiP.

És la millor opció si:

• Estàs avaluant diverses plataformes abans de decidir-te
• El teu SIREN/SIRET ja està publicat a l’Annuaire amb una altra PA i encara no vols canviar de PA
• Prefereixes no associar l’identificador de la teva empresa amb activitat de proves

L’entorn staging és autoprovisionat: un cop tinguis identificadors de prova, pots començar proves end-to-end en menys de 24 hores.

Validació del SIRET a staging: a l’entorn staging, qualsevol número vàlid de 14 dígits s’accepta com a SIRET sense validar el checksum. Els identificadors ficticis del CSV QAS de Chorus Pro ja estan preregistrats a l’annuaire QAS de la DGFiP i funcionen end-to-end. En producció sí que es valida el format i checksum del SIRET.

Important: la DGFiP no permet SIREN ni SIRET reals al seu entorn QAS. Has d’utilitzar identificadors ficticis de prova. Pots obtenir-los tu mateix mitjançant el portal QAS de Chorus Pro (gratuït, procés d’uns 5 minuts) o demanar-ne un conjunt preassignat obrint un ticket de suport a l’app de staging.

Un compte per SIREN: B2Brouter crea un compte per SIREN i la clau del número de TVA es deriva del SIREN. Si proporciones un SIRET, se n’extreu el SIREN. Dos SIRET diferents de la mateixa empresa (mateix SIREN) es resolen com un mateix compte. Si la teva empresa opera des de diversos establiments (SIRET diferents), aquests es modelen com a unitats organitzatives dins del mateix compte de B2Brouter, no com a comptes separats. Contacta amb Support si necessites configurar facturació multiestabliment. Tingues-ho present quan seleccionis files del CSV: tria SIRET amb SIREN diferents (els primers 9 dígits) per a cada empresa independent que vulguis provar.

Obtenir identificadors de prova via Chorus Pro QAS

El portal Chorus Pro QAS et permet generar un “Matelas de données” (joc de dades), és a dir, un fitxer CSV amb identificadors ficticis SIREN/SIRET preregistrats a l’entorn de proves de la DGFiP. Segueix aquests passos:

1. Ves a qualif.chorus-pro.gouv.fr → pestanya Entreprise → Créer mon compte.
   • Pots utilitzar una adreça de correu temporal, com ara temp-mail.io.
   • Pots posar qualsevol nom; aquest compte només serveix per obtenir identificadors de prova.
2. Revisa la teva safata d’entrada per trobar el correu “Initialisation de mot de passe Chorus Pro” i defineix la teva contrasenya. L’enllaç és vàlid durant 60 minuts.
3. Inicia sessió → ves a Domaines → Matelas de données → fes clic a Générer un matelas de données i confirma.
4. Ves a Consultation du matelas de données. Espera fins que tots dos estats mostrin “Disponible”:
   • Statut pour Chorus Pro: Disponible
   • Statut pour l’annuaire de facturation PPF: Disponible
   • La generació acostuma a trigar pocs minuts. Refresca la pàgina per comprovar-ho.
5. Fes clic a “Générer et télécharger le fichier CSV du matelas structures et utilisateurs” per descarregar els teus identificadors de prova.

El CSV conté diversos números ficticis SIREN/SIRET en files etiquetades com “Privé” i “Public”. Utilitza només les files de la secció “Privé” per als teus comptes de prova. Les entitats del sector públic (SIREN 'Public') són rebutjades per l’annuaire QAS de la DGFiP; si intentes activar l’e-Reporting en un compte del sector públic rebràs un HTTP 422. És el comportament correcte: les entitats públiques utilitzen Chorus Pro directament, no una PA.

Utilitza un SIREN del sector privat per al compte emissor i un altre per al contacte de prova.

Un cop tinguis els identificadors de prova:

1. Registra’t a app-staging.b2brouter.net i activa el teu compte.
2. Crea el compte de la teva empresa utilitzant un SIREN del CSV (consulta Crear el compte de la teva empresa).
3. Subscriu-te a un pla eDocExchange. Les subscripcions a staging són simulades i no tenen cost.
4. Activa els DGFiP Tax Report Settings (consulta Activar el Tax Report Setting).
   • ⚠️ El registre de la teva empresa a l’Annuaire no és immediat: la publicació va amb la tramesa nocturna i queda activa l’endemà al matí, tant a staging com a producció. És el funcionament de la infraestructura DGFiP, no un retard de B2Brouter. Fins llavors no podràs enviar factures.
5. L’endemà, crea un contacte de prova amb un segon SIREN del CSV (consulta Crear un contacte).
6. Envia la teva primera factura (consulta Emetre factures).

Credencials API

L’autenticació utilitza una API key estàtica enviada a la capçalera HTTP X-B2B-API-Key. No hi ha cap flux OAuth2: genera la teva API key des de la interfície de B2Brouter a Settings → API Keys. Guarda-la de manera confidencial i no la incloguis mai en codi client-side. A més, estableix X-B2B-API-Version a cada petició.

Versió mínima de l’API: 2026-03-02

L’endpoint DGFiP Tax Report Settings i tots els camps específics de DGFiP requereixen X-B2B-API-Version: 2026-03-02 o posterior. Les versions anteriors no exposen aquests endpoints. Els endpoints d’invoices i accounts funcionen a partir de 2025-01-01.

Base URL: tots els exemples següents utilitzen https://api-staging.b2brouter.net. Per a producció, substitueix-lo per https://api.b2brouter.net.

---

Estructura del compte: matriu i unitats organitzatives

A França, cada empresa té un SIREN de 9 dígits que la identifica com a entitat legal, i cada establiment o servei té un SIRET de 14 dígits derivat d’aquell SIREN. B2Brouter segueix la mateixa jerarquia amb un compte matriu i, sota seu, una unitat organitzativa (UO) per cada establiment o servei. Les factures s’emeten des del compte matriu o des d’una UO concreta, segons l’establiment emissor.

Quins països cobreix aquesta guia. Les regles de compte d’aquesta guia (matriu i UO, identificadors, Tax Report Setting) són per a empreses establertes al territori de TVA francès: França (fr) i els DROM Guadalupe (gp), Martinica (mq) i La Reunió (re). Per a un emissor establert a qualsevol altre territori d’ultramar (Guaiana, Mayotte, Polinèsia Francesa, Nova Caledònia, Saint-Pierre-et-Miquelon…) aquesta guia no estableix la configuració del compte: contacta amb suport abans de crear-lo.

Precaució

Aquesta estructura no té relació amb els grups de comptes de B2Brouter. Les unitats organitzatives són establiments o seus d’un únic compte SIREN, no comptes independents d’un grup.

La regla d’or

El compte matriu sempre és un SIREN. Qualsevol SIRET, Code Routage o Suffix (consulta Identificadors i esquemes) es modela sempre com a UO sota aquell matriu, mai com a compte independent: és el que manté coherents els identificadors publicats del matriu i de les seves UOs.

Si crees un compte amb un SIRET, B2Brouter no el rebutja: en deriva el SIREN dels 9 primers dígits, crea el compte matriu si encara no existeix i hi penja el SIRET com a UO. El que et retorna la crida és la UO. Convertir un matriu existent a SIRET amb un PUT sí que retorna 422 parameter_matriu_must_be_siren.

Cada UO té el seu propi Tax Report Setting. Una UO mai declara a través del compte matriu: si no té el seu propi Tax Report Setting activat, no declara. Ara bé, en crear una UO sota un matriu que ja té la DGFiP activa, B2Brouter li clona un Tax Report Setting propi perquè comenci a declarar sense passos addicionals. Si no vols que declari, desactiva’l (enabled: false) un cop creada. Consulta Escenaris i casos per triar la teva configuració.

Contactes

La regla d’or també val per als contactes. Els contactes francesos (clients i proveïdors) segueixen la mateixa jerarquia i els mateixos cin_scheme: el contacte matriu és sempre el SIREN, i qualsevol SIRET, Code Routage o Suffix és una UO. El sistema admet tècnicament un contacte matriu amb un identificador diferent del SIREN, però fer-ho trenca les UOs que afegeixis després per al mateix client. Per crear-los, consulta Crear un contacte.

Comptes i contactes creats amb un SIRET com a matriu

• Comptes: fins al juliol de 2026 la plataforma permetia crear un compte matriu amb un SIRET. Cal normalitzar-los: substitueix l’identificador del matriu pel SIREN (cin_scheme="0002", cin_value = el SIREN de 9 dígits) i crea el SIRET corresponent com a UO sota aquell matriu.
• Contactes: fins al juny de 2026 passava el mateix amb els contactes. Normalitza’ls igual, posant el SIREN al contacte matriu i el SIRET com a UO sota aquell contacte.

Identificadors i esquemes

Identificadors a B2Brouter

A B2Brouter, els comptes, les unitats organitzatives i els contactes francesos es defineixen amb un identificador principal (cin_scheme + cin_value). Les UOs amb SIRET que tenen diversos serveis interns hi afegeixen un sub-identificador (routing_codes.cin1_scheme + routing_codes.cin1_value) per apuntar a un servei concret. Són dues coses diferents: el Suffix és un cin_scheme principal, mentre que el Code Routage va sempre al sub-identificador i mai com a cin_scheme principal.

Identificador principal del compte, UO o contacte (cin_scheme + cin_value):

cin_scheme	cin_value	Què representa	Exemple
0002 (2)	SIREN, 9 dígits + Luhn	Entitat legal	842917361
0009 (9)	SIRET, 14 dígits (SIREN + 5 dígits), amb dos controls Luhn: el dels 14 dígits i el del SIREN inicial	Establiment	84291736100011
8040	Suffix, alfanumèric [A-Za-z0-9_.-]{1,100}	UO sense SIRET propi	SUF01, ADMIN

La validació del SIREN i del SIRET és només aritmètica: B2Brouter no consulta el registre Sirene ni cap altre. Un número inventat que passa el control s’accepta, i pot coincidir amb el d’una empresa real. Per construir un parell de prova:

1. Tria 8 dígits i afegeix-hi el dígit de control Luhn: tens el SIREN.
2. Afegeix-hi 4 dígits d’establiment i el dígit de control Luhn calculat sobre els 13 dígits: tens el SIRET.

Tots els SIREN i SIRET d’aquesta pàgina passen els dos controls, per exemple 842917361 i 84291736100011.

Sub-identificador o routing code (routing_codes.cin1_scheme + routing_codes.cin1_value):

routing_codes.cin1_scheme	routing_codes.cin1_value	Què representa	Exemple
0224 (224)	Code Routage, alfanumèric [A-Za-z0-9_\-\/]+ (mínim 1 caràcter)	Servei dins un SIRET	COMPTA, SERV01, A123

Identificador publicat a l’Annuaire

A la xarxa Peppol, en canvi, el participant francès s’identifica sempre amb l’esquema 0225 (FRCTC Electronic Address), el codi reservat a les adreces electròniques franceses. El seu valor és sempre una composició publicada a l’Annuaire, mai un identificador sol: un SIRET sense el SIREN al davant no és publicable. Els schemes 0224 i 8040 no són esquemes Peppol: només serveixen per compondre aquest valor.

Identificador del participant Peppol (pin_scheme + pin_value):

pin_scheme	pin_value	Què representa
0225	SIREN	Entitat sencera (matriu)
0225	SIREN_SIRET	Establiment
0225	SIREN_SIRET_<CR>	Servei dins un establiment
0225	SIREN_<SUFFIX>	UO sense SIRET propi

Cada composició correspon a un o dos dels casos de la Taula de casos. Per veure els camps API que la generen, consulta Afegir els establiments com a unitats organitzatives.

---

Escenaris i casos

B2Brouter cobreix tres escenaris de configuració. Quin et correspon depèn de què vols fer des de B2Brouter. Si no saps si el teu SIREN ja està registrat amb una altra PA, consulta’l a l’Annuaire amb el Directory lookup.

Vols que el SIREN declari des de B2Brouter?

Resposta	Escenari	Què has de fer
Sí	Escenari 1. Declara tota l’empresa	Activa el Tax Report Setting al compte matriu SIREN. Els establiments, serveis i unitats internes es modelen amb els casos 1, 2 i 3. Si el SIREN ja està registrat amb una altra PA, primer l’has de migrar a B2Brouter amb un codi de migració (consulta Migrar des d’una altra PA o cap a una altra).
No, vull declarar un establiment concret des de B2Brouter	Escenari 2. Declara només un establiment	Crea l’establiment com a UO amb el SIRET i activa el Tax Report Setting només en aquesta UO, no al compte matriu SIREN. El registre del SIREN amb l’altra PA no es modifica. Casos 4 i 5.
No, només vull emetre des de B2Brouter	Escenari 3. Emet des de B2Brouter, rep a la teva PA	⚠️ Només disponible en una UO de Suffix: crea-la sota el SIREN i activa-hi el Tax Report Setting amb issue_only: true. La recepció es manté a l’altra PA. Cas 6, consulta Modes del Tax Report Setting.

Taula de casos

Cas	Unitat organitzativa (UO)	Tax Report Setting	Adreçament Annuaire (pin_value)	Quan et cal
1. Établissement Escenari 1	SIRET	Matriu:ON UO:ON1	SIREN_SIRET	Tens establiments i tots declaren des de l’empresa.
2. Service Escenari 1	SIRET + Code Routage	Matriu:ON UO:ON1	SIREN_SIRET_<CR>	Vols adreçar un departament concret dins d’un establiment.
3. Suffix Escenari 1	Suffix	Matriu:ON UO:ON1	SIREN_<SUFFIX>	Tens una unitat sense SIRET propi que ha de rebre i declarar amb adreça pròpia.
4. Établissement-only Escenari 2	SIRET	Matriu:OFF UO:ON	SIREN_SIRET	El SIREN ja està registrat amb una altra PA i només portes un establiment a B2Brouter.
5. Établissement-only + Service Escenari 2	SIRET + Code Routage	Matriu:OFF UO:ON	SIREN_SIRET_<CR>	Com el cas 4, però adreçant un departament dins d’aquell establiment.
6. Issue-only Escenari 3	Suffix amb issue_only2	Matriu:OFF UO:ON	SIREN_<SUFFIX>	Vols emetre des de B2Brouter mantenint la recepció a la teva PA actual.

¹ En crear una UO sota un matriu que ja té la DGFiP activa, B2Brouter li clona un Tax Report Setting propi. Consulta La regla d’or.

² Una UO de Suffix publica transport 0225 i rep factures com qualsevol altra adreça (cas 3). El que en treu la recepció és el flag issue_only del seu Tax Report Setting, que només s’accepta en una UO de Suffix (consulta Modes del Tax Report Setting).

---

Crear el compte de la teva empresa

Aquest apartat explica com crear el compte matriu amb el SIREN i com afegir-hi les unitats organitzatives. El model que hi ha al darrere és a Estructura del compte.

Crear el compte matriu amb el SIREN

Crea el compte amb POST /accounts. Si ja existeix, recupera’n l’id amb GET /accounts i salta’t la creació.

Camps específics d’un compte francès:

Camp	Valor	Finalitat
country	"fr"	Activa les validacions i l’encaminament FR
cin_scheme	"0002"	SIREN, l’entitat legal. El matriu és sempre SIREN: consulta La regla d’or per a què passa si hi envies un SIRET
cin_value	SIREN de 9 dígits	Identificador de l’empresa, validat amb Luhn
tin_scheme	9957	Codi ISO 6523 de l’identificador fiscal francès
tin_value	FR{kk}{siren}	Número de TVA que apareix a l’UBL. El checksum kk no l’has de calcular

Derivació entre SIREN i número de TVA

Si informes només un dels dos, B2Brouter deriva l’altre en crear el compte. Si no informes cap dels dos, el camp queda buit i l’emissió de factures falla.

Exemple de petició:

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 'Content-Type: application/json' \
  --data '{
    "account": {
      "country": "fr",
      "name": "Exemplar SAS",
      "address": "10 Rue Imaginaire",
      "city": "Paris",
      "postalcode": "75001",
      "province": "Île-de-France",
      "email": "john.doe@example.com",
      "tin_value": "FR22842917361",
      "tin_scheme": 9957,
      "cin_scheme": "0002",
      "cin_value": "842917361",
      "rounding_method": "half_up"
    }
  }'

Exemple de resposta:

{
  "account": {
    "id": 83428,
    "name": "Exemplar SAS",
    "tin_value": "FR22842917361",
    "tin_scheme": 9957,
    "cin_scheme": "0002",
    "cin_value": "842917361",
    "address": "10 Rue Imaginaire",
    "city": "Paris",
    "postalcode": "75001",
    "province": "Île-de-France",
    "country": "fr",
    "currency": "EUR",
    "email": "john.doe@example.com",
    "rounding_method": "half_up",
    "created_at": "2026-06-10T09:54:38.000Z",
    "updated_at": "2026-06-10T09:54:38.000Z"
  }
}

Afegir els establiments com a unitats organitzatives (opcional)

Versió mínima de l’API

Crear una UO passant parent_id requereix l’API 2026-06-26 o posterior; a les versions anteriors parent_id només és un camp de lectura. Per a comptes francesos tens una alternativa que funciona a qualsevol versió: crear el compte amb el SIRET i deixar que B2Brouter en derivi el matriu i la UO (consulta La regla d’or).

Si l’estructura de la teva empresa requereix UOs (consulta la taula de casos), crea cada UO amb POST /accounts afegint parent_id (l’ID del compte matriu que has creat abans).

Si el compte matriu ja té el Tax Report Setting de la DGFiP actiu, la UO nova en rep una còpia pròpia i comença a declarar tot seguit. Si no vols que declari, desactiva-li el Tax Report Setting (enabled: false) un cop creada (consulta La regla d’or).

Restriccions:

• Una UO no pot portar tin_value ni tin_scheme: els hereta del matriu i no s’han de repetir.
• Una UO no pot ser parent d’una altra UO: només hi ha un nivell de profunditat.

Camps obligatoris en tots els payloads UO:

Camp	Valor	Finalitat
parent_id	ID del compte matriu	Penja la UO del matriu SIREN: és el que la converteix en UO
cin_scheme i cin_value	Segons el tipus de UO	Identificador propi de la UO; consulta Camps de creació i resultat a l’Annuaire. Un SIRET comença sempre pels 9 dígits del SIREN matriu, per definició de l’INSEE: si el matriu és 842917361, els SIRETs vàlids tenen la forma 842917361XXXXX
country	"fr"	Activa les validacions i l’encaminament FR
email, address, city, postalcode, province	Dades de contacte i adreça de la UO	Obligatòries a qualsevol compte, també a les UOs

Camps de creació i resultat a l’Annuaire

Tipus de UO	Camps a enviar a POST /accounts	Resultat a l’Annuaire
Établissement (casos 1 i 4)	parent_id (matriu SIREN) + cin_scheme="0009" + cin_value=<SIRET>	SIREN_SIRET
Service (casos 2 i 5)	parent_id (matriu SIREN) + cin_scheme="0009" + cin_value=<SIRET> + routing_codes.cin1_scheme="224" + routing_codes.cin1_value=<CR>	SIREN_SIRET_<CR>
Suffix (casos 3 i 6)	parent_id (matriu SIREN) + cin_scheme="8040" + cin_value=<SUFFIX>	SIREN_<SUFFIX>

Què s’envia a cin_value

• Suffix: només el sufix (ADMIN), mai 842917361_ADMIN. B2Brouter hi prefixa el SIREN de la matriu i publica 842917361_ADMIN. Si envies el valor compost, el que es publica és 842917361_842917361_ADMIN, que no és l’adreça que has donat als teus proveïdors.
• Établissement: el SIRET sencer de 14 dígits (84291736100011), mai el NIC de 5 (00011). El SIRET es valida (14 dígits i dígit de control) en crear la UO.

Exemples de payload

Els casos 4, 5 i 6: el payload no els distingeix dels seus equivalents. El que canvia és on s’activa el Tax Report Setting i, al cas 6, el flag issue_only. Consulta Escenaris i casos.

Cas 1 i 2: UO de tipus Établissement amb Service opcional

Per a un establiment sense Code Routage (Cas 1), omet el bloc routing_codes.

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 'Content-Type: application/json' \
  --data '{
    "account": {
      "name": "Exemplar SAS, Sucursal Paris",
      "parent_id": {PARENT_ACCOUNT_ID},
      "cin_scheme": "0009",
      "cin_value": "84291736100011",
      "routing_codes": { "cin1_scheme": "224", "cin1_value": "COMPTA" },
      "country": "fr",
      "email": "sucursal-paris@example.com",
      "address": "1 Rue de la Paix",
      "city": "Paris",
      "postalcode": "75001",
      "province": "Île-de-France"
    }
  }'

Cas 3: UO de tipus Suffix

El payload del cas 6 (Issue-only) és idèntic al del cas 3: el que els diferencia no és el POST /accounts sinó el Tax Report Setting que hi actives després, amb issue_only: true. Aquest flag només s’accepta sobre una UO amb cin_scheme="8040". Consulta Modes del Tax Report Setting.

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 'Content-Type: application/json' \
  --data '{
    "account": {
      "name": "Exemplar SAS, Unitat Administrativa",
      "parent_id": {PARENT_ACCOUNT_ID},
      "cin_scheme": "8040",
      "cin_value": "SUF01",
      "country": "fr",
      "email": "admin-unit@example.com",
      "address": "1 Rue de la Paix",
      "city": "Paris",
      "postalcode": "75001",
      "province": "Île-de-France"
    }
  }'

---

Activar el Tax Report Setting

Disponible des de la versió 2026-03-02

Aquest és el pas clau de l’onboarding. Quan crees un Tax Report Setting amb code: "dgfip", B2Brouter:

1. Registra la teva empresa a l’Annuaire del PPF: el teu identificador passa a ser visible per a qualsevol plataforma de l’ecosistema francès de facturació electrònica.
2. Crea un transport Peppol 0225 (FRCTC Electronic Address): la teva empresa queda habilitada per rebre factures electròniques de qualsevol plataforma francesa connectada a Peppol.
   ⚠️ Si el compte sobre el qual actives ja té un transport Peppol, es substituirà pel nou transport 0225 durant l’activació.

Identificador ja registrat amb una altra PA: Si el SIREN sobre el qual actives estava registrat prèviament amb una altra PA, B2Brouter tancarà l’entrada existent a l’Annuaire i n’obrirà una de nova. Si necessites conservar aquell registre existent, no activis sobre el SIREN; activa sobre una UO SIRET (consulta “On activar” més avall). Actualitza qualsevol integració existent que faci referència a l’identificador de l’antic transport.

On activar el Tax Report Setting: {ACCOUNT_ID} pot ser el matriu SIREN, una UO SIRET, o tots dos. Cada compte (matriu o UO) que té Tax Report Setting propi es publica a l’Annuaire amb la seva pròpia adreça. Per a comptes del territori de TVA francès (FR, i els DROM GP/MQ/RE) no hi ha herència entre UO i matriu (consulta La regla d’or): sense Tax Report Setting propi la UO no declara, i amb un Tax Report Setting propi desactivat tampoc. Tres configuracions:

1. Tax Report Setting només al SIREN: l’empresa es publica com a SIREN (cas estàndard, Escenari 1). Les UOs noves sota aquest matriu reben automàticament un Tax Report Setting propi clonat en crear-se (consulta la nota següent), de manera que normalment també declaren.
2. Tax Report Setting al SIREN i a una o més UOs SIRET: l’empresa es publica alhora com a SIREN i com a cada SIREN_SIRET (una adreça d’Annuaire per compte activat). Tots els Tax Report Settings DGFiP actius del mateix SIREN han de compartir el mateix vat_regime: si n’actives un de diferent, la petició retorna 422 dgfip_vat_regime_taken_per_siren.
3. Tax Report Setting només a una UO SIRET, no al SIREN: només es publica aquell establiment (SIREN_SIRET); el SIREN no (Escenari 2). Usa-ho quan el SIREN ja està registrat amb una altra PA i vols conservar aquell registre.

Consulta Estructura del compte per al model complet.

Si crees una UO amb el matriu ja actiu: B2Brouter li crea automàticament el seu propi Tax Report Setting DGFiP (amb start_date de demà), perquè comenci a declarar sense passos addicionals. Si el matriu no té la DGFiP activa en aquell moment, la UO es crea sense cap Tax Report Setting; quan actives el matriu més endavant, la UO en rep un de propi. En cap cas la UO consulta el del matriu per declarar.

El start_date determina quan comença la declaració fiscal. A partir d’aquesta data, les factures que emetis generaran tax reports i es transmetran al PPF.

Exemple de petició:

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_report_settings \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report_setting": {
      "code": "dgfip",
      "start_date": "2026-10-01",
      "type_operation": "services",
      "vat_regime": "reel_normal_mensuel",
      "naf_code": "62",
      "enterprise_size": "eti",
      "email": "jane.doe@example.com"
    }
  }'

Resposta d’exemple:

{
  "tax_report_setting": {
    "code": "dgfip",
    "start_date": "2026-10-01",
    "auto_generate": true,
    "auto_send": true,
    "enabled": true,
    "type_operation": "services",
    "vat_regime": "reel_normal_mensuel",
    "naf_code": "62",
    "enterprise_size": "eti",
    "email": "jane.doe@example.com",
    "locked": false,
    "created_at": "2026-06-10T10:15:22.000Z",
    "updated_at": "2026-06-10T10:15:22.000Z"
  }
}

Camps de DGFiP Tax Report Settings

Camp	Tipus	Obligatori	Descripció
code	string	Sí	Ha de ser "dgfip".
start_date	date	No	Quan comença la declaració fiscal. Ha de ser demà o més tard: la data d’avui es refusa amb 422. Si s’omet, el valor per defecte és demà.
type_operation	string	Sí	Tipus d’operació per defecte per a aquesta empresa: "services", "goods" o "mixed". Determina el codi de procés DGFiP (S1/B1, etc.) utilitzat als tax reports. Tria "mixed" si l’empresa ven tant béns com serveis. En una factura mixta, el tax report del Flux 1 porta un codi de procés de la sèrie M (M1/M2/M4) i reporta tots els breakdowns (consulta Codis de procés). Aquest ajust es pot modificar després de l’activació.
naf_code	string	No	Opcional; només es valida si s’informa. El codi NAF/APE de l’empresa. És el codi de secció de 2 dígits assignat per l’INSEE que identifica l’activitat econòmica principal de l’empresa. La DGFiP l’utilitza per classificar la declaració fiscal.
enterprise_size	string	No	Opcional; només es valida si s’informa. La categoria de mida de l’empresa definida per l’INSEE. Valors admesos: "micro", "pme", "eti" o "ge".
vat_regime	string	Sí, tret que annuaire_only=true	El règim de TVA de l’empresa. Determina la freqüència de transmissió del Flux 10 (e-Reporting). Sense un vat_regime vàlid no es poden transmetre factures declarables: la petició retorna HTTP 422. Consulta la taula de règims.
reason_vat_exempt	string	No	Codi per defecte del motiu d’exempció de TVA per a l’empresa. Per defecte és "VATEX-FR-FRANCHISE".
email	string	No	Correu de contacte per a notificacions fiscals.
auto_generate	boolean	No	Sempre true per a DGFiP per obligació legal. No es pot canviar.
auto_send	boolean	No	Transmet automàticament els tax reports al PPF. Per defecte és true.
enabled	boolean	No	Indica si la configuració està activa. Per defecte és true. El registre a l’Annuaire només es produeix quan és true.
annuaire_only	boolean	No	Quan és true, el compte només es registra a l’Annuaire del PPF per a recepció. No es generen tax reports Flux 1 ni missatges CDAR, i vat_regime no és obligatori. Per defecte és false. Consulta Modes del Tax Report Setting.
issue_only	boolean	No	Quan és true, B2Brouter emet les teves factures i tax reports mentre la recepció es queda a la teva PA actual. Només s’accepta en una UO de Suffix (cin_scheme="8040"): en qualsevol altre compte la petició retorna 422 dgfip_issue_only_suffix_uo_only. Per defecte és false. Consulta issue_only.
peppol_email_fallback	boolean	No	Envia la factura per correu electrònic en format Factur-X quan el destinatari francès és a l’Annuaire però absent confirmat de Peppol. Per defecte és false: sense això, l’enviament es bloqueja. Consulta Emetre factures.

Règims de TVA i freqüència de transmissió

Règim	Descripció
reel_normal_mensuel	Transaccions cada deu dies (dies 1-10, 11-20, 21-fi de mes); pagaments mensualment.
reel_normal_trimestriel	Mensual.
simplifie	Mensual. Termini d’enviament: dia 26 del mes següent. Règim abolit el 2027-01-01; a partir d’aquesta data es tracta com reel_normal_trimestriel.
franchise_en_base	Bimensual (bimesos naturals: Gener-Febrer, Març-Abril, Maig-Juny, Juliol-Agost, Setembre-Octubre, Novembre-Desembre). Termini d’enviament: dia 26 del mes següent.

El dia 26 el fixem nosaltres

El termini del dia 26 dels règims simplifie i franchise_en_base és una decisió de B2Brouter, no un termini de la DGFiP: el dipòsit s’ha de fer abans de final de cada mes.

Si el registre a l’Annuaire falla, per exemple per SIREN/SIRET invàlid o per una caiguda temporal dels serveis DGFiP, la creació del Tax Report Setting es desfà i es retorna un error. Corregeix el problema i torna-ho a provar.

Tax Report Settings - API Reference

Modes del Tax Report Setting

Si has seguit els passos anteriors, ja tens el mode complet i no cal que llegeixis res més d’aquest apartat. Els altres dos modes són desviacions per a situacions concretes.

Mode	On viu el Tax Report Setting	Annuaire	Recepció Peppol 0225	Tax reports	Respostes (CDAR)
Complet (per defecte)	Matriu o UO	sí	sí	sí	s’envien i es reben
annuaire_only	Matriu o UO	sí	sí	no	no se n’envia cap
issue_only	Només UO de Suffix	sí	no (es queda a la PA actual)	sí	es reben si actives cdar al transport

El transport Peppol només-emissió no és un mode del Tax Report Setting: és el vehicle d’emissió que acompanya issue_only i es crea a part.

annuaire_only: només rebre

Quan et cal: la teva empresa encara no està obligada a emetre, però vols estar a l’Annuaire perquè els proveïdors et puguin enviar factures.

Registra l’empresa a l’Annuaire i crea el transport 0225 per a la recepció, però no genera tax reports ni envia missatges CDAR. El camp vat_regime no és obligatori en aquest mode.

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_report_settings \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report_setting": {
      "code": "dgfip",
      "start_date": "2026-10-01",
      "annuaire_only": true,
      "email": "jane.doe@example.com"
    }
  }'

Quan vulguis emetre, actualitza el Tax Report Setting a mode complet amb un PATCH.

issue_only: emetre des de B2Brouter mantenint la recepció on és

Quan et cal: vols emetre des d’una UO de Suffix a B2Brouter mantenint la recepció a la PA que ja té el teu SIREN. Si el que vols és endur-te’l, consulta Canviar de PA.

Aquest flag només s’accepta en una UO de Suffix (cin_scheme="8040") sota el matriu SIREN. Activar-lo sobre el matriu retorna 422 dgfip_issue_only_suffix_uo_only.

Per què només en una UO de Suffix

Un Suffix no és un identificador receptor de factures: penja d’un SIREN i no en pot rebre amb adreça pròpia, així que l’única configuració coherent és emetre sense rebre. El matriu i les UOs amb SIRET sí que ho són, i han de continuar rebent: si hi poguessis posar el flag, el compte es quedaria sense cap adreça on rebre les factures dels proveïdors.

En activar-lo, B2Brouter publica la teva línia a l’Annuaire de la PPF (el directori de l’administració francesa que encamina el Flux 1) amb l’adreçament SIREN_<SUFFIX>, però no crea cap transport Peppol. La línia que l’altra PA té publicada per al teu SIREN queda intacta: el que publiquis tu ho fas sota SIREN_<SUFFIX>, que és un identificador diferent.

Habilitar l’emissió Peppol

El transport l’has de crear tu per a la UO de Suffix, amb l’identificador compost i amb cdar com a únic tipus de document activat. Sense transport, el primer enviament falla amb 422 "To use Peppol Network you need to configure this connection to your account".

Tres camps són crítics:

• reception: true publica el Suffix a l’SML. Cal, perquè els CDAR arriben per Peppol i sense publicació no et trobarien.
• cdar: true, i cap altre tipus de document. És el que fa que el mode sigui issue-only: reps les respostes de les factures que emets, però no factures, que han de continuar arribant a la teva PA actual.
• pin_value ha de ser la composició {SIREN del matriu}_<SUFFIX> amb pin_scheme: 225, el mateix adreçament que B2Brouter ja ha publicat a la línia de l’Annuaire.

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{UO_ACCOUNT_ID}/transports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "transport": {
      "code": "peppol",
      "enabled": true,
      "reception": true,
      "cdar": true,
      "pin_scheme": 225,
      "pin_value": "842917361_SUF01"
    }
  }'

Queda un transport que emet i que només rep CDAR. El registre que l’altra PA té per al teu SIREN no es toca i segueix rebent les factures dels teus proveïdors.

Publicar el Suffix no et treu de l’altra PA

Els CDAR arriben per Peppol, o sigui que el Suffix ha d’estar publicat a l’SML perquè les respostes de les teves factures et trobin. Això no afecta l’altra PA: ella té publicat el SIREN i tu publiques SIREN_<SUFFIX>, que són participants Peppol diferents. El que et manté issue-only no és estar sense publicar, és tenir només cdar activat.

Si més endavant vols rebre també per B2Brouter, desactiva issue_only.

---

Canviar de PA

El canvi implica dos registres separats que es comporten de manera diferent:

• L’Annuaire l’actualitza sempre la PA que entra, no la que surt.
• El registre Peppol és el que pot bloquejar el canvi: un identificador només pot estar actiu amb un proveïdor alhora. Fins que el registre no es mogui o es doni de baixa, l’activació de la PA que entra falla amb 422.

Hi ha tres maneres de desbloquejar-lo:

• Amb codi de migració, el camí automàtic i el recomanat, perquè no talla el servei. L’emet sempre la PA que té l’identificador publicat en aquell moment, i el fa servir la PA que entra en activar. A B2Brouter el pots demanar en marxar (consulta Marxar de B2Brouter) i aportar-lo en arribar (consulta Venir a B2Brouter).
• Amb baixa de Peppol: la PA que surt despublica l’identificador de Peppol. Això l’allibera i la PA que entra ja pot activar, però et deixa sense servei fins que el torni a publicar. Consulta Despublicar, donar de baixa i migrar.
• Manualment, quan la PA que surt no ofereix cap de les dues: contacta amb la PA que entra, i és aquesta qui reclama el canvi a la que surt. Totes les PA franceses estan obligades a oferir aquest camí, així que no tenir codi no et deixa bloquejat (consulta Venir a B2Brouter).

Despublicar, donar de baixa i migrar

Tres operacions que sovint s’anomenen igual i tenen efectes diferents:

Operació	Efecte	Segueix registrat a l’SML?
Despublicar del directori de Peppol	Treu l’entrada del catàleg cercable	Sí, continua enviant i rebent
Despublicar de Peppol	Elimina el registre del participant a l’SML	No, és la baixa que allibera l’identificador
Migrar amb codi	Transfereix el registre a la PA nova sense donar-lo de baixa	Sí, sense interrupció

Només la segona allibera l’identificador. Mentre el registre de l’SML existeixi, activar el Tax Report Setting sobre aquell identificador seguirà fallant amb 422, encara que l’altra PA hagi despublicat el directori. És la confusió més habitual: si t’assegura que ja t’ha despublicat i l’activació continua fallant, demana-li que confirmi que ha eliminat el registre de l’SML i no només l’entrada del directori.

La comprovació que fa B2Brouter en activar és una consulta DNS en viu contra l’SML, no una consulta a una base de dades nostra. Per tant no hi ha cap termini garantit després d’una baixa, perquè la propagació depèn de l’SML i del DNS, però pots reintentar l’activació quan vulguis i obtindràs l’estat real d’aquell moment. El codi de migració evita tot això, perquè no passa per cap baixa.

Venir a B2Brouter

Activar el Tax Report Setting sobre un identificador que publica un altre proveïdor falla amb 422. Repeteix la mateixa crida afegint-hi el codi que t’hagi donat aquell proveïdor:

• POST /tax_report_settings amb peppol_migration_code. És la via principal per a França: mou l’identificador com a part de la mateixa activació.
• POST /transports o PUT /transports/{code} amb migration_code, si el que crees és el transport directament.

Tots dos camps són write-only i no surten a cap GET. Si el codi no serveix, la crida falla amb migration_code_malformed, migration_code_not_applicable o migration_code_rejected, aquest últim amb el motiu real de l’SML. No queda estat parcial: si la migració falla, el transport no es crea.

Si l’altra PA no t’ofereix codi ni et despublica, obre un tiquet de suport i iniciem el procediment manual per reclamar la teva portabilitat.

Marxar de B2Brouter

POST /accounts/{ACCOUNT_ID}/transports/peppol/migration_code retorna el codi que has de donar al proveïdor nou. És idempotent: repetir la crida torna el mateix codi fins que el cancel·lis amb DELETE al mateix camí, i un POST posterior en genera un de nou.

Retorna 409 not_published_by_b2brouter si el transport és només d’emissió, perquè aleshores l’identificador no el publiquem nosaltres.

El camp read-only migration_pending dels GET de transports diu si hi ha un codi emès i encara no cancel·lat. El codi en si no s’exposa mai en cap GET.

Limitacions

• A sandbox els codis de migració no estan disponibles: la crida retorna 409 migration_unavailable.
• Els països amb SMP centralitzat (Singapur, Malàisia) retornen 409.
• Cal permís d’edició sobre transports.

---

Crear un contacte

Un contacte B2B francès necessita identificadors d’encaminament i identificació fiscal.

Camp	Valor	Finalitat
cin_scheme	"0002" (SIREN, per defecte) o "0009" (SIRET, per adreçar un establiment concret)	Identificador de l’organització, utilitzat per cercar el destinatari a l’Annuaire
cin_value	SIREN o SIRET	Identificador registrat a l’Annuaire
tin_scheme	9957	Tax ID, codi ISO 6523 per a l’identificador fiscal francès
tin_value	FR{kk}{siren}	Número de TVA francès que apareix a l’UBL XML
pin_scheme	"0225"	EAS Peppol del participant FR (FRCTC Electronic Address), obligatori per a contactes francesos
pin_value	Composició Annuaire del destinatari	Identificador Peppol del contacte; segueix la mateixa composició que la matriu a l’Annuaire (SIREN, SIREN_SIRET, SIREN_SIRET_<CR> o SIREN_<SUFFIX>; consulta Identificadors i esquemes)
country	"fr"	Obligatori per a la lògica d’encaminament DGFiP
currency	"EUR"	Moneda per defecte per a les factures d’aquest contacte
transport_type_code	"peppol"	Recomanat per garantir l’entrega via xarxa Peppol
document_type_code	"xml.ubl.invoice.frcius.v1"	Recomanat: format de factura UBL France CIUS

Transport i tipus de document: per a contactes francesos registrats a l’Annuaire, recomanem establir explícitament transport_type_code: "peppol" i document_type_code: "xml.ubl.invoice.frcius.v1". Sense pin_value la creació retorna HTTP 422 (“Peppol Endpoint ID can’t be blank”). Pots verificar abans si un contacte està registrat a l’Annuaire fent servir el Directory lookup o el Peppol Directory oficial.

Contactes a Bèlgica, Alemanya i altres països de la UE: per a factures B2B a empreses no franceses, utilitza l’esquema nacional corresponent i el country adequat. Si el destinatari té un access point Peppol actiu, B2Brouter encaminarà la factura via Peppol BIS 3.0. Per a qualsevol transacció amb un contacte amb country diferent de "fr", es generarà automàticament Flux 10 d’e-Reporting transfronterer.

Exemple de petició:

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": {
      "name": "Client Exemple SARL",
      "address": "25 Avenue de la République",
      "city": "Lyon",
      "postalcode": "69001",
      "country": "fr",
      "currency": "EUR",
      "language": "fr",
      "cin_scheme": "0002",
      "cin_value": "987654324",
      "tin_scheme": 9957,
      "tin_value": "FR14987654324",
      "pin_scheme": "0225",
      "pin_value": "987654324",
      "transport_type_code": "peppol",
      "document_type_code": "xml.ubl.invoice.frcius.v1"
    }
  }'

POST Contact - API Reference

Adreçar un establiment concret: si el client té diversos establiments i cal identificar-ne un en particular, utilitza cin_scheme: "0009" amb el SIRET de 14 dígits i pin_value amb la composició SIREN_SIRET (p. ex. 987654324_98765432400019) en comptes del SIREN sol.

Contactes amb estructura multinivell: si el teu client té diversos establiments o serveis que cal identificar per separat, crea primer el contacte matriu a nivell SIREN i després afegeix UOs amb parent_id. Consulta Estructura del compte per a la regla d’or i les estructures aplicables.

Alternativa: contacte inline a la factura (sense el mòdul de contactes)

En comptes de crear un contacte per separat i referenciar-lo amb contact_id, pots enviar un objecte contact inline directament dins de POST /accounts/{ACCOUNT_ID}/invoices, amb totes les dades del receptor:

{
  "invoice": {
    "type": "IssuedInvoice",
    "contact": {
      "name": "Client Exemple SARL",
      "country": "fr",
      "currency": "EUR",
      "language": "fr",
      "cin_scheme": "0009",
      "cin_value": "98765432400019",
      "tin_scheme": 9957,
      "tin_value": "FR14987654324",
      "pin_scheme": "0225",
      "pin_value": "987654324_98765432400019",
      "transport_type_code": "peppol",
      "document_type_code": "xml.ubl.invoice.frcius.v1"
    }
  }
}

⚠️ Avís clau: passa sempre tots els identificadors correctes (tin / cin / pin) amb la composició FR correcta (matriu SIREN + UO), per no trencar la coherència matriu↔UO (consulta La regla d’or). Des de la versió d’API 2026-04-20, el sistema rebutja (422) un contacte inline no simplificat que no informi tin_value ni cin_value. currency i language són obligatoris a qualsevol contacte; sense aquests camps la creació falla igualment. El contacte inline també accepta routing_codes.cin1_scheme / routing_codes.cin1_value per identificar un servei dins un SIRET (Cas 2), amb els mateixos valors ("224" i el Code Routage) que en un contacte creat via el mòdul de contactes.

Opcional: verifica l’encaminament del destinatari (consulta al directori)

B2Brouter encamina les factures automàticament. Si vols inspeccionar com s’encaminarà un destinatari abans d’enviar, per exemple per confirmar si està registrat a l’Annuaire, utilitza la consulta al directori (Flux 11):

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

Resposta asíncrona disponible a partir de la versió 2026-06-26

Per a contactes francesos, la primera crida pot retornar HTTP 202 amb un polling_url. Repeteix la petició a aquesta URL fins obtenir HTTP 200 amb les dades resoltes.

Resposta resolta: exemple:

{
  "external_company": {
    "country": "fr",
    "cin_scheme": "0009",
    "cin_value": "98765432400019",
    "information_flags": ["FR_ASSUJETTI_ACTIVE"],
    "source": ["peppol", "annuaire"]
  }
}

Camps específics de França:

Camp	Valors	Significat
information_flags	FR_ASSUJETTI_ACTIVE	Destinatari registrat i actiu a l’Annuaire del PPF
	FR_ASSUJETTI_INACTIVE	Destinatari amb registre fora de vigència o sense PA assignada
	FR_ASSUJETTI_UNKNOWN	El PPF no té informació concloent (per exemple, 404)
source	array de "peppol", "annuaire"	Orígens consultats. Si apareixen tots dos, B2Brouter ha trobat el destinatari a ambdós directoris

Aquesta consulta és informativa: B2Brouter ja resol l’encaminament automàticament en crear la factura (consulta Verificació a l’Annuaire i generació de tax reports). Fes-la servir per inspeccionar abans d’enviar o per pintar l’estat del destinatari a la teva UI. No garanteix l’encaminament que es farà servir realment a l’enviament: si el destinatari resulta no localitzable a Peppol, per defecte l’enviament es bloqueja, o es degrada a correu electrònic si el compte ha activat el fallback Peppol → correu. Consulta la nota més avall.

GET Lookup Directory - API Reference

Verificació a l’Annuaire i generació de tax reports

B2Brouter verifica automàticament si els contactes francesos (country: "fr") estan registrats a l’Annuaire de la DGFiP. Aquesta verificació determina el flux de declaració fiscal:

• Contacte registrat a l’Annuaire (in_dgfip_annuaire: true o encara no verificat): la factura genera un tax report de Flux 1.
• Contacte NO registrat a l’Annuaire (in_dgfip_annuaire: false): la factura no genera tax report. Això evita enviaments Flux 1 invàlids a destinataris que el PPF no pot encaminar.
• Contacte encara no verificat (in_dgfip_annuaire: nil): B2Brouter és permissiu; la factura continua i genera tax report. La verificació es fa de manera asíncrona en segon pla.

Si crees un contacte francès i immediatament hi envies una factura, és possible que la verificació de l’Annuaire encara no hagi acabat. És intencionat: B2Brouter no bloqueja la creació de factures mentre la verificació està pendent. Si després resulta que el contacte no està registrat, les futures factures cap a aquest contacte no generaran tax reports Flux 1 fins que el contacte es registri en una PA.

La comprovació de l’Annuaire només s’aplica a contactes francesos domèstics (country: "fr"). Els contactes no francesos sempre segueixen el camí d’e-Reporting Flux 10 independentment de l’estat de l’Annuaire.

Important: ambdues empreses a l’Annuaire DGFiP: per a un enviament FR → FR amb tax report Flux 1, tant l’emissor com el receptor han d’estar registrats a l’Annuaire de la DGFiP. Si una de les dues no hi és, el tax report no es pot completar i la factura s’envia sense declaració.

Com comprovar la inscripció a l’Annuaire DGFiP:

• Producció → facturation.chorus-pro.gouv.fr/annuaire
• Staging (QAS) → qas.facturation.chorus-pro.gouv.fr/annuaire

⚠️ La web annuaire-entreprises.data.gouv.fr és per a dades fiscals generals; no garanteix la inscripció a l’Annuaire DGFiP: són bases diferents.

Des del setembre de 2026 aquest comportament permissiu ja no s’aplica: les declaracions fallen si l’identificador no consta com a activable a la DGFiP, encara que el SIREN/SIRET sigui vàlid.

---

Emetre factures

Un cop la teva empresa ha completat l’onboarding i el DGFiP Tax Report Setting està activat, la creació de factures funciona mitjançant l’Invoice API estàndard, POST /accounts/{ACCOUNT_ID}/invoices. B2Brouter gestiona automàticament tots els requisits específics de França: generació de tax reports, format UBL/CII/Factur-X i transmissió al PPF via Flux 1.

Utilitza send_after_import: true per crear i transmetre en un sol pas. Estableix-lo a false si vols crear la factura primer i revisar-la abans d’enviar-la; en aquest cas, la factura quedarà en estat new fins que en desencadenis la transmissió amb una crida separada o des de la interfície de B2Brouter.

Data de la factura
Per a comptes amb DGFiP Tax Report Setting actiu, la date de la factura no pot ser una data futura. Si es passa una data posterior a avui, l’enviament retorna HTTP 422 (“Only invoices with today’s date are allowed”). Els exemples d’aquesta guia usen dates fictícies; substitueix-les per la data actual quan facis proves.

Número de factura
⚠️ El number, amb la sèrie inclosa, pot tenir fins a 35 caràcters (regla BR-FR-01). B2Brouter ho valida en crear la factura: un número més llarg o amb caràcters no permesos retorna HTTP 422. El límit de 20 caràcters només s’aplica a les factures B2G per a Chorus Pro.

Facturació seqüencial
L’API processa una factura per petició. En escenaris batch o massius, itera sobre la llista de factures i crida l’endpoint per a cada document. L’API admet peticions concurrents, de manera que pots paral·lelitzar múltiples POSTs.

Factura B2B estàndard

El cas més habitual: una factura B2B domèstica francesa amb TVA estàndard del 20%.

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": 1313228381,
      "number": "FA-2026-0048",
      "date": "2026-09-15",
      "due_date": "2026-10-15",
      "currency": "EUR",
      "payment_method": 4,
      "bank_account_id": {YOUR_BANK_ACCOUNT_ID},
      "remittance_information": "FA-2026-0048",
      "payment_method_text": "Virement bancaire",
      "payment_terms": "Net 30 jours à compter de la date de facture.",
      "invoice_lines_attributes": [
        {
          "quantity": 10.0,
          "description": "Consulting services — architecture review",
          "price": 150.0,
          "unit": 9,
          "taxes_attributes": [
            { "name": "TVA", "percent": 20.0, "category": "S" }
          ]
        },
        {
          "quantity": 5.0,
          "description": "Training sessions — API integration",
          "price": 200.0,
          "unit": 9,
          "taxes_attributes": [
            { "name": "TVA", "percent": 20.0, "category": "S" }
          ]
        }
      ]
    }
  }'

L’array tax_report_ids de la resposta conté l’ID del tax report generat. Fes-lo servir per seguir el cicle de vida de l’enviament.

POST Invoice - API Reference

Camps específics de França a les factures

Informació de pagament

Els camps de pagament només porten dades de pagament:

Camp	EN 16931	Descripció	Obligatori
remittance_information	BT-83	Referència de pagament (per exemple, el número de factura)	No
payment_method_text	BT-82	Descripció textual del mètode de pagament	No
payment_terms	BT-20	Condicions de pagament (venciment, descompte per pagament anticipat que concedeixes, etc.)	No
bank_account_id	—	Id del compte bancari associat al teu compte de B2Brouter. Obligatori quan payment_method és transferència bancària (codi 4)	Sí, si pagament per transferència

Aquests camps no es fan servir mai com a menció legal. No hi escriguis les penalitzacions per retard, la indemnització de 40 € ni la menció de descompte: envia-les com a mencions legals de pagament.

Una factura amb un import a pagar positiu necessita due_date o payment_terms (regla BR-CO-25). Sense cap dels dos, la petició retorna HTTP 422 («Due date can’t be blank»).

Bank account: crea primer un bank account associat al teu compte (des de la interfície web o via API) i referencia el seu id a la factura amb bank_account_id. El bank account inclou IBAN i BIC i és l’únic lloc on han d’anar: no els escriguis a payment_method_text ni en una menció legal.

Mencions legals de pagament (PMD, PMT, AAB)

Les factures franceses porten tres mencions legals de pagament com a notes de factura amb codi de tema (BT-21), una nota per codi (regles BR-FR-05 i BR-FR-06):

Codi	Menció	Text per defecte
PMD	Penalitzacions per retard en el pagament (pénalités de retard)	Tout retard de paiement engendre une pénalité exigible à compter de la date d’échéance, calculée sur la base de trois fois le taux d’intérêt légal.
PMT	Indemnització forfetària de 40 € per despeses de cobrament (indemnité forfaitaire)	Indemnité forfaitaire pour frais de recouvrement en cas de retard de paiement : 40 €.
AAB	Descompte per pagament anticipat, o que no n’hi ha (escompte)	Les règlements reçus avant la date d’échéance ne donneront pas lieu à escompte.

Les mencions són opcionals a la petició. Si no n’envies una, B2Brouter hi posa el text per defecte. Envia el teu text quan el text per defecte no s’ajusti a les teves condicions, per exemple quan apliques un tipus de penalització concret o quan concedeixes un descompte per pagament anticipat: sense la teva menció AAB, la factura diu que no hi ha descompte, encara que els teus payment_terms diguin el contrari.

Com enviar-les depèn de la versió de l’API:

• Versió de l’API 2026-06-26 o posterior: fes servir l’atribut coded_notes, amb una entrada per menció.

  "coded_notes": [
    { "subject_code": "PMD", "text": "Pénalités de retard : 12 % annuel, exigibles dès le lendemain de la date d'échéance." },
    { "subject_code": "PMT", "text": "Indemnité forfaitaire pour frais de recouvrement : 40 €." },
    { "subject_code": "AAB", "text": "Escompte de 2 % pour paiement sous 10 jours." }
  ]

  En actualitzar, només canvien els codis que envies: cada codi enviat substitueix les notes de la factura amb aquell codi, i les altres notes es conserven. Per eliminar una menció, envia el codi amb _destroy: { "subject_code": "AAB", "_destroy": true }. Un array buit, o no enviar l’atribut, deixa les notes com estaven. coded_notes també accepta altres codis UNTDID 4451 (per exemple REG, AAI, TXD, o ABL per a les mencions legals de l’empresa com el RCS i el capital social, regla BR-FR-07), que surten com a notes pròpies. ACC no s’accepta: fes servir fa_clauses.

• Versions anteriors: escriu les mencions com a etiquetes a extra_info:

  #PMD#Pénalités de retard : 12 % annuel, exigibles dès le lendemain de la date d'échéance. #PMT#Indemnité forfaitaire pour frais de recouvrement : 40 €. #AAB#Escompte de 2 % pour paiement sous 10 jours.

Per a cada codi, B2Brouter agafa el text de l’entrada de coded_notes; si no n’hi ha, de l’etiqueta d’extra_info; i si tampoc n’hi ha, fa servir el text per defecte.

En una factura que s’envia en un format francès, la petició retorna HTTP 422 quan:

• el mateix codi (PMD, PMT, AAB o TXD) apareix més d’un cop (BR-FR-06);
• el text de PMT o AAB supera els 255 caràcters;
• una entrada de coded_notes no té subject_code o no té text.

Importació des d’altres formats (UBL, CII, Factur-X): no cal que facis res. Cada nota PMD, PMT o AAB del fitxer es conserva com a nota pròpia amb el mateix text, i PaymentID (BT-83) i PaymentTerms (BT-20) conserven els seus valors.

Línies exemptes de TVA (categoria E)

Quan una línia té category: "E" (exempta de TVA), també has de proporcionar un comment amb el codi d’exempció VATEX-FR-CGI261-* aplicable.

⚠️ Bloqueig silenciós: si s’omet comment en una línia de categoria E, la factura es crea però mai no es transmet al PPF. La resposta contindrà un array errors no buit, així que cal revisar-lo fins i tot en respostes exitoses.

Codis d’exempció de TVA DGFiP

Codi	Referència legal	Categoria	Descripció
VATEX-FR-FRANCHISE	Art. 293 B CGI	E	Franchise en base de TVA. S’envia al PPF com a Z
VATEX-FR-CNWVAT	—	E	Avoir net de taxe — nota de crèdit sense TVA (el proveïdor renuncia a l’ajust de la TVA). Només notes de crèdit (261/381/396, regla G6.21)
VATEX-FR-AE	—	AE	Autoliquidació
VATEX-FR-CGI261-1	Art. 261-1° CGI	E	Cures i serveis mèdics
VATEX-FR-CGI261-2	Art. 261-2° CGI	E	Serveis paramèdics
VATEX-FR-CGI261-3	Art. 261-3° CGI	E	Ensenyament escolar, universitari i formació professional
VATEX-EU-F / -I / -J	—	E	Règim de la marge (margin scheme)

Codis d’exempció de nivell UE: a més dels codis nacionals VATEX-FR-* de dalt, la DGFiP també accepta la llista VATEX-EU-* (extensions UNCL5305 / EN16931). El règim de la marge utilitza VATEX-EU-F, VATEX-EU-I o VATEX-EU-J en una línia de categoria E. Indica el codi aplicable al comment de la línia.

Franchise en base de TVA (VATEX-FR-FRANCHISE)

Les factures en franchise en base de TVA porten la categoria E amb el codi d’exempció VATEX-FR-FRANCHISE (regla BR-FR-CO-16). Per a aquestes factures, estableix percent: 0.0, category: "E" i comment: "VATEX-FR-FRANCHISE" a cada línia d’impost. La factura manté la categoria E: B2Brouter només la transcodifica a Z a les dades que envia al PPF (regla BR-FR-MAP-08).

{
  "taxes_attributes": [
    {
      "name": "TVA",
      "percent": 0.0,
      "category": "E",
      "comment": "VATEX-FR-FRANCHISE"
    }
  ]
}

Operacions fora del camp de la TVA (categoria O)

Algunes operacions queden fora del camp d’aplicació de la TVA i han de portar la categoria O amb percent: 0.0, no la categoria E (exempta) ni Z (tipus zero). Dos casos habituals:

• Détaxe (operacions fora del camp de la TVA): la línia no porta TVA.
• Débours (despeses reembossables avançades en nom del client): es traspassen sense TVA.

{
  "taxes_attributes": [
    { "name": "TVA", "percent": 0.0, "category": "O" }
  ]
}

El tax report del Flux 1 sintetitza automàticament el TaxSubtotal de categoria O corresponent. La categoria NS també s’accepta i es transcodifica a O.

Nota de crèdit

Des de la versió d’API 2026-04-20, per emetre una nota de crèdit referencia la factura original amb invoice_references:

"invoice_references": [
  {
    "reference_type": "amend",
    "number": "FA-2026-0048",
    "date": "2026-09-15",
    "reason": "Annule et remplace",
    "correction_method": "01"
  }
]

B2Brouter generarà un UBL CreditNote amb codi de tipus 381 i inclourà la referència de facturació.

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": 1313228381,
      "number": "NC-2026-001",
      "date": "2026-09-25",
      "due_date": "2026-10-25",
      "is_credit_note": true,
      "invoice_references": [
        {
          "reference_type": "amend",
          "number": "FA-2026-0048",
          "date": "2026-09-15",
          "reason": "Annule et remplace",
          "correction_method": "01"
        }
      ],
      "currency": "EUR",
      "payment_method": 4,
      "bank_account_id": {YOUR_BANK_ACCOUNT_ID},
      "remittance_information": "Pénalités de retard : trois fois le taux d'intérêt légal.",
      "payment_method_text": "Indemnité forfaitaire pour frais de recouvrement en cas de retard de paiement : 40 €.",
      "payment_terms": "Pas d'escompte pour paiement anticipé.",
      "invoice_lines_attributes": [
        {
          "quantity": -1.0,
          "description": "Annulation partielle — Consulting services",
          "price": 500.0,
          "unit": 9,
          "taxes_attributes": [
            { "name": "TVA", "percent": 20.0, "category": "S" }
          ]
        }
      ]
    }
  }'

Camps legacy: en versions d’API anteriors a 2026-04-20, la nota de crèdit s’expressava amb is_amend: true + amended_number + amended_date en comptes de invoice_references. Aquests camps continuen sent acceptats en aquelles versions per compatibilitat, però queden com a legacy: per a integracions noves, utilitza invoice_references.

Codis de procés

El codi de procés determina el flux cadre del PPF. B2Brouter l’assigna automàticament segons type_operation del Tax Report Setting i les característiques de la factura. Per indicar un codi concret (per exemple S7 o B7), envia transaction_type_code a la factura.

Codi de procés	Tipus d’operació	Descripció
S1	Services	Factura estàndard de serveis
B1	Goods	Factura estàndard de béns
M1	Mixed	Factura estàndard d’operacions mixtes
S2	Services	Factura pagada de serveis
B2	Goods	Factura pagada de béns
M2	Mixed	Factura pagada d’operacions mixtes
S4	Services	Factura amb bestretes (serveis)
B4	Goods	Factura amb bestretes (béns)
M4	Mixed	Factura amb bestretes (mixt)
S7	Services	TVA ja recaptada (serveis): venda ja declarada per e-reporting B2C (o a la declaració de TVA) i facturada després a una empresa. Consulta el cas 30
B7	Goods	TVA ja recaptada (béns): venda ja declarada per e-reporting B2C (o a la declaració de TVA) i facturada després a una empresa. Consulta el cas 30

Factures mixtes al Flux 1: amb type_operation: "mixed", el tax report del Flux 1 porta M1, M2 o M4 i reporta tots els breakdowns de la factura. No hi ha codi M7: una factura mixta amb la TVA ja declarada per e-reporting B2C porta S7. La regla de declarar només els serveis s’aplica a les dades de cobrament (212), no al Flux 1.

Formats de document

Document Type Code	Format	Descripció
xml.ubl.invoice.frcius.v1	UBL XML	Factura Peppol France CIUS (Flux 1 / Annuaire)
xml.cii.cross_industry_invoice.frcius.v1	CII XML	Factura France CIUS CII
xml.cii.cross_industry_invoice.facturx.fr.all_profiles.v1	Factur-X (CII XML)	Factura France CIUS Factur-X (tots els perfils)

Fallback Peppol → correu opcional per a destinataris francesos (opt-in)

Per defecte, quan el destinatari és un contacte francès registrat a l’Annuaire però la consulta del seu participant SMP a Peppol confirma que hi és absent, B2Brouter bloqueja l’enviament amb un error de validació peppol_endpoint_not_registered_to_receive, tant si el contacte té document_type_code desat com si no. Per fer que B2Brouter redirigeixi la factura a correu electrònic en el seu lloc, cal establir peppol_email_fallback: true al Tax Report Setting de DGFiP del compte amb un PATCH; també disponible com a casella a ⚙ Configuració del compte → e-Reporting France.

Amb el fallback activat:

• La factura s’envia per correu electrònic, en format Factur-X France CIUS (EN 16931, amb les mencions franceses, com el mode de facturació BT-23). La configuració del contacte no canvia, i el tax report del Flux 1 es diposita igualment pel circuit SFTP de la DGFiP, independentment del transport utilitzat.
• Senyal: to_net informa "email" a la factura enviada, i document_type_code reflecteix el format realment utilitzat, fixat en el moment de l’emissió.
• Sense senyal previ: continua sense haver-hi manera de saber que una factura es redirigirà abans d’enviar-la. Només es pot detectar després a partir de to_net.
• Els identificadors mal formats fallen en silenci: un BT-49 (Peppol Endpoint ID) incorrecte o irresoluble es classifica com a “no localitzat a Peppol” i es degrada a correu sense error. Verifica amb cura els identificadors dels teus contactes.

Amb el fallback desactivat (l’estat per defecte), aquell mateix BT-49 mal format o irresoluble es mostra com l’error de validació de bloqueig anterior, de manera que el detectes abans que la factura s’emeti.

Importació de Factur-X i UBL XML

Si el teu sistema ja genera factures Factur-X o UBL XML, pots enviar-les directament amb l’endpoint d’importació:

POST /accounts/{id}/invoices/import

Estableix Content-Type a:

• application/pdf per a Factur-X
• application/xml per a UBL 2.1 o CII XML independents

---

Cicle de vida de la factura

França fa servir un model en Y (5 cantonades), no de clearance. La factura es transmet al receptor independentment que es registri un informe fiscal Flux 1; el PPF no valida prèviament les factures abans que arribin al receptor. La Factura i l’Informe fiscal són cicles de vida separats que només coincideixen en el lliurament del Flux 1. Un error en l’informe fiscal no desfà una factura que ja ha arribat al receptor.

Factures al sector públic

Si la factura s’envia pel transport fr.chorus, no es genera cap tax report ni cap CDV: Chorus Pro gestiona tot el cicle de vida. Si una factura a una administració s’envia per Peppol, en canvi, la declaració de Flux 1 sí que es fa, com a qualsevol factura B2B. Consulta Enviar factures a Chorus Pro (B2G).

Estats ↔ CDV de factura emesa

Estat	CDV	Origen	Descripció
sending	—	B2Brouter (C1)	La factura s’ha creat i està en cua per transmetre’s al PPF
sent	200:Déposée	B2Brouter (C2)	La factura s’ha enviat al receptor i al PPF correctament
registered	202:Reçue	Receptor (C3)	El sistema del receptor ha rebut la factura
read	204:Prise en charge	Receptor (C4)	El receptor ha visualitzat la factura
accepted	205:Approuvée	Receptor (C4)	El receptor ha aprovat la factura
accepted1	206:Approuvée partiellement	Receptor (C4)	El receptor ha aprovat la factura parcialment
annotated	207:En litige	Receptor (C4)	El receptor ha posat la factura en litigi
refused	210:Refusée	Receptor (C4)	El receptor ha rebutjat la factura2
paid	212:Encaissée	Emissor (C1)	Has registrat el cobrament de la factura. B2Brouter envia el 212 només per a prestacions de serveis. Consulta Estat Encaissée: confirmació de pagament.
error	—	Divers	La validació prèvia o la transmissió han fallat. El camp errors conté el motiu. Consulta Com gestionar factures amb error.

¹ El CDV 206 fixa el mateix estat que el 205: accepted. L’estat de la factura no distingeix una aprovació total d’una de parcial. L’import que ha aprovat el receptor queda registrat com a metadada de l’esdeveniment corresponent, no com a camp de la factura.
² El payload de la factura porta refuse_reason_code amb el motiu estructurat del rebuig.

Com gestionar factures amb error

Abans de l’enviament:
Perquè una factura es pugui enviar, ha de passar la validació del schematron. Si no la passa, l’enviament retorna HTTP 422, la factura queda en estat error i no es crea cap tax report. El missatge cita el codi de la regla que ha fallat, per exemple G1.24 per a un tipus de TVA no vàlid. El camp errors conté el motiu del rebuig, edita la factura amb un PATCH i torna-la a enviar, o elimina-la i crea’n una de nova. No hi ha cap endpoint de reintent: el camí és corregir i reenviar.

Després de l’enviament:
DELETE i PATCH retornen 422: la factura és dins el cicle de vida del receptor i la correcció es fa amb una nota de crèdit. L’excepció és el dipòsit fallit: mentre tots els seus tax reports estiguin en estat error o refused i la factura no hagi arribat al receptor, encara la pots corregir amb un PATCH i tornar-la a enviar. DELETE continua retornant 422: una factura amb un tax report, en qualsevol estat, no es pot eliminar.

Seguiment dels estats de factura

Webhooks (recomanat)

Configura endpoints de webhook des de la interfície de B2Brouter a Pestanya Developers → Webhooks. Un cop configurats, B2Brouter enviarà un HTTP POST al teu endpoint cada vegada que la factura arribi a un nou estat.

Invoice Status WebHooks - API Reference

Polling

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

GET Invoice - API Reference

Descarregar el document original de la factura

Quan una factura arriba a l’estat sent, la resposta de GET /invoices/{id} inclou el camp download_legal_url. Fes-lo servir per descarregar el document de factura que s’ha transmès.

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

Com a alternativa en un sol pas, pots cridar directament GET /invoices/{id}/as/legal, sense haver d’obtenir primer download_legal_url del payload de la factura. Retorna el document legal arxivat tal com està emmagatzemat i no genera cap transacció facturable. Consulta Descarregar factures i Transaction: View_as.

Estat Encaissée: confirmació de pagament

Encaissée és l’últim estat del cicle CDV d’una factura B2B francesa. No l’envia el receptor sinó l’emissor: B2Brouter l’envia en nom teu quan registres un cobrament de la factura (consulta el mapping CDV complet a la taula Estats de factura). Segons l’art. 41 septies G de l’annex IV del CGI, només correspon a les prestacions de serveis: B2Brouter no l’envia per als lliuraments de béns ni per als breakdowns amb autoliquidació (categoria AE), i en una factura mixta només declara els breakdowns de serveis. En una factura rebuda, marcar-la com a pagada envia el 211 al proveïdor (consulta Com respondre).

B2Brouter propaga la confirmació de pagament al PPF per una de dues vies, segons la naturalesa de la factura:

Cas	Branca	Mecanisme
Domèstic FR → FR (B2Brouter detecta company.country == "fr" i contact.country == "fr")	CDAR	Envia un missatge CDV 212 (transició d’estat) sense generar tax report addicional
Cross-border (B2B intra-UE / extra-UE) o B2C (IssuedSimplifiedInvoice)	Flux 10 fitxer C	Genera un tax report al Ledger C (payments) (consulta Model de 3 ledgers)

Marcar una factura com a pagada via API

Quan el cobrament està confirmat, marca la factura al PPF amb una crida al mark_as:

curl --request POST \
  --url https://api-staging.b2brouter.net/invoices/{INVOICE_ID}/mark_as \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{"state":"paid"}'

Pagaments parcials

Els pagaments parcials es registren amb l’endpoint POST /accounts/{ACCOUNT_ID}/payments, indicant amount i invoice_id. Repeteix la crida per cada pagament que rebis; quan la suma dels imports registrats cobreix el total de la factura, aquesta passa automàticament a l’estat paid.

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/payments \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "payment": {
      "invoice_id": {INVOICE_ID},
      "amount": 900.00
    }
  }'

Requereix X-B2B-API-Version: 2026-03-02 o posterior.

Per a un pagament complet en una sola operació, també pots fer servir directament mark_as amb state: "paid" (consulta Marcar una factura com a pagada via API); no cal passar primer per POST /accounts/{ACCOUNT_ID}/payments.

Alternativament, pots gestionar els cobraments des de l’app de B2Brouter: obre la factura → Crear cobrament → defineix l’import pagat.

Notes sobre pagaments:

• Pots passar full: true en lloc d’amount per registrar el pagament complet pendent: B2Brouter calcula l’import pendent en el moment d’executar la crida i mai supera el total de la factura. Si en canvi indiques un amount explícit, no hi ha cap protecció contra el sobrepagament: és responsabilitat teva no superar el total pendent.
• Esborrar un pagament no reobre la factura: es queda a l’estat paid.
• Si el pagament ha generat un tax report de Flux 10 (factura cross-border o B2C), el PUT/DELETE d’aquell pagament retorna HTTP 422 pel bloqueig de la declaració ja enviada. El cas domèstic FR-FR (CDV 212, sense tax report addicional) no té aquest bloqueig.

---

Recepció de factures

Com a empresa francesa registrada a l’Annuaire amb transport Peppol 0225, rebràs automàticament factures electròniques d’altres plataformes franceses i connectades a Peppol.

Respondre una factura rebuda

Com a receptor, respons amb POST /invoices/{id}/mark_as. La mecànica general del mark_as, comuna a tots els països, és a Canviar l’estat de la factura.

Cada transició d’estat emet el CDV corresponent cap a l’emissor. Els rebutjos automàtics (213) en són l’excepció: no demanen cap crida, perquè B2Brouter deriva el codi de motiu de la DGFiP dels errors de validació (REJ_COH si no n’hi ha cap per classificar).

Com respondre: crida, estat i CDV

Estat	CDV	Crida	Descripció
read	204:Prise en charge	state: "read"	Prens en càrrec la factura
accepted	205:Approuvée	state: "accepted"	Aproves la factura
accepted	206:Approuvée partiellement	state: "accepted" + amount + amount_code1 + reason	Aproves la factura parcialment
annotated	207:En litige	state: "annotated" + dispute: true2 + reason	Poses la factura en litigi
refused	210:Refusée	state: "refused" + reason_code3	Rebutges la factura
paid	211:Paiement transmis	state: "paid"	Avises el proveïdor que has pagat la factura. No s’envia a la DGFiP

El reason és obligatori en els casos 206 i 207: sense ell, la crida retorna 422.

¹ Els valors d’amount_code són MAP, MAPTTC, MNA i MNATTC.
² Sense dispute: true, l’estat annotated només comptabilitza internament i no envia cap CDV.
³ El reason_code és opcional a la crida, però el 210 sempre porta un motiu: si no l’envies, B2Brouter hi posa NON_CONFORME. Consulta Codis de refús.

Exemple de petició d’aprovació parcial:

curl --request POST \
  --url https://api-staging.b2brouter.net/invoices/{INVOICE_ID}/mark_as \
  --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 '{
    "state": "accepted",
    "amount": 250.00,
    "amount_code": "MAP",
    "reason": "Una línia no correspon a la comanda"
  }'

Codis de refús

Quan refuses una factura pots afegir un reason_code amb el motiu estructurat de la DGFiP: ADR_ERR, REF_CT_ABSENT, CMD_ERR, TX_TVA_ERR, MONTANTTOTAL_ERR, CALCUL_ERR, DOUBLON, NON_CONFORME, DEST_ERR, TRANSAC_INC, EMMET_INC, CONTRAT_TERM i DOUBLE_FACT.

L’API també accepta AUTRE, però la DGFiP no el permet en un refús.

La DGFiP rebutja un refús sense comentari. Si no envies cap reason, B2Brouter escriu el comentari a partir de l’etiqueta oficial del reason_code, o del codi per defecte NON_CONFORME si no n’envies cap, i l’historial de la factura mostra «Comentari del rebuig generat a partir del codi de motiu». A l’aplicació web el motiu és obligatori.

Exemple de petició:

POST /invoices/{id}/mark_as
{
  "state": "refused",
  "reason": "Incorrect total amount",
  "reason_code": "MONTANTTOTAL_ERR"
}

Exemple de resposta (extracte):

{
  "invoice": {
    "id": 12345,
    "state": "refused",
    "refuse_reason": "Incorrect total amount",
    "refuse_reason_code": "MONTANTTOTAL_ERR"
  }
}

POST mark_as - API Reference

---

Comprovar l’estat d’un tax report

El tax report segueix el cicle de vida tècnic de l’enviament al PPF. Tant la generació de l’XML com la transmissió al PPF són asíncrones.

Flux 1: Factures B2B domèstiques

Estat	Descripció
new	Tax report creat i en cua per a transmissió
sent	Document dipositat al PPF via SFTP
acknowledged	El PPF ha rebut i validat el fitxer
registered	Estat terminal: factura acceptada i registrada per la DGFiP
refused	Estat terminal: rebutjada per la DGFiP
error	Estat terminal: error de transmissió o processament

Flux 10: Factures B2B transfrontereres i B2C (e-Reporting)

Estat	Descripció
new	Tax report creat i acumulat per al batch diari de ledger
sent	Ledger dipositat al PPF via SFTP
acknowledged	El PPF ha rebut el ledger
registered	Estat terminal: ledger acceptat i registrat per la DGFiP
refused	Estat terminal: ledger rebutjat per la DGFiP
error	Estat terminal: error de transmissió o processament

Polling

Consulta l’estat utilitzant el tax report ID obtingut a tax_report_ids a la resposta de la factura:

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

GET Tax Report - API Reference

---

e-Reporting (Flux 10)

El Flux 10 cobreix transaccions fora de l’obligació de facturació electrònica B2B domèstica però que igualment s’han d’informar a la DGFiP. B2Brouter gestiona el Flux 10 automàticament.

Si ja generes el teu propi <Report> F10 i només necessites un canal acreditat per dipositar-lo, consulta Flux 10: dipositar un fitxer que genera el teu sistema.

Operacions B2C

Vendes a particulars no registrats a la TVA a França. Utilitza "type": "IssuedSimplifiedInvoice". El contact_id i els camps de pagament no són obligatoris per a factures B2C.

Operacions transfrontereres (B2B intra-UE i extra-UE)

Les vendes o compres amb empreses establertes fora de França s’han d’informar via Flux 10. Utilitza el tipus estàndard IssuedInvoice o ReceivedInvoice i estableix el country de la contraparte a un valor diferent de "fr". B2Brouter detectarà automàticament la naturalesa transfronterera.

Territoris francesos d’ultramar (el contacte de la factura, no el teu compte): els departaments DROM Guadalupe (gp), Martinica (mq) i La Reunió (re) es tracten com a França domèstica. Les factures a contactes d’aquests territoris generen un tax report del Flux 1 i porten IdentificationCode FR, exactament igual que la França metropolitana. La resta de territoris d’ultramar (Guaiana gf, Mayotte yt, Polinèsia Francesa pf, Nova Caledònia nc, TAAF tf, Saint-Pierre-et-Miquelon pm) queden fora del territori de la TVA francesa i segueixen el camí d’e-Reporting del Flux 10. Aquest paràgraf parla de la contrapart de la factura; per al compte que emet, consulta Estructura del compte.

Ledgers de Flux 10

B2Brouter agrupa els tax reports Flux 10 en Ledgers enviats al PPF. La freqüència d’enviament no és sempre diària: depèn del vat_regime configurat al Tax Report Setting (consulta Camps de DGFiP Tax Report Settings), cada deu dies o mensual segons el règim, o bimensual per a franchise_en_base. A l’entorn de staging, els ledgers es dipositen diàriament per facilitar les proves; a producció, segueixen la periodicitat real del règim. Pots identificar els tax reports de Flux 10 perquè tenen ledger_id no nul a la resposta del tax report.

Model de 3 ledgers

Cada ledger s’identifica per dues dimensions internes:

• Rol DGFiP (SE o BY):
  • SE (Seller / émission): per a les vendes que emets.
  • BY (Buyer / réception): per a les compres intracomunitàries que has de declarar com a comprador.
• Mode (transactions o payments):
  • transactions: ledgers de factures (codis de procés S1 / B1 / M1), document type xml.ledger.dgfip.transactions.
  • payments: ledgers de pagaments (codis de procés S2 / B2 / M2, TVA sobre serveis es merita al cobrament), document type xml.ledger.dgfip.payments.

La combinació de rols i modes dóna fins a 3 ledgers per compte i període de reporting:

Ledger	Rol	Mode	Contingut
A: Emissió	SE	transactions	Factures emeses (B2C i cross-border B2B)
B: Recepció	BY	transactions	Compres intracomunitàries / extra-UE que has de declarar com a comprador
C: Pagaments	SE	payments	Pagaments confirmats de les teves factures emeses (cas Encaissée cross-border / B2C)

El parell (BY, payments) no existeix: la informació de pagament de les teves compres la genera el venedor des de la seva banda; no la declares tu.

Cada tax report es vincula a un únic ledger_id (no pertany a més d’un ledger alhora). L’agrupació es fa per compte + període de reporting + (rol, mode) sota lock per evitar duplicats.

---

Recursos addicionals

Guies:

• Casos d’ús suportats: els 44 casos d’ús de la RFE (XP Z12-014) i quins cobreix B2Brouter.
• Tax Report Settings Guide: l’endpoint de Tax Report Settings a fons, per a tots els països, no només França.
• Rebre, integrar i gestionar factures rebudes: com respondre a una factura rebuda amb mark_as, per a qualsevol xarxa.

Casos d’ús:

• Enviar factures a Chorus Pro (B2G): circuit per a factures dirigides al sector públic francès.
• Flux 10: dipositar un fitxer que genera el teu sistema: dipositar al PPF un fitxer d’e-Reporting que has generat al teu sistema.

Altres:

• API Reference
• Obrir un tiquet de suport

Recursos externs:

• DGFiP: reforma francesa de facturació electrònica