v2026-04-20

Changelog

Selecciona esta versión enviando X-B2B-API-Version: 2026-04-20 en las cabeceras de tu petición.

Esta versión implementa cambios incompatibles. Cada cambio incompatible está marcado con la etiqueta Breaking.

Resumen de los cambios

Cambio	Área
Añadir identificadores adicionales a las cuentas (`routing_codes`)	Cuentas
Añadir `auto_remittance` a las cuentas	Cuentas
Añadir `skip_line_taxable_base_rounding` a las cuentas	Cuentas
Exponer `cin_value` y `cin_scheme` en los campos de contacto de factura	Facturas
Reemplazar los campos de enmienda por `invoice_references` Breaking	Facturas
Cambios en el transporte Peppol Breaking (eliminar `standard_documents`, `pending_peppol_directory_publish`; añadir `sml_status`, `peppol_directory_status`, `reception_document_types`)	Transportes
Validar `tin_value` y `tin_scheme` contra el contacto padre Breaking	Contactos
Requerir `tin_value` o `cin_value` al crear un contacto en línea en facturas Breaking	Facturas
Nuevo endpoint de verificación de NIF	Verificaciones NIF
Nuevo evento de webhook `tin_verification.finished`	Webhooks
Añadir `exchange_rate` y `exchange_date` a la respuesta de factura	Facturas
Eliminar `payment_method_info` de la respuesta de factura Breaking	Facturas
Corregir el error tipográfico `clasification_code_scheme` en las respuestas de líneas de factura Breaking	Facturas
Añadir `order_date` a la respuesta de factura	Facturas
Añadir `total_amount_due` a la petición de factura	Facturas (KSeF)
Añadir soporte a `third_party` en las facturas	Facturas (KSeF)
Añadir `customer_party_jst` y `customer_party_gv` a los informes fiscales	Reporte fiscal (KSeF)
Añadir `purchase_order_date` y `despatch_advice_reference` a los informes fiscales	Reporte fiscal (KSeF)
Añadir `supplier_party_krs`, `supplier_party_regon` y `supplier_party_bdo` a los informes fiscales	Reporte fiscal (KSeF)
Añadir `supplier_contact_phone` y `supplier_contact_email` a los informes fiscales	Reporte fiscal (KSeF)
Añadir `previous_advance_total` a los informes fiscales	Reporte fiscal (KSeF)
Añadir `order_total_amount` a los informes fiscales	Reporte fiscal (KSeF)
Añadir `prepayment_references` a los informes fiscales	Reporte fiscal (KSeF)
Hacer editables los campos `third_party` en los informes fiscales	Reporte fiscal (KSeF)
Añadir códigos de tipo de factura KSeF	Facturas (KSeF)

Añadido

Endpoint de verificación de NIF

Nuevo endpoint para verificar pares NIF (Número de Identificación Fiscal) + nombre contra un censo de la autoridad fiscal. Actualmente solo admite España (AEAT).

El procesamiento es asíncrono: POST retorna 202 Accepted inmediatamente, y los resultados se recuperan via GET o se reciben a través del evento de webhook tin_verification.finished. Los resultados de las últimas 24 horas se guardan en caché para evitar llamadas redundantes a la autoridad fiscal.

Nuevos endpoints:

POST /tin_verifications?country=es — Envía un lote de hasta 20.000 pares NIF+nombre para la verificación.
GET /tin_verifications/{id} — Recupera el estado y los resultados de una petición de verificación.

Ejemplo: Enviar verificación

curl --request POST \
     --url 'https://app-staging.b2brouter.net/tin_verifications?country=es' \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
     --header 'content-type: application/json' \
     --data '[{"tin": "B12345678", "name": "Ejemplo S.L."}]'

{
  "id": 42,
  "status": "pending",
  "results": []
}

Ejemplo: Obtener resultados

{
  "id": 42,
  "status": "success",
  "results": [
    {
      "tin": "B12345678",
      "normalized_tin": "ESB12345678",
      "name": "Ejemplo S.L.",
      "tin_format_valid": true,
      "census_match": true
    }
  ]
}

Cuando census_match es true, el campo name de los resultados retorna el nombre canónico del censo de la autoridad fiscal; en caso contrario, retorna el nombre enviado.

Webhook de verificación de NIF

El nuevo evento de webhook tin_verification.finished se activa cuando una petición de verificación de NIF llega a un estado terminal (success o failed). El payload contiene solo el ID de la petición y el estado — usa GET /tin_verifications/{id} para obtener los resultados completos.

Suscríbete a este evento al configurar un webhook:

{
  "web_hook": {
    "url": "https://example.com/hooks",
    "events": ["tin_verification.finished"]
  }
}

Añadir identificadores adicionales a las cuentas (`routing_codes`)

