Guia de migració v2026-03-02 → v2026-04-20

Tot el que necessites per actualitzar el teu codi.

Aquesta guia t’ajuda a actualitzar de X-B2B-API-Version: 2026-03-02 a X-B2B-API-Version: 2026-04-20, centrant-se en el que has de canviar, no només en el que ha canviat.

Changelog Per al llistat complet d'afegits i correccions, consulta el changelog de v2026-04-20.

Resum ràpid

Què ha canviat	Has d’actuar?
Notes de crèdit i rectificacions utilitzen la nova estructura `invoice_references`	Sí
`payment_method_info` s’elimina de les respostes de factura	Sí
Es corregeix el typo `clasification_code_scheme`	Sí
Nova validació en crear contactes fills	Sí, només en alguns casos
Nova validació en crear factures amb contacte inline	Sí
Nous camps a respostes de factura, compte i transport Peppol	Només si el teu codi falla davant camps nous
`pending_peppol_directory_publish` es substitueix	Només si el llegeixes
Nou endpoint de verificació TIN	No, és optatiu
Nous camps de compte	No, són optatius
Afegits per a KSeF	No, només si integres KSeF

Canvis que requereixen acció

1. Notes de crèdit i rectificacions: substitueix camps plans per `invoice_references`

Aquest és el canvi més important. Els camps individuals de rectificació de les factures han estat substituïts per un array invoice_references. Si la teva integració crea o llegeix factures rectificatives, has d’actualitzar tant les peticions com el tractament de respostes.

Els camps següents ja no s’envien ni es retornen:

Camp eliminat	Substituït per `invoice_references[].`
`amended_number`	`number`
`amended_date`	`date`
`amended_invoicing_period_start`	`invoicing_period_start`
`amended_invoicing_period_end`	`invoicing_period_end`
`amend_reason`	`reason`
`amend_code_tax`	`tax_correction_code`
`correction_method`	`correction_method`

Cada entrada d’invoice_references requereix un reference_type. Utilitza "amend" per a factures rectificatives que referencien una factura original.

Actualitzar la petició (create/update):

Abans (v2026-03-02)
Després (v2026-04-20)

{
  "invoice": {
    "number": "CN-2026-001",
    "is_credit_note": true,
    "contact_id": 123,
    "amended_number": "INV-2026-042",
    "amended_date": "2026-02-10",
    "amend_reason": "Price correction"
  }
}

{
  "invoice": {
    "number": "CN-2026-001",
    "is_credit_note": true,
    "contact_id": 123,
    "invoice_references": [
      {
        "reference_type": "amend",
        "number": "INV-2026-042",
        "date": "2026-02-10",
        "reason": "Price correction"
      }
    ]
  }
}

Actualitzar el tractament de la resposta (read):

Abans (v2026-03-02)
Després (v2026-04-20)

const originalNumber = invoice.amended_number;
const reason = invoice.amend_reason;

const ref = invoice.invoice_references.find(
  (r) => r.reference_type === "amend",
);
const originalNumber = ref?.number;
const reason = ref?.reason;

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

2. `payment_method_info` s’elimina de les respostes de factura

El camp payment_method_info ja no es retorna. Si el feies servir, passa a utilitzar camps estructurats com payment_method, contact_iban, contact_bic, etc.

3. Correcció del typo `clasification_code_scheme` → `classification_code_scheme`

Si el teu codi llegeix clasification_code_scheme (amb una sola “s”), l’has d’actualitzar.

Abans
Després

{ "clasification_code_scheme": "..." }

{ "classification_code_scheme": "..." }

4. Contactes fills (oficines): `tin_value` ara es valida contra el pare

Quan crees o actualitzes un contacte amb parent_id, l’API ara rebutja la petició si el tin_value no coincideix amb el del contacte pare. La recomanació és ometre tin_value en crear oficines.

{
  "contact": {
    "name": "Branch Office Madrid",
    "parent_id": 456
  }
}

5. Crear una factura amb contacte inline ara requereix identificador

Si crees una factura passant el contacte inline amb un objecte contact, aquest ha d’incloure almenys tin_value o cin_value. Si no, la petició fallarà amb 422 Unprocessable Entity.

{
  "invoice": {
    "contact": {
      "name": "Acme Corp",
      "tin_value": "B12345678",
      "tin_scheme": "9915"
    }
  }
}

Nous camps en respostes existents

Els camps següents s’han afegit a respostes existents. Són compatibles cap enrere, però si el teu codi falla davant camps nous, hauràs d’actualitzar els models de resposta.

Respostes de factura:

invoice_references
exchange_rate
exchange_date
order_date
contact.cin_value, contact.cin_scheme

Respostes de compte:

routing_codes
auto_remittance
skip_line_taxable_base_rounding

Resposta de transport Peppol:

sml_status
peppol_directory_status
reception_document_types
standard_documents i pending_peppol_directory_publish ja no es retornen

Noves funcionalitats disponibles en aquesta versió

Verificació TIN: verifica que un nom d’empresa i un número fiscal estiguin registrats a l’autoritat tributària abans d’enviar una factura.

POST /tin_verifications?country=es
GET /tin_verifications/{id}
Webhook tin_verification.finished

Nous camps de configuració de compte:

routing_codes
auto_remittance
skip_line_taxable_base_rounding

Afegits de KSeF: si la teva integració gestiona factures poloneses, aquesta versió afegeix suport per a fluxos de bestreta (ZAL, ROZ, KOR_ZAL, KOR_ROZ), escenaris d’unitats de govern local i grups d’IVA, i diversos camps nous de tax report.

Checklist de migració

Utilitza aquesta checklist abans de canviar a v2026-04-20 en producció.

Factures rectificatives:

Substitueix els camps plans (amended_number, amended_date, amend_reason, etc.) per invoice_references
Inclou reference_type: "amend" a cada entrada
Actualitza la lectura de respostes per llegir invoice_references
Prova la creació i lectura d’una nota de crèdit

Camps de resposta de factura:

Elimina qualsevol codi que llegeixi payment_method_info
Actualitza clasification_code_scheme a classification_code_scheme
Confirma que el teu codi accepta exchange_rate, exchange_date, order_date, contact.cin_value i contact.cin_scheme

Contactes:

Si crees contactes amb parent_id, elimina tin_value o alinea’l amb el del pare
Si crees factures amb contacte inline, assegura’t que sempre hi hagi tin_value o cin_value

Transport Peppol:

Substitueix pending_peppol_directory_publish per peppol_directory_status
Confirma que el teu model de resposta accepta sml_status, peppol_directory_status i reception_document_types

Comptes:

Confirma que el tractament de respostes accepta routing_codes, auto_remittance i skip_line_taxable_base_rounding

Provar la teva integració

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

X-B2B-API-Version: 2026-04-20

Pots establir aquesta capçalera per petició, de manera que pots provar-la sense tocar la configuració de producció. Un cop hagis validat la checklist anterior, actualitza la versió a la configuració de l’API Key de producció o a les capçaleres de petició.