Guía de migración v2026-03-02 → v2026-04-20

Esta guía te ayuda a actualizar de X-B2B-API-Version: 2026-03-02 a X-B2B-API-Version: 2026-04-20, centrándose en lo que necesitas cambiar, no solo en lo que ha cambiado.

Changelog Para la lista completa de adiciones y correcciones, consulta el changelog de v2026-04-20.

Resumen

Qué ha cambiado	¿Necesitas actuar?
Las notas de crédito y rectificaciones usan una nueva estructura invoice_references	Sí — afecta a todas las integraciones que crean o leen facturas rectificativas
payment_method_info eliminado de las respuestas de factura	Sí — elimina cualquier código que lea este campo
Corrección del error tipográfico clasification_code_scheme en respuestas de línea	Sí — actualiza el nombre del campo si lo lees
Nueva validación al crear contactos hijo (sucursales)	Sí — solo si estableces tin_value en contactos con parent_id
Nueva validación al crear facturas con contacto en línea	Sí — asegúrate de que siempre se incluya tin_value o cin_value
Nuevos campos en respuestas de factura, cuenta y transporte Peppol	Solo si tu código falla con campos JSON inesperados
Transporte Peppol: pending_peppol_directory_publish reemplazado	Solo si lees este campo
Endpoint de verificación de NIF (nuevo)	No — función opcional
Nuevos campos de cuenta (routing_codes, auto_remittance, etc.)	No — opcional
Adiciones de KSeF	No — solo relevante para integraciones polacas con KSeF

---

Cambios que requieren acción

1. Notas de crédito y rectificaciones: reemplazar campos planos por invoice_references

Este es el cambio más significativo. Los campos individuales de rectificación en las facturas han sido reemplazados por un único array invoice_references. Si tu integración crea o lee facturas rectificativas (notas de crédito, rectificaciones), debes actualizar tanto tus solicitudes como el manejo de respuestas.

Los siguientes campos ya no se envían ni se devuelven:

Campo eliminado	Reemplazado por invoice_references[].
amended_number	number
amended_date	date
amended_invoicing_period_start	invoicing_period_start (solo envío, no se devuelve)
amended_invoicing_period_end	invoicing_period_end (solo envío, no se devuelve)
amend_reason	reason
amend_code_tax	tax_correction_code
correction_method	correction_method

Cada entrada en invoice_references requiere un reference_type. Usa "amend" para facturas rectificativas que hacen referencia a una factura original.

Actualización de tu solicitud (crear/actualizar):

Antes (v2026-03-02)

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

Después (v2026-04-20)

{
  "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"
      }
    ]
  }
}

Actualización del manejo de respuestas (lectura):

Antes (v2026-03-02)

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

Después (v2026-04-20)

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

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

---

2. payment_method_info eliminado de las respuestas de factura

El campo payment_method_info ya no se devuelve. Contenía un resumen de pago con formato HTML legible — si lo estabas usando, cambia a los campos estructurados ya presentes en la respuesta: payment_method, contact_iban, contact_bic, etc.

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

---

3. Corrección del error tipográfico en el nombre del campo de línea de factura: clasification_code_scheme → classification_code_scheme

El campo estaba mal escrito en todas las versiones anteriores. La respuesta ahora devuelve la ortografía correcta. Si tu código lee clasification_code_scheme (con una sola ‘s’) de las respuestas de línea de factura, actualízalo.

Nota: el envío de la ortografía correcta en las solicitudes ya se aceptaba en todas las versiones — solo cambia la clave de respuesta.

Antes (v2026-03-02)

{ "clasification_code_scheme": "..." }

Después (v2026-04-20)

{ "classification_code_scheme": "..." }

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

---

4. Contactos hijo (sucursales): tin_value ahora se valida contra el padre

Al crear o actualizar un contacto que pertenece a una empresa matriz (usando parent_id), la API ahora rechazará la solicitud si el tin_value proporcionado no coincide con el del contacto padre. Anteriormente, un valor no coincidente se ignoraba silenciosamente.

El enfoque recomendado es omitir tin_value al crear sucursales — se hereda automáticamente del padre.

// Recomendado (v2026-04-20) — crear una sucursal
{
  "contact": {
    "name": "Branch Office Madrid",
    "parent_id": 456
  }
}

Endpoints afectados: POST /accounts/{account}/contacts, PATCH /contacts/{id}

---

5. Crear una factura con contacto en línea ahora requiere un identificador

Si creas una factura y pasas los datos del contacto en línea (usando un objeto contact en lugar de contact_id), el contacto ahora debe incluir al menos uno de tin_value o cin_value. Las solicitudes sin ninguno serán rechazadas con 422 Unprocessable Entity.

Esto no aplica a las facturas simplificadas (IssuedSimplifiedInvoice), que no requieren un contacto identificado.

// v2026-04-20 — tin_value o cin_value es obligatorio
{
  "invoice": {
    "contact": {
      "name": "Acme Corp",
      "tin_value": "B12345678",
      "tin_scheme": "9915"
    }
  }
}

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