Nuevo objeto routing_codes en las cuentas para soportar hasta 5 Números de Identificación de Empresa adicionales más allá del cin principal. Contiene los campos cin1_value, cin1_scheme hasta cin5_value, cin5_scheme (cadena, anulable). Los códigos de esquema se retornan como cadenas de 4 caracteres con ceros a la izquierda (p. ej. "0088"), o null cuando el esquema es desconocido.

Respuesta GET:

"routing_codes": {
  "cin1_value": "7080000950171",
  "cin1_scheme": "0088",
  "cin2_value": null,
  "cin2_scheme": null,
  ...
  "cin5_value": "1234567890",
  "cin5_scheme": "0001",
}

Entrada POST/PUT: usa el mismo objeto anidado routing_codes. Si se proporciona cinN_value, cinN_scheme es obligatorio (y viceversa).

"account": {
  "routing_codes": {
    "cin1_value": "7080000950171",
    "cin1_scheme": "0088"
  }
}

Endpoints afectados:

POST /accounts — acepta routing_codes en el cuerpo de la petición.
PUT /accounts/{account} — acepta routing_codes en el cuerpo de la petición.
GET /accounts/{account} — retorna routing_codes en la respuesta.
GET /accounts — retorna routing_codes en cada entrada de cuenta.

Añadir `auto_remittance` a las cuentas

Nuevo campo booleano auto_remittance (por defecto false) en las cuentas que activa la generación automática de referencias de remesa estructuradas (códigos OGM) para facturas belgas, sin requerir un grupo de integración que las imponga.

Cuando auto_remittance es true y tanto la cuenta como el contacto de la factura se encuentran en Bélgica, la factura recibirá automáticamente una referencia de remesa estructurada — el mismo comportamiento que anteriormente solo estaba disponible a través de grupos de integración que requerían códigos OGM.

Endpoints afectados:

POST /accounts — acepta auto_remittance en el cuerpo de la petición.
PUT /accounts/{account} — acepta auto_remittance en el cuerpo de la petición.
GET /accounts/{account} — retorna auto_remittance en la respuesta.

Añadir `skip_line_taxable_base_rounding` a las cuentas

Nuevo campo booleano skip_line_taxable_base_rounding (por defecto false) en las cuentas. Cuando está activado, el cálculo de impuestos de la factura omite el redondeo de las bases imponibles individuales de cada línea y los importes de impuesto por línea, redondeando solo los totales acumulados finales. Esto reduce la deriva por redondeo en las facturas con muchas líneas.

Requiere que apply_taxes_per_line sea true — la API retorna 422 Unprocessable Entity si skip_line_taxable_base_rounding se establece a true mientras apply_taxes_per_line es false.

Endpoints afectados:

POST /accounts — acepta skip_line_taxable_base_rounding en el cuerpo de la petición.
PUT /accounts/{account} — acepta skip_line_taxable_base_rounding en el cuerpo de la petición.
GET /accounts/{account} — retorna skip_line_taxable_base_rounding en la respuesta.
GET /accounts — retorna skip_line_taxable_base_rounding en cada entrada de cuenta.

Exponer `cin_value` y `cin_scheme` en los campos de contacto de factura

El objeto contact en las respuestas de factura ahora incluye los campos cin_value y cin_scheme junto a los existentes tin_value y tin_scheme.

Endpoints afectados:

GET /invoices/{id} — el objeto contact ahora incluye cin_value y cin_scheme.
GET /accounts/{account}/invoices — el objeto contact en las entradas del índice ahora incluye cin_value y cin_scheme.

Modificado

Validar `tin_value` y `tin_scheme` contra el contacto padre

🚨 Breaking

Las peticiones POST /accounts/{account}/contacts y PATCH /contacts/{id} con parent_id ahora validan tin_value y tin_scheme contra el contacto padre. Las oficinas (unidades organizativas) heredan el NIF de su padre; si el tin_value proporcionado no coincide con el del padre, la API retorna 422 Unprocessable Entity con código parameter_invalid. Anteriormente, los valores no coincidentes se ignoraban silenciosamente.

cin_value y cin_scheme se heredan del contacto padre y no se validan contra él.

Para migrar, omite tin_value al crear oficinas (recomendado), o asegúrate de que coincide exactamente con el valor del padre.

Endpoints afectados:

POST /accounts/{account}/contacts — rechaza tin_value / tin_scheme no coincidentes cuando parent_id está establecido.
PATCH /contacts/{id} — rechaza tin_value / tin_scheme no coincidentes cuando el contacto tiene un padre.

Requerir `tin_value` o `cin_value` al crear un contacto en línea en facturas

🚨 Breaking

POST /accounts/{account}/invoices ahora valida que cuando se proporciona un objeto contact en línea, al menos uno de tin_value o cin_value esté presente. Si los dos faltan, la API retorna 422 Unprocessable Entity con código parameter_blank y param: "contact".

IssuedSimplifiedInvoice está exenta de esta validación — las facturas simplificadas (tickets) no requieren un contacto identificado.

Para migrar, incluye siempre tin_value o cin_value al enviar un contact en línea al crear una factura. Como alternativa, usa contact_id para referenciar un contacto existente.

Endpoints afectados:

POST /accounts/{account}/invoices — rechaza los objetos contact en línea sin tin_value ni cin_value (excepto para IssuedSimplifiedInvoice).

Reemplazar los campos de enmienda por `invoice_references`

🚨 Breaking Un nuevo array invoice_references reemplaza los campos planos de enmienda (amended_number, amended_date, amended_invoicing_period_start, amended_invoicing_period_end, amend_reason, amend_code_tax, correction_method) en el recurso Factura.

Cada referencia tiene un reference_type:

amend — factura correctiva que referencia la original. Máximo 1 por factura.
prepayment — factura de liquidación (ROZ) que referencia facturas de anticipo (ZAL). Se permiten múltiples.

Cambio incompatible — respuesta: los campos planos amended_number, amended_date, amended_invoicing_period_start, amended_invoicing_period_end, amend_reason y correction_method ya no se retornan en la respuesta GET. Usa invoice_references en su lugar.

Cambio incompatible — petición: los parámetros planos de escritura amended_number, amended_date, amended_invoicing_period_start, amended_invoicing_period_end, amend_reason, amend_code_tax y correction_method ya no se aceptan. Usa invoice_references en el cuerpo de la petición en su lugar.

Guía de migración — mapeo de campos:

v2026-03-02 (campo plano)	v2026-04-20 (`invoice_references`)	Notas
`amended_number`	`invoice_references[].number`	Lectura + Escritura
`amended_date`	`invoice_references[].date`	Lectura + Escritura
`amended_invoicing_period_start`	`invoice_references[].invoicing_period_start`	Solo escritura en v2026-04-20 (no se retorna en la respuesta)
`amended_invoicing_period_end`	`invoice_references[].invoicing_period_end`	Solo escritura en v2026-04-20 (no se retorna en la respuesta)
`amend_reason`	`invoice_references[].reason`	Lectura + Escritura
`amend_code_tax`	`invoice_references[].tax_correction_code`	Ya era solo escritura en v2026-03-02
`correction_method`	`invoice_references[].correction_method`	Lectura + Escritura
(nuevo)	`invoice_references[].reference_type` (`amend` o `prepayment`)	Obligatorio
(nuevo)	`invoice_references[].tax_registration_code`	Lectura + Escritura
(nuevo)	`invoice_references[].total_amount`	Lectura + Escritura

Endpoints afectados:

GET /invoices/{id} — retorna el array invoice_references. Los campos planos de enmienda se han eliminado de la respuesta.
POST /accounts/{account}/invoices — acepta el array invoice_references.
PATCH /invoices/{id} — acepta el array invoice_references. Usa { "id": 123, "_destroy": true } para eliminar una referencia.

Campos de InvoiceReference:

Campo	Tipo	Descripción
`id`	entero	Identificador de solo lectura
`reference_type`	cadena	`amend` o `prepayment` (obligatorio)
`number`	cadena	Número de factura de la factura referenciada
`series_code`	cadena	Código de serie de la factura referenciada
`date`	fecha	Fecha de emisión de la factura referenciada
`invoicing_period_start`	fecha	Inicio del período de facturación (solo escritura; no se retorna)
`invoicing_period_end`	fecha	Fin del período de facturación (solo escritura; no se retorna)
`reason`	cadena	Motivo de la corrección
`correction_method`	cadena	Método de corrección (p. ej. Facturae 01-04)
`tax_registration_code`	cadena	Código de registro de la autoridad fiscal (p. ej. número NrKSeF de KSeF)
`tax_correction_code`	cadena	Código de tipo de corrección fiscal (p. ej. TypKorekty de KSeF)
`total_amount`	float	Total de la factura referenciada
`currency`	cadena	Moneda de total_amount (ISO 4217)

Ejemplo: Crear una nota de crédito que referencia la factura original

curl --request POST \
     --url 'https://app-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 '{
       "invoice": {
         "number": "CN-2026-001",
         "date": "2026-03-15",
         "is_credit_note": true,
         "contact_id": {CONTACT_ID},
         "invoice_references": [
           {
             "reference_type": "amend",
             "number": "INV-2026-042",
             "date": "2026-02-10"
           }
         ],
         "invoice_lines_attributes": [
           { "quantity": 2, "price": 50, "description": "Product returned",
             "taxes_attributes": [{ "name": "VAT", "percent": 21 }] }
         ]
       }
     }'

Ejemplo: Crear una factura ROZ (liquidación) con referencias de anticipo

curl --request POST \
     --url 'https://app-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 '{
       "invoice": {
         "number": "ROZ/2026/001",
         "date": "2026-08-17",
         "type_code": "ROZ",
         "contact_id": {CONTACT_ID},
         "invoice_references": [
           {
             "reference_type": "prepayment",
             "tax_registration_code": "9999999999-20260215-8BEF280C8D35-4D"
           },
           {
             "reference_type": "prepayment",
             "number": "ZAL/2026/100"
           }
         ],
         "invoice_lines_attributes": [
           { "quantity": 1, "price": 8000, "description": "Service — final settlement",
             "taxes_attributes": [{ "name": "VAT", "percent": 8 }] }
         ]
       }
     }'

Ejemplo: Crear un KOR_ZAL (corrección de anticipo) con referencia de enmienda

curl --request POST \
     --url 'https://app-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 '{
       "invoice": {
         "number": "KOR_ZAL/2026/001",
         "date": "2026-03-17",
         "type_code": "KOR_ZAL",
         "contact_id": {CONTACT_ID},
         "invoice_references": [
           {
             "reference_type": "amend",
             "number": "ZAL/2026/050",
             "date": "2026-02-15",
             "tax_registration_code": "9999999999-20260215-8BEF280C8D35-4D",
             "tax_correction_code": "1",
             "total_amount": 20000.0,
             "currency": "PLN"
           }
         ],
         "invoice_lines_attributes": [
           { "quantity": 1, "price": 5000, "description": "Advance correction",
             "taxes_attributes": [{ "name": "VAT", "percent": 8 }] }
         ]
       }
     }'

Cambios en el transporte Peppol

🚨 Breaking

La respuesta del transporte Peppol se ha actualizado con nuevos campos que reemplazan los indicadores de estado de publicación anteriores. Las operaciones de publicación y retirada ahora se ejecutan de manera asíncrona — consulta estos campos para seguir el progreso.

Campos eliminados:

standard_documents — ya no se retorna en las respuestas. Si se envía en una petición, se ignora silenciosamente. El sistema ahora configura automáticamente los documentos estándar para todos los transportes Peppol.
pending_peppol_directory_publish — reemplazado por peppol_directory_status.

Nuevos campos:

sml_status — cadena. Estado de registro en el SML (Service Metadata Locator).
peppol_directory_status — cadena. Estado de listado en el Directorio Peppol.
reception_document_types — array de objetos de tipo de documento (code, name) que lista los tipos de documento que este participante puede recibir via Peppol. Vacío cuando reception es false o la empresa no tiene servicios de recepción configurados.

Valores posibles para los dos campos de estado: "not_published", "processing" (operación asíncrona pendiente) y "published". Estos campos reflejan el estado de publicación de este participante en la red Peppol via B2Brouter como Punto de Acceso.

Ejemplo de respuesta (transporte Peppol, participante publicado):

{
  "code": "peppol",
  "enabled": true,
  "reception": true,
  "invoice": true,
  "credit_note": true,
  "self_billing": false,
  "order": true,
  "application_response": true,
  "pin_scheme": "0208",
  "pin_value": "0123456789",
  "sml_status": "published",
  "peppol_directory_status": "published",
  "reception_document_types": [
    { "code": "xml.ubl.invoice.be", "name": "Belgium UBL.BE Invoice 3.0" },
    { "code": "xml.ubl.credit_note.bis3", "name": "Peppol BIS3 CreditNote" }
  ]
}

Endpoints afectados:

GET /accounts/{account}/transports — la respuesta incluye sml_status, peppol_directory_status y reception_document_types; ya no retorna standard_documents ni pending_peppol_directory_publish.
PATCH /transports/{code} — el parámetro standard_documents se ignora silenciosamente.
PUT /transports/{code} — el parámetro standard_documents se ignora silenciosamente.

Añadir `exchange_rate` y `exchange_date` a la respuesta de factura

Nuevos campos en la respuesta de factura:

exchange_rate (decimal, anulable) — el tipo de cambio utilizado para la conversión de moneda cuando la moneda de la factura difiere de la moneda local de la autoridad fiscal.
exchange_date (fecha, anulable) — la fecha del tipo de cambio.

Estos campos se aceptaban anteriormente en la entrada (solo escritura) pero no se retornaban en las respuestas de la API. A partir de la v2026-04-20, se incluyen en la respuesta.

Endpoints afectados:

GET /invoices/{id} — retorna exchange_rate y exchange_date.
POST /accounts/{account}/invoices — retorna los dos campos en la respuesta.
PATCH /invoices/{id} — retorna los dos campos en la respuesta.

Añadir `order_date` a la respuesta de factura

Nuevo campo order_date (fecha, anulable) en la respuesta de factura. Es la fecha del pedido de compra, que complementa el campo existente ponumber (referencia del pedido de compra). Anteriormente se aceptaba en la entrada pero no se retornaba en las respuestas de la API.

Endpoints afectados:

GET /invoices/{id} — retorna order_date.
POST /accounts/{account}/invoices — retorna order_date en la respuesta.
PATCH /invoices/{id} — retorna order_date en la respuesta.

Corregir el error tipográfico `clasification_code_scheme` en las respuestas de líneas de factura

🚨 Breaking

El campo de respuesta de línea de factura clasification_code_scheme estaba mal escrito (faltaba una ‘s’) en todas las versiones anteriores de la API. A partir de la v2026-04-20, la respuesta retorna la ortografía correcta: classification_code_scheme.

Petición (entrada): classification_code_scheme — sin cambios, todas las versiones ya aceptaban la ortografía correcta.
Respuesta (salida): classification_code_scheme — corregido en la v2026-04-20. Las versiones anteriores (v2025-01-01, v2025-10-13, v2026-03-02) continúan retornando clasification_code_scheme para evitar romper las integraciones existentes.

Si tu código lee clasification_code_scheme de las respuestas de líneas de factura, actualízalo a classification_code_scheme al migrar a la v2026-04-20.

Endpoints afectados:

GET /invoices/{id} — lines[].classification_code_scheme ahora usa la ortografía correcta en la respuesta.
POST /accounts/{account}/invoices — el cuerpo de la respuesta usa la ortografía correcta.
PATCH /invoices/{id} — el cuerpo de la respuesta usa la ortografía correcta.

Añadir `total_amount_due` a la petición de factura

Nuevo campo de solo escritura total_amount_due en el recurso Factura. Acepta el total de la factura directamente, evitando el cálculo basado en líneas.

Principalmente pensado para las facturas KSeF ZAL (pago a cuenta) y KOR_ZAL (corrección de anticipo), donde el total de la factura no puede derivarse de las líneas de factura de la manera habitual. Se mapea al campo P_15 en el XML FA(3) de KSeF.

total_amount_due no se retorna en la respuesta (solo escritura). El total resuelto se retorna a través de los campos estándar total y payable_amount.

Endpoints afectados:

POST /accounts/{account}/invoices — acepta total_amount_due en el cuerpo de la petición.
PATCH /invoices/{id} — acepta total_amount_due en el cuerpo de la petición.

Cambios KSeF

Añadir soporte a `third_party` en las facturas

Tres nuevos campos en el recurso Factura soportan escenarios de facturación KSeF polaca donde interviene un tercero (Podmiot3):

apply_to_local_government_unit — booleano, marca la factura como dirigida a una JST (Jednostka Samorządu Terytorialnego), una unidad subordinada de gobierno local.
apply_to_vat_group_member — booleano, marca la factura como dirigida a un miembro de GV (Grupa VAT).
third_party — objeto anidado con el nombre del tercero, NIP (tin_value) y dirección. Obligatorio cuando cualquiera de los indicadores es true.

Estos campos son mutuamente excluyentes: solo uno de apply_to_local_government_unit o apply_to_vat_group_member puede ser true en la misma factura.

Estos campos utilizan un patrón de respuesta expandible: no se incluyen en las respuestas de la API por defecto. Solicítalos via el parámetro de consulta include.

Al generar un informe fiscal KSeF a partir de una factura, B2Brouter utiliza estos indicadores para establecer automáticamente los roles del comprador/tercero. El contacto de la factura pasa a ser el comprador (Podmiot2) y el third_party pasa a ser Podmiot3 (rol 8 para JST, rol 10 para GV).

Endpoints afectados:

GET /invoices/{id} — retorna los nuevos campos cuando se solicitan via ?include=apply_to_local_government_unit,apply_to_vat_group_member,third_party
POST /accounts/{account}/invoices — acepta los nuevos campos en el cuerpo de la petición
PATCH /invoices/{id} — acepta los nuevos campos en el cuerpo de la petición

Ejemplo: Crear una factura para una unidad de gobierno (JST)

curl --request POST \
     --url 'https://app-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 '{
       "invoice": {
         "number": "FV/2026/001",
         "date": "2026-03-23",
         "contact_id": {CONTACT_ID},
         "apply_to_local_government_unit": true,
         "third_party": {
           "role": "local_government_unit_recipient",
           "name": "Przykład Jednostka Podrzędna",
           "tin_value": "PL1234567890",
           "tin_scheme": "9945",
           "address": "ul. Przykładowa 12",
           "city": "Warszawa",
           "postalcode": "00-001",
           "country": "pl"
         },
         "invoice_lines_attributes": [
           { "quantity": 1, "price": 100, "description": "Service" }
         ]
       }
     }'

Ejemplo: Leer factura con campos expandidos

curl --request GET \
     --url 'https://app-staging.b2brouter.net/invoices/{INVOICE_ID}?include=apply_to_local_government_unit,apply_to_vat_group_member,third_party' \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

{
  "invoice": {
    "id": 67890,
    "apply_to_local_government_unit": true,
    "apply_to_vat_group_member": false,
    "third_party": {
      "role": "local_government_unit_recipient",
      "name": "Przykład Jednostka Podrzędna",
      "tin_value": "PL1234567890",
      "tin_scheme": "9945",
      "cin_value": null,
      "cin_scheme": null,
      "address": "ul. Przykładowa 12",
      "address2": null,
      "city": "Warszawa",
      "postalcode": "00-001",
      "province": null,
      "country": "pl"
    },
    ...
  }
}

Añadir `customer_party_jst` y `customer_party_gv` a los informes fiscales KSeF

Dos nuevos campos booleanos en los informes fiscales KSeF indican si el comprador es una unidad de gobierno o un miembro de un grupo de IVA:

customer_party_jst — true si el comprador es una unidad subordinada de gobierno local. Por defecto false.
customer_party_gv — true si el comprador es un miembro de un grupo de IVA. Por defecto false.

Al crear informes fiscales a partir de facturas, estos campos se establecen automáticamente basándose en los indicadores apply_to_local_government_unit y apply_to_vat_group_member de la factura. Al crear informes fiscales directamente via la API, hay que establecerlos explícitamente.

Endpoints afectados:

POST /accounts/{account}/tax_reports — acepta y retorna customer_party_jst y customer_party_gv cuando el tipo de informe fiscal es KSeF.
POST /accounts/{account}/tax_reports/import — acepta los nuevos campos al importar informes fiscales KSeF.

Ejemplo: Crear un informe fiscal KSeF para una unidad de gobierno

{
  "tax_report": {
    "type": "KSeF",
    "customer_party_jst": true,
    "customer_party_gv": false,
    ...
  }
}

Añadir `purchase_order_date` y `despatch_advice_reference` a los informes fiscales KSeF

Dos nuevos campos en los informes fiscales KSeF para soportar la trazabilidad de pedidos y albaranes:

purchase_order_date — fecha (YYYY-MM-DD), anulable. La fecha del pedido de compra (BT-92). Se mapea automáticamente desde la fecha de pedido de la factura.
despatch_advice_reference — cadena, anulable. El número de referencia del albarán (BT-16). Se mapea automáticamente desde el número de nota de entrega de la factura.

Ambos campos se pueden leer y escribir via la API.

Endpoints afectados:

POST /accounts/{account}/tax_reports — acepta y retorna los dos campos cuando el tipo de informe fiscal es KSeF.
GET /tax_reports/{id} — retorna los dos campos para los informes fiscales KSeF.

Añadir `supplier_party_krs`, `supplier_party_regon` y `supplier_party_bdo` a los informes fiscales KSeF

Tres nuevos campos en los informes fiscales KSeF para los identificadores del registro de empresas polaco:

supplier_party_krs — cadena, anulable. Número KRS (Krajowy Rejestr Sądowy) del proveedor. Debe tener exactamente 10 dígitos si se proporciona.
supplier_party_regon — cadena, anulable. REGON (número de identificación estadística) del proveedor. Debe tener exactamente 9 o 14 dígitos si se proporciona.
supplier_party_bdo — cadena, anulable. Número BDO (registro de base de datos de residuos) del proveedor.

Se mapean automáticamente desde los valores CIN de la empresa de la factura cuando los códigos de esquema coinciden (8036 para REGON, 8037 para KRS, 8038 para BDO). Si se proporcionan directamente via la API, supplier_party_krs y supplier_party_regon se validan y retornan 422 Unprocessable Entity si no cumplen los requisitos de dígitos.

Endpoints afectados:

POST /accounts/{account}/tax_reports — acepta y retorna los campos cuando el tipo de informe fiscal es KSeF.
GET /tax_reports/{id} — retorna los campos para los informes fiscales KSeF.

Añadir `supplier_contact_phone` y `supplier_contact_email` a los informes fiscales KSeF

Dos nuevos campos en los informes fiscales KSeF para los datos de contacto del proveedor (EN16931 BT-41, BT-42, BT-43):

supplier_contact_phone — cadena, anulable. Número de teléfono de contacto del proveedor (BT-42). Se mapea desde el teléfono de la empresa de la factura. Se exporta en el XML FA(3) como DaneKontaktowe/Telefon.
supplier_contact_email — cadena, anulable. Dirección de correo electrónico de contacto del proveedor (BT-43). Se mapea desde el correo electrónico de la empresa de la factura. Se exporta en el XML FA(3) como DaneKontaktowe/Email.

Endpoints afectados:

POST /accounts/{account}/tax_reports — acepta y retorna los campos cuando el tipo de informe fiscal es KSeF.
GET /tax_reports/{id} — retorna los campos para los informes fiscales KSeF.

Añadir `previous_advance_total` a los informes fiscales KSeF

Nuevo campo en los informes fiscales KSeF para facturas de corrección de anticipo (KOR_ZAL):

previous_advance_total — decimal, anulable. El total bruto de la factura ZAL (pago a cuenta) original que se está corrigiendo. Se mapea al campo P_15ZK en el XML FA(3) de KSeF. Obligatorio cuando invoice_type_code es KOR_ZAL.

Al generar un informe fiscal a partir de una factura, este valor se mapea automáticamente desde la referencia de enmienda total_amount de la factura. Al crear un informe fiscal directamente via la API, hay que establecerlo explícitamente.

Endpoints afectados:

POST /accounts/{account}/tax_reports — acepta y retorna el campo cuando el tipo de informe fiscal es KSeF.
GET /tax_reports/{id} — retorna el campo para los informes fiscales KSeF.

Ejemplo: Crear un informe fiscal KOR_ZAL

{
  "tax_report": {
    "type": "KSeF",
    "invoice_type_code": "KOR_ZAL",
    "previous_advance_total": 1230.00,
    ...
  }
}

Añadir `order_total_amount` a los informes fiscales KSeF

Nuevo campo en los informes fiscales KSeF para facturas de pago a cuenta y corrección de anticipo:

order_total_amount — decimal, anulable. El valor total del pedido (WartoscZamowienia). Obligatorio cuando invoice_type_code es ZAL o KOR_ZAL.

Al generar un informe fiscal a partir de una factura, este valor se mapea automáticamente desde la factura. Al crear un informe fiscal directamente via la API, hay que establecerlo explícitamente para las facturas ZAL y KOR_ZAL.

Endpoints afectados:

POST /accounts/{account}/tax_reports — acepta y retorna el campo cuando el tipo de informe fiscal es KSeF.
GET /tax_reports/{id} — retorna el campo para los informes fiscales KSeF.

Añadir `prepayment_references` a los informes fiscales KSeF

Nuevo campo de array en los informes fiscales KSeF para facturas de liquidación (ROZ/KOR_ROZ):

prepayment_references — array de objetos, cada uno referenciando una factura de pago a cuenta que esta factura ROZ liquida. Cada entrada se mapea a un elemento FakturaZaliczkowa en el XML FA(3) de KSeF. Obligatorio (no vacío) cuando invoice_type_code es ROZ o KOR_ROZ.

Cada objeto del array tiene:

Campo	Tipo	Descripción
`id`	entero	Identificador interno de solo lectura (retornado en la respuesta)
`number`	cadena	Número de factura de la factura de pago a cuenta (`NrFaZaliczkowej`). Obligatorio cuando `registration_code` está ausente.
`registration_code`	cadena	Número de registro KSeF de la factura de pago a cuenta (`NrKSeFFaZaliczkowej`). Obligatorio cuando `number` está ausente.
`_destroy`	booleano	Establece a `true` (con `id`) para eliminar la referencia

Al generar un informe fiscal a partir de una factura, las referencias se mapean automáticamente desde las referencias de factura prepayment de la factura. Al crear directamente via la API, hay que establecerlas explícitamente.

Endpoints afectados:

POST /accounts/{account}/tax_reports — acepta y retorna el array cuando el tipo de informe fiscal es KSeF.
GET /tax_reports/{id} — retorna el array para los informes fiscales KSeF.

Ejemplo: Crear un informe fiscal ROZ

{
  "tax_report": {
    "type": "KSeF",
    "invoice_type_code": "ROZ",
    "prepayment_references": [
      { "registration_code": "9999999999-20260215-8BEF280C8D35-4D" },
      { "number": "ZAL/2026/001" }
    ],
    ...
  }
}

Hacer editables los campos `third_party` en los informes fiscales KSeF

Los campos de identificador third_party_* en los informes fiscales KSeF eran anteriormente de solo lectura — se poblaban únicamente al generar un informe fiscal a partir de una factura. A partir de la v2026-04-20, se pueden escribir para que los consumidores de la API puedan establecer los datos de Podmiot3 al crear informes fiscales directamente.

Campos nuevos con permiso de escritura:

third_party_name — cadena, anulable.
third_party_id — cadena, anulable. Valor del identificador (p. ej. GLN).
third_party_scheme — cadena, anulable. Esquema del identificador (p. ej. "0088" para GLN).
third_party_tax_id — cadena, anulable. NIP / número de IVA del tercero.
third_party_tax_scheme — cadena, anulable. Código de esquema fiscal.
third_party_country — cadena, anulable. Código de país ISO 3166-1 alfa-2.
third_party_endpoint_id — cadena, anulable. Identificador de punto final Peppol para propósitos de enrutamiento.

Campos ya editables en versiones anteriores (sin cambios): third_party_role (código KSeF 2–11, p. ej. 2 = receptor de entrega, 8 = unidad de gobierno local, 10 = miembro de grupo de IVA), third_party_address, third_party_postalcode, third_party_city.

Validación: cuando third_party_role está establecido, third_party_country es ahora obligatorio. La API retorna 422 Unprocessable Entity con param: "third_party_country" si falta. (Esta validación es nueva en la v2026-04-20 — posible porque third_party_country ahora es editable.)

Endpoints afectados:

POST /accounts/{account}/tax_reports — acepta los campos de tercero en el cuerpo de la petición.
PATCH /tax_reports/{id} — acepta los campos de tercero en el cuerpo de la petición.

Añadir códigos de tipo de factura KSeF

Nuevos valores de type_code para los flujos de trabajo de facturas de pago a cuenta y corrección de KSeF polaco:

`type_code`	Descripción
`ZAL`	Factura de pago a cuenta (Faktura zaliczkowa)
`ROZ`	Factura de liquidación (Faktura rozliczeniowa) — liquida una o más facturas ZAL
`KOR_ZAL`	Corrección de una factura de pago a cuenta
`KOR_ROZ`	Corrección de una factura de liquidación
`KOR`	Factura de corrección genérica (KSeF FA(3) Korekta)
`VAT`	Factura solo de IVA (Faktura VAT)
`UPR`	Factura simplificada (Faktura uproszczona)

Estos valores se aceptan al crear (POST /accounts/{account}/invoices) y actualizar (PUT /invoices/{id}), y se retornan en las respuestas de factura. Los códigos de tipo existentes (IssuedInvoice, ReceivedInvoice, etc.) no cambian.

Endpoints afectados:

POST /accounts/{account}/invoices — acepta los nuevos valores de type_code.
PUT /invoices/{id} — acepta los nuevos valores de type_code.
GET /invoices/{id} — puede retornar los nuevos valores en el campo type_code.

Eliminado

Eliminar `payment_method_info` de la respuesta de factura

🚨 Breaking

El campo payment_method_info se ha eliminado de la respuesta de factura. Este campo contenía un resumen en formato HTML de los detalles de pago (p. ej. "Bank transfer to<br />IBAN ES13 210..."), que es redundante con los campos estructurados ya presentes en la respuesta (payment_method, contact_iban, contact_bic, etc.) y se renderizaba mal en los consumidores JSON.

Endpoints afectados:

GET /invoices/{id} — ya no retorna payment_method_info.
POST /accounts/{account}/invoices — ya no retorna payment_method_info en la respuesta.
PATCH /invoices/{id} — ya no retorna payment_method_info en la respuesta.

v2026-04-20

Changelog

Resumen de los cambios

Añadido

Endpoint de verificación de NIF

Webhook de verificación de NIF

Añadir identificadores adicionales a las cuentas (routing_codes)

Añadir auto_remittance a las cuentas

Añadir skip_line_taxable_base_rounding a las cuentas

Exponer cin_value y cin_scheme en los campos de contacto de factura

Modificado

Validar tin_value y tin_scheme contra el contacto padre

Requerir tin_value o cin_value al crear un contacto en línea en facturas

Reemplazar los campos de enmienda por invoice_references

Cambios en el transporte Peppol

Añadir exchange_rate y exchange_date a la respuesta de factura

Añadir order_date a la respuesta de factura

Corregir el error tipográfico clasification_code_scheme en las respuestas de líneas de factura

Añadir total_amount_due a la petición de factura

Cambios KSeF

Añadir soporte a third_party en las facturas

Añadir customer_party_jst y customer_party_gv a los informes fiscales KSeF

Añadir purchase_order_date y despatch_advice_reference a los informes fiscales KSeF

Añadir supplier_party_krs, supplier_party_regon y supplier_party_bdo a los informes fiscales KSeF

Añadir supplier_contact_phone y supplier_contact_email a los informes fiscales KSeF

Añadir previous_advance_total a los informes fiscales KSeF

Añadir order_total_amount a los informes fiscales KSeF

Añadir prepayment_references a los informes fiscales KSeF

Hacer editables los campos third_party en los informes fiscales KSeF

Añadir códigos de tipo de factura KSeF

Eliminado

Eliminar payment_method_info de la respuesta de factura

Añadir identificadores adicionales a las cuentas (`routing_codes`)

Añadir `auto_remittance` a las cuentas

Añadir `skip_line_taxable_base_rounding` a las cuentas

Exponer `cin_value` y `cin_scheme` en los campos de contacto de factura

Validar `tin_value` y `tin_scheme` contra el contacto padre

Requerir `tin_value` o `cin_value` al crear un contacto en línea en facturas

Reemplazar los campos de enmienda por `invoice_references`

Añadir `exchange_rate` y `exchange_date` a la respuesta de factura

Añadir `order_date` a la respuesta de factura

Corregir el error tipográfico `clasification_code_scheme` en las respuestas de líneas de factura

Añadir `total_amount_due` a la petición de factura

Añadir soporte a `third_party` en las facturas

Añadir `customer_party_jst` y `customer_party_gv` a los informes fiscales KSeF

Añadir `purchase_order_date` y `despatch_advice_reference` a los informes fiscales KSeF

Añadir `supplier_party_krs`, `supplier_party_regon` y `supplier_party_bdo` a los informes fiscales KSeF

Añadir `supplier_contact_phone` y `supplier_contact_email` a los informes fiscales KSeF

Añadir `previous_advance_total` a los informes fiscales KSeF

Añadir `order_total_amount` a los informes fiscales KSeF

Añadir `prepayment_references` a los informes fiscales KSeF

Hacer editables los campos `third_party` en los informes fiscales KSeF

Eliminar `payment_method_info` de la respuesta de factura