Guia de migració v2026-04-20 → v2026-06-26

Tot el que necessites per actualitzar el teu codi.

Aquesta guia t'ajuda a actualitzar de X-B2B-API-Version: 2026-04-20 a X-B2B-API-Version: 2026-06-26, centrant-se en què has de canviar, no només en què ha canviat.

Changelog Per a la llista completa d'addicions i correccions, consulta el changelog de v2026-06-26.

Resum ràpid

Què ha canviat	Cal actuar?
Les oficines ara emmagatzemen el seu propi `cin_value` / `cin_scheme` en lloc d'heretar-lo	Sí — només si la teva integració crea o llegeix oficines (contactes amb `parent_id`)
Coincidència més estricta de contactes en crear factures amb un `contact` en línia	Sí — afecta integracions que passen dades de `contact` en línia en crear factures
La consulta a l'Annuaire francès a `/directory/fr` ara pot retornar `202 Accepted`	Sí — només si crides `/directory/fr` per a identificadors francesos
Les claus planes `cinN_value` / `cinN_scheme` ja no s'accepten al `contact` de la factura	Sí — mou-les a `contact.routing_codes`
Els camps d'encaminament dedicats (`dire`, `accounting_unit`, etc.) ja no s'accepten al nivell superior de la factura	Sí — mou-los a l'objecte `routing_codes` a nivell de factura
`POST /invoices/{id}/generate_tax_report` ara retorna `201 Created`	Sí — només si comproves un estat exacte de `200`
El filtre `number` del llistat de factures ara fa coincidència per prefix en lloc de coincidència exacta	Només si la teva integració depèn del comportament de coincidència exacta
Nous events de webhook per a factures rebudes	No — opt-in
Crear oficines via `POST /accounts` amb `parent_id`	No — opt-in
`issue_after_import` en crear i importar factures	No — opt-in
Preferència `unit_code_format` del compte	No — opt-in
`apply_taxes_per_line` per factura	No — opt-in
Nous camps `taxable_base` / `tax_amount` al llistat de factures	No — additiu
`refuse_reason_code` de DGFiP a mark_as i a les respostes de factura	No — opt-in

Canvis que requereixen acció

1. Les oficines ara emmagatzemen el seu propi CIN en lloc d'heretar-lo

Anteriorment, una oficina (un contacte creat amb parent_id) sempre heretava cin_value / cin_scheme del seu contacte pare. Ara aquests camps s'emmagatzemen de forma independent per oficina.

Si envies cin_value / cin_scheme en crear o actualitzar una oficina, s'emmagatzemen a l'oficina i es retornen a les respostes.
Si els omets (o els esborres amb cin_value: ""), l'oficina continua heretant el CIN del pare a les respostes de lectura — no cal actuar si mai has establert el CIN a les oficines.
tin_value / tin_scheme no es veuen afectats — continuen sempre heretant-se del pare i no es poden establir de forma independent.
Ara s'aplica la unicitat del CIN dins del compte: reutilitzar un cin_value ja assignat a un altre contacte del mateix compte retorna 422 Unprocessable Entity.

Abans (v2026-04-20)
Després (v2026-06-26)

POST /accounts/{account_id}/contacts
{
  "contact": {
    "parent_id": 12345,
    "name": "Branch Office",
    "cin_value": "1234567890",
    "cin_scheme": 88
  }
}

// Resposta — cin_value s'ignora, s'hereta del contacte pare
{
  "contact": {
    "id": 67890,
    "parent_id": 12345,
    "name": "Branch Office",
    "cin_value": "<cin_value del pare>",
    "cin_scheme": "<cin_scheme del pare>"
  }
}

POST /accounts/{account_id}/contacts
{
  "contact": {
    "parent_id": 12345,
    "name": "Branch Office",
    "cin_value": "1234567890",
    "cin_scheme": 88
  }
}

// Resposta — cin_value ara s'emmagatzema a l'oficina mateixa
{
  "contact": {
    "id": 67890,
    "parent_id": 12345,
    "name": "Branch Office",
    "cin_value": "1234567890",
    "cin_scheme": "88"
  }
}

Endpoints afectats: POST /accounts/{account}/contacts, PUT /contacts/{id}

2. Validació més estricta de contactes en crear factures amb un `contact` en línia

Quan passes un hash contact en línia en crear una factura, l'API ara el compara amb els contactes existents per tin_value o cin_value abans de decidir què fer:

Coincidència completa → la factura s'enllaça amb el contacte existent.
Els identificadors d'encaminament difereixen (cin_value, cin_scheme, routing_codes, pin_value, recipient_code) → es crea una oficina automàticament.
Només difereixen camps descriptius (address, city, postalcode, etc.) → la petició ara retorna 422 Unprocessable Entity amb codi data_mismatch en lloc d'actualitzar el contacte silenciosament.
Cap coincidència → es crea un contacte nou (i s'enllaça al directori de B2Brouter si coincideix amb una empresa coneguda).

Si la teva integració depèn del comportament anterior de sobreescriure silenciosament les dades descriptives del contacte en crear factures, passa update_contact: true (camp de la petició a nivell superior, per defecte false) per tornar a activar-ho. Els identificadors d'encaminament i fiscals mai es sobreescriuen d'aquesta manera, i update_contact no té cap efecte en documents rebuts.

// Activar l'actualització de dades descriptives del contacte des de la creació de factura
POST /accounts/{account_id}/invoices
{
  "update_contact": true,
  "invoice": {
    "contact": {
      "tin_value": "B12345678",
      "name": "Acme Corp",
      "address": "New address 123"
    }
  }
}

L'endpoint de contactes és la manera recomanada de crear i mantenir contactes i les seves oficines. Per enllaçar una factura amb un contacte existent sense cap lògica de coincidència, utilitza contact_id directament.

Endpoints afectats: POST /accounts/{account}/invoices

3. La consulta a l'Annuaire francès a `/directory/fr` ara és asíncrona

GET /directory/fr/{scheme}/{id} ara consulta l'Annuaire francès de la PPF per a identificadors SIREN, SIRET i FRCTC (0225). Si la teva integració crida aquest endpoint per a identificadors francesos, gestiona les noves formes de resposta:

202 Accepted amb un polling_url — l'empresa encara no era coneguda; un job en segon pla està consultant l'Annuaire. Reintenta al cap d'uns segons.
424 Failed Dependency amb codi d'error upstream_unavailable i una capçalera Retry-After — l'Annuaire o Peppol no estan disponibles temporalment. Reintenta després del retard indicat; no ho tractis com un 404.
422 Unprocessable Entity amb codi invalid_identifier — l'identificador ha fallat la validació de longitud/checksum per al seu esquema.
S'inclou un nou array information_flags a les respostes amb èxit (FR_ASSUJETTI_ACTIVE, FR_ASSUJETTI_INACTIVE, FR_ASSUJETTI_UNKNOWN).

curl --request GET \
     --url 'https://app-staging.b2brouter.net/api/v1/directory/fr/0002/123456789' \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: 2026-06-26'

// 202 Accepted — encara no coneguda, reintenta a polling_url
{
  "status": "processing",
  "message": "Querying French PPF Annuaire. Please retry this request.",
  "polling_url": "https://app-staging.b2brouter.net/api/v1/directory/fr/0002/123456789"
}

Endpoints afectats: GET /directory/fr/{scheme}/{id} (els països no francesos no es veuen afectats)

4. Les claus planes `cinN_value` / `cinN_scheme` ja no s'accepten al `contact` de la factura

L'objecte contact en línia a POST /accounts/{account}/invoices ja no accepta les claus planes cin1_value/cin1_scheme … cin5_value/cin5_scheme. Mou-les a un objecte contact.routing_codes — la mateixa forma utilitzada per POST /accounts/{account}/contacts.

Abans (v2026-04-20)
Després (v2026-06-26)

{
  "invoice": {
    "contact": {
      "tin_value": "ESA13585625",
      "name": "Buyer Full Name AS",
      "cin1_value": "ESR_MISSION_FACTURES_DEPLACEMENTS",
      "cin1_scheme": "8017"
    }
  }
}

{
  "invoice": {
    "contact": {
      "tin_value": "ESA13585625",
      "name": "Buyer Full Name AS",
      "routing_codes": {
        "cin1_value": "ESR_MISSION_FACTURES_DEPLACEMENTS",
        "cin1_scheme": "8017"
      }
    }
  }
}

Les peticions que encara usen les claus planes retornen 422 Unprocessable Entity.

Endpoints afectats: POST /accounts/{account}/invoices

5. Els camps d'encaminament a nivell de factura se substitueixen per un objecte `routing_codes`

Al nivell superior de la factura, tant les claus planes cinN_value / cinN_scheme com els camps d'encaminament dedicats (dire, accounting_unit, managing_unit, processing_unit, proponent_unit, nadby, naddp, nadiv, nadpr, nadud) ja no s'accepten. Utilitza en el seu lloc l'objecte routing_codes a nivell de factura — porta els codis d'encaminament propis de la factura (p. ex. els codis de servei DIR3 / Chorus Pro del comprador), independents dels del contacte.

Ranura	DIR3 (esquema `8014`)	DIRe (`8015`)	EDI/GLN (`88`)
cin1	`accounting_unit`	—	`nadby`
cin2	`managing_unit`	—	`naddp`
cin3	`processing_unit`	—	`nadiv`
cin4	`proponent_unit`	—	`nadpr`
cin5	—	`dire`	`nadud`

Abans (v2026-04-20)
Després (v2026-06-26)

{
  "invoice": {
    "number": "F-2026-0001",
    "accounting_unit": "ESR_MISSION_FACTURES_DEPLACEMENTS"
  }
}

{
  "invoice": {
    "number": "F-2026-0001",
    "routing_codes": {
      "cin1_value": "ESR_MISSION_FACTURES_DEPLACEMENTS",
      "cin1_scheme": "8014"
    }
  }
}

Els codis aplicats es retornen en un objecte routing_codes al nivell superior de la factura de la resposta. Les peticions que encara usen els camps antics retornen 422 Unprocessable Entity.

Endpoints afectats: POST /accounts/{account}/invoices, PUT /invoices/{id}

6. `generate_tax_report` ara retorna `201 Created`

POST /invoices/{id}/generate_tax_report ara retorna 201 Created en cas d'èxit en lloc de 200 OK. El cos de la resposta no canvia. Això només afecta els clients que comproven un estat exacte de 200 — els clients que comproven qualsevol èxit 2xx no es veuen afectats.

Endpoints afectats: POST /invoices/{id}/generate_tax_report

7. El filtre `number` del llistat de factures ara fa coincidència per prefix

GET /accounts/{account}/invoices?number=... ara fa una coincidència de prefix en lloc d'una coincidència exacta. Si la teva integració depèn del comportament anterior de coincidència exacta, afegeix una comprovació al costat client per filtrar coincidències de prefix no desitjades, o canvia a un valor més específic.

GET /accounts/{account}/invoices?number=INV-2

ara també retorna INV-20, INV-21, … a més d'una factura numerada exactament INV-2. Hi ha disponible un nou filtre series_code per a filtratge de coincidència exacta per sèrie.

Endpoints afectats: GET /accounts/{account}/invoices

Nous camps a respostes existents

S'han afegit els següents camps. Són compatibles amb versions anteriors — la teva integració continuarà funcionant sense canvis. No obstant, si el teu codi falla quan troba camps JSON inesperats, actualitza els teus models de resposta per permetre'ls.

Respostes de contacte (GET /contacts/{id}, POST, PUT, DELETE):

parent_id — null per als contactes de nivell superior, l'ID del contacte pare per a les oficines

Llistat de factures (GET /accounts/{account}/invoices):

taxable_base — subtotal de la factura abans d'impostos
tax_amount — import total d'impostos de tots els desglossaments d'impost

Respostes de factura (mark_as, crear, actualitzar):

refuse_reason_code — codi de motiu estructurat definit per DGFiP per als rebutjos del procés 210 (s'accepta a POST /invoices/{id}/mark_as juntament amb reason)

Respostes de compte (GET /accounts/{account}, GET /accounts):

unit_code_format — internal (per defecte) o unece_rec20; consulta la funcionalitat opt-in a continuació per a l'efecte sobre unit a les línies de factura

Noves funcionalitats disponibles en aquesta versió

Webhooks de factures rebudes — subscriu-te a received_invoice.created i received_invoice.state_change per rebre notificacions quan es creen factures rebudes o canvien d'estat.

Oficines via POST /accounts — crea una oficina (filial) directament sota un compte pare passant parent_id; els camps obligatoris habituals esdevenen opcionals i l'oficina hereta la integració del grup.

issue_after_import — passa aquest indicador en crear o importar factures per transicionar de forma síncrona la factura a state=issued dins de la mateixa petició, en lloc de dependre del flux d'enviament.

Preferència de compte unit_code_format — estableix-la a unece_rec20 per intercanviar el camp unit de la línia de factura com un codi en cadena de la Recomanació 20 d'UN/ECE (p. ex. "HUR") en lloc de l'id enter intern de B2Brouter. El valor per defecte internal no afecta les integracions existents.

apply_taxes_per_line per factura (comptes premium) — sobreescriu el mode d'arrodoniment d'IVA a nivell de compte per a una sola factura, útil quan una administració pública recalcula els totals amb una regla d'arrodoniment diferent. Consulta la guia de càlcul de factures.

Llista de comprovació de migració

Utilitza aquesta llista abans de canviar a v2026-06-26 en producció.

Contactes i oficines:

Si estableixes cin_value / cin_scheme en crear o actualitzar oficines, verifica que el valor és únic dins del compte (els duplicats ara retornen 422)
Actualitza el codi que llegeix parent_id a les respostes de contacte si necessites distingir oficines de contactes de nivell superior

Creació de factures amb contacte en línia:

Mou qualsevol clau cinN_value / cinN_scheme dins de invoice.contact a invoice.contact.routing_codes
Mou qualsevol cinN_value/cinN_scheme o camp dedicat (dire, accounting_unit, etc.) a nivell superior de la factura a l'objecte routing_codes a nivell de factura
Decideix si necessites update_contact: true per preservar el comportament anterior de sobreescriptura de dades descriptives
Prova: crea una factura amb un contacte en línia les dades descriptives del qual difereixen d'un contacte existent, i confirma que gestiones la resposta 422 data_mismatch (o passa update_contact: true)

Informes fiscals:

Actualitza qualsevol comprovació d'estat a POST /invoices/{id}/generate_tax_report que esperi exactament 200 OK

Filtratge del llistat de factures:

Revisa qualsevol ús del filtre number que depengui del comportament de coincidència exacta; canvia a series_code si necessites coincidència exacta per sèrie

Consultes al directori francès:

Gestiona 202 Accepted amb polling_url i reintenta
Gestiona 424 Failed Dependency amb Retry-After com a error transitori, no com un 404
Gestiona 422 Unprocessable Entity amb codi invalid_identifier

Provant la teva integració

Canvia a la nova capçalera de versió al teu entorn de sandbox o staging primer:

X-B2B-API-Version: 2026-06-26

Pots establir aquesta capçalera per petició, de manera que pots provar contra sandbox (o staging) sense tocar la teva configuració de producció. Un cop hagis validat la llista de comprovació anterior, actualitza la versió a la configuració de la teva clau d'API de producció o a les capçaleres de petició.