---

Nuevos campos en respuestas existentes

Los siguientes campos se han añadido a las respuestas existentes. Son compatibles con versiones anteriores — tu integración seguirá funcionando sin cambios. Sin embargo, si tu código falla cuando encuentra campos JSON inesperados, actualiza tus modelos de respuesta para permitirlos.

Respuestas de factura (GET /invoices/{id}, POST, PATCH):

• invoice_references — array de referencias de rectificación/prepago (véase apartado 1 arriba)
• exchange_rate — el tipo de cambio aplicado cuando la moneda de la factura difiere de la moneda de la autoridad fiscal local
• exchange_date — la fecha del tipo de cambio
• order_date — fecha de la orden de compra (complementa el campo ponumber existente)
• contact.cin_value, contact.cin_scheme — identificador de empresa del contacto de la factura

Respuestas de cuenta (GET /accounts/{account}, GET /accounts):

• routing_codes — objeto que contiene hasta 5 identificadores adicionales de empresa (cin1_value/cin1_scheme hasta cin5_value/cin5_scheme)
• auto_remittance — booleano
• skip_line_taxable_base_rounding — booleano

Respuesta de transporte Peppol (GET /accounts/{account}/transports):

• sml_status — estado de registro SML: "not_published", "processing" o "published"
• peppol_directory_status — estado de listado en el directorio Peppol (reemplaza el booleano antiguo pending_peppol_directory_publish)
• reception_document_types — lista de tipos de documento que este participante puede recibir a través de Peppol
• standard_documents y pending_peppol_directory_publish ya no se devuelven

---

Nuevas funciones disponibles en esta versión

Verificación de NIF — verifica que el nombre y número fiscal de una empresa estén registrados en la autoridad fiscal antes de enviar una factura. Actualmente admite España (AEAT).

• POST /tin_verifications?country=es — envía una lista de hasta 20.000 pares NIF+nombre para verificación; devuelve 202 Accepted mientras el proceso se ejecuta en segundo plano
• GET /tin_verifications/{id} — recupera los resultados una vez completado el proceso
• Suscríbete al evento webhook tin_verification.finished para recibir notificaciones automáticamente

Nuevos campos de configuración de cuenta:

• routing_codes en cuentas — almacena hasta 5 identificadores adicionales de empresa, útil para el enrutamiento Peppol
• auto_remittance — genera automáticamente referencias de remesa OGM estructuradas en facturas belgas
• skip_line_taxable_base_rounding — útil para facturas con muchas líneas donde se acumulan pequeñas diferencias de redondeo; requiere apply_taxes_per_line: true

Adiciones de KSeF (facturación electrónica polaca) — si tu integración gestiona facturas polacas, esta versión añade soporte para flujos de trabajo de anticipo (ZAL, ROZ, KOR_ZAL, KOR_ROZ), escenarios de facturación de gobierno local y grupo de IVA, y varios campos nuevos de informes fiscales. Consulta el changelog para la lista completa.

---

Lista de verificación de migración

Usa esta lista de verificación antes de cambiar a v2026-04-20 en producción.

Facturas rectificativas (notas de crédito, rectificaciones):

• Reemplaza los campos planos de rectificación (amended_number, amended_date, amend_reason, etc.) con invoice_references en todas las solicitudes de creación/actualización de facturas
• Incluye reference_type: "amend" en cada entrada
• Actualiza el manejo de respuestas para leer desde invoice_references en lugar de los campos planos
• Prueba: crea una nota de crédito, léela de vuelta y confirma que el array invoice_references está presente y es correcto

Campos de respuesta de factura:

• Elimina cualquier código que lea payment_method_info
• Actualiza clasification_code_scheme → classification_code_scheme donde leas respuestas de línea de factura
• Confirma que tu manejo de respuestas acepta los nuevos campos: exchange_rate, exchange_date, order_date, contact.cin_value, contact.cin_scheme

Contactos:

• Si creas contactos con parent_id, elimina o alinea tin_value con el valor del contacto padre
• Si creas facturas con un objeto contact en línea, asegúrate de que siempre se incluya tin_value o cin_value

Transporte Peppol:

• Actualiza el manejo de respuestas de transporte: reemplaza pending_peppol_directory_publish por peppol_directory_status y elimina las lecturas de standard_documents
• Confirma que tu modelo de respuesta acepta sml_status, peppol_directory_status y reception_document_types

Cuentas:

• Confirma que tu manejo de respuestas de cuenta acepta los nuevos campos routing_codes, auto_remittance y skip_line_taxable_base_rounding

Prueba de tu integración

Cambia a la nueva cabecera de versión en tu entorno de sandbox o staging primero:

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

Puedes establecer esta cabecera por solicitud, de modo que puedas probar en sandbox (o staging) sin tocar tu configuración de producción. Una vez que hayas validado la lista de verificación anterior, actualiza la versión en los ajustes de tu clave de API de producción o en las cabeceras de solicitud.