v2026-04-20

Changelog

Selecciona aquesta versió enviant X-B2B-API-Version: 2026-04-20 a les capçaleres de la teva petició.

Aquesta versió implementa canvis incompatibles. Cada canvi incompatible està marcat amb l’etiqueta Breaking.

Resum dels canvis

Canvi	Àrea
Afegir identificadors addicionals als comptes (`routing_codes`)	Comptes
Afegir `auto_remittance` als comptes	Comptes
Afegir `skip_line_taxable_base_rounding` als comptes	Comptes
Exposar `cin_value` i `cin_scheme` als camps de contacte de factura	Factures
Substituir els camps de rectificació per `invoice_references` Breaking	Factures
Canvis al transport Peppol Breaking (eliminar `standard_documents`, `pending_peppol_directory_publish`; afegir `sml_status`, `peppol_directory_status`, `reception_document_types`)	Transports
Validar `tin_value` i `tin_scheme` contra el contacte pare Breaking	Contactes
Requerir `tin_value` o `cin_value` en crear un contacte en línia a factures Breaking	Factures
Nou endpoint de verificació de NIF	Verificacions NIF
Nou event de webhook `tin_verification.finished`	Webhooks
Afegir `exchange_rate` i `exchange_date` a la resposta de factura	Factures
Eliminar `payment_method_info` de la resposta de factura Breaking	Factures
Corregir el tipogràfic `clasification_code_scheme` a les respostes de línies de factura Breaking	Factures
Afegir `order_date` a la resposta de factura	Factures
Afegir `total_amount_due` a la petició de factura	Factures (KSeF)
Afegir suport a `third_party` a les factures	Factures (KSeF)
Afegir `customer_party_jst` i `customer_party_gv` als informes fiscals	Report fiscal (KSeF)
Afegir `purchase_order_date` i `despatch_advice_reference` als informes fiscals	Report fiscal (KSeF)
Afegir `supplier_party_krs`, `supplier_party_regon` i `supplier_party_bdo` als informes fiscals	Report fiscal (KSeF)
Afegir `supplier_contact_phone` i `supplier_contact_email` als informes fiscals	Report fiscal (KSeF)
Afegir `previous_advance_total` als informes fiscals	Report fiscal (KSeF)
Afegir `order_total_amount` als informes fiscals	Report fiscal (KSeF)
Afegir `prepayment_references` als informes fiscals	Report fiscal (KSeF)
Fer editables els camps `third_party` als informes fiscals	Report fiscal (KSeF)
Afegir codis de tipus de factura KSeF	Factures (KSeF)

Afegit

Endpoint de verificació de NIF

Nou endpoint per verificar parells NIF (Número d’Identificació Fiscal) + nom contra un cens de l’autoritat fiscal. Actualment només admet Espanya (AEAT).

El processament és asíncron: POST retorna 202 Accepted immediatament, i els resultats es recuperen via GET o es reben a través de l’event de webhook tin_verification.finished. Els resultats de les darreres 24 hores es guarden a la memòria caché per evitar trucades redundants a l’autoritat fiscal.

Nous endpoints:

POST /tin_verifications?country=es — Envia un lot de fins a 20.000 parells NIF+nom per a la verificació.
GET /tin_verifications/{id} — Recupera l’estat i els resultats d’una petició de verificació.

Exemple: Enviar verificació

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": []
}

Exemple: Obtenir resultats

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

Quan census_match és true, el camp name dels resultats retorna el nom canònic del cens de l’autoritat fiscal; en cas contrari, retorna el nom enviat.

Webhook de verificació de NIF

El nou event de webhook tin_verification.finished s’activa quan una petició de verificació de NIF arriba a un estat terminal (success o failed). El payload conté només l’ID de la petició i l’estat — utilitza GET /tin_verifications/{id} per obtenir els resultats complets.

Subscriu-te a aquest event quan configuris un webhook:

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

Afegir identificadors addicionals als comptes (`routing_codes`)

Nou objecte routing_codes als comptes per suportar fins a 5 Números d’Identificació d’Empresa addicionals més enllà del cin principal. Conté els camps cin1_value, cin1_scheme fins a cin5_value, cin5_scheme (cadena, nul·lable). Els codis d’esquema es retornen com a cadenes de 4 caràcters amb zeros a l’esquerra (p. ex. "0088"), o null quan l’esquema és desconegut.

Resposta GET:

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

Entrada POST/PUT: utilitza el mateix objecte routing_codes dins del cos de la petició. Si es proporciona cinN_value, cinN_scheme és obligatori (i viceversa).

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

Endpoints afectats:

POST /accounts — accepta routing_codes al cos de la petició.
PUT /accounts/{account} — accepta routing_codes al cos de la petició.
GET /accounts/{account} — retorna routing_codes a la resposta.
GET /accounts — retorna routing_codes a cada entrada de compte.

Afegir `auto_remittance` als comptes

Nou camp booleà auto_remittance (per defecte false) als comptes que activa la generació automàtica de referències de remesa estructurades (codis OGM) per a factures belgues, sense requerir un grup d’integració que les imposi.

Quan auto_remittance és true i tant el compte com el contacte de la factura es troben a Bèlgica, la factura rebrà automàticament una referència de remesa estructurada — el mateix comportament que anteriorment només estava disponible a través de grups d’integració que requerien codis OGM.

Endpoints afectats:

POST /accounts — accepta auto_remittance al cos de la petició.
PUT /accounts/{account} — accepta auto_remittance al cos de la petició.
GET /accounts/{account} — retorna auto_remittance a la resposta.

Afegir `skip_line_taxable_base_rounding` als comptes

Nou camp booleà skip_line_taxable_base_rounding (per defecte false) als comptes. Quan s’activa, en lloc d’arrodonir la base imposable i l’impost de cada línia individualment, arrodoneix només els totals acumulats finals. Això redueix la deriva per arrodoniment a les factures amb moltes línies.

Requereix que apply_taxes_per_line sigui true — l’API retorna 422 Unprocessable Entity si skip_line_taxable_base_rounding s’estableix a true mentre apply_taxes_per_line és false.

Endpoints afectats:

POST /accounts — accepta skip_line_taxable_base_rounding al cos de la petició.
PUT /accounts/{account} — accepta skip_line_taxable_base_rounding al cos de la petició.
GET /accounts/{account} — retorna skip_line_taxable_base_rounding a la resposta.
GET /accounts — retorna skip_line_taxable_base_rounding a cada entrada de compte.

Exposar `cin_value` i `cin_scheme` als camps de contacte de factura

L’objecte contact a les respostes de factura ara inclou els camps cin_value i cin_scheme juntament amb els existents tin_value i tin_scheme.

Endpoints afectats:

GET /invoices/{id} — l’objecte contact ara inclou cin_value i cin_scheme.
GET /accounts/{account}/invoices — l’objecte contact a les entrades de l’índex ara inclou cin_value i cin_scheme.

Modificat

Validar `tin_value` i `tin_scheme` contra el contacte pare

🚨 Breaking

Les peticions POST /accounts/{account}/contacts i PATCH /contacts/{id} amb parent_id ara validen tin_value i tin_scheme contra el contacte pare. Les oficines (unitats organitzatives) hereten el NIF del seu contacte pare; si el tin_value proporcionat no coincideix amb el del pare, l’API retorna 422 Unprocessable Entity amb codi parameter_invalid. Anteriorment, els valors no coincidents s’ignoraven silenciosament.

cin_value i cin_scheme s’hereten del contacte pare i no es validen contra ell.

Per migrar, omet tin_value en crear oficines (recomanat), o assegura’t que coincideix exactament amb el valor del pare.

Endpoints afectats:

POST /accounts/{account}/contacts — rebutja tin_value / tin_scheme no coincidents quan parent_id està establert.
PATCH /contacts/{id} — rebutja tin_value / tin_scheme no coincidents quan el contacte té un pare.

Requerir `tin_value` o `cin_value` en crear un contacte en línia a factures

🚨 Breaking

POST /accounts/{account}/invoices ara valida que quan es proporciona un objecte contact en línia, almenys un de tin_value o cin_value estigui present. Si els dos falten, l’API retorna 422 Unprocessable Entity amb codi parameter_blank i param: "contact".

Les factures simplificades (IssuedSimplifiedInvoice) com ara tiquets, estan exemptes d’aquesta validació.

Per migrar, inclou sempre tin_value o cin_value en enviar un contact en línia en crear una factura. Com a alternativa, utilitza contact_id per referenciar un contacte existent.

Endpoints afectats:

POST /accounts/{account}/invoices — rebutja els objectes contact en línia sense tin_value ni cin_value (excepte per a IssuedSimplifiedInvoice).

Substituir els camps de rectificació per `invoice_references`

🚨 Breaking Un nou array invoice_references substitueix els camps plans de rectificació (amended_number, amended_date, amended_invoicing_period_start, amended_invoicing_period_end, amend_reason, amend_code_tax, correction_method) al recurs Factura.

Cada referència té un reference_type:

amend — factura correctiva que referencia l’original. Màxim 1 per factura.
prepayment — factura de liquidació (ROZ) que referencia factures de bestreta (ZAL). Se’n permeten múltiples.

Canvi incompatible — resposta: els camps plans amended_number, amended_date, amended_invoicing_period_start, amended_invoicing_period_end, amend_reason i correction_method ja no es retornen a la resposta GET. Utilitza invoice_references en el seu lloc.

Canvi incompatible — petició: els paràmetres plans d’escriptura amended_number, amended_date, amended_invoicing_period_start, amended_invoicing_period_end, amend_reason, amend_code_tax i correction_method ja no s’accepten. Utilitza invoice_references al cos de la petició en el seu lloc.

Guia de migració — mapatge de camps:

v2026-03-02 (camp pla)	v2026-04-20 (`invoice_references`)	Notes
`amended_number`	`invoice_references[].number`	Lectura + Escriptura
`amended_date`	`invoice_references[].date`	Lectura + Escriptura
`amended_invoicing_period_start`	`invoice_references[].invoicing_period_start`	Només escriptura a v2026-04-20 (no es retorna a la resposta)
`amended_invoicing_period_end`	`invoice_references[].invoicing_period_end`	Només escriptura a v2026-04-20 (no es retorna a la resposta)
`amend_reason`	`invoice_references[].reason`	Lectura + Escriptura
`amend_code_tax`	`invoice_references[].tax_correction_code`	Ja era només escriptura a v2026-03-02
`correction_method`	`invoice_references[].correction_method`	Lectura + Escriptura
(nou)	`invoice_references[].reference_type` (`amend` o `prepayment`)	Obligatori
(nou)	`invoice_references[].tax_registration_code`	Lectura + Escriptura
(nou)	`invoice_references[].total_amount`	Lectura + Escriptura

Endpoints afectats:

GET /invoices/{id} — retorna l’array invoice_references. Els camps plans de rectificació s’han eliminat de la resposta.
POST /accounts/{account}/invoices — accepta l’array invoice_references.
PATCH /invoices/{id} — accepta l’array invoice_references. Utilitza { "id": 123, "_destroy": true } per eliminar una referència.

Camps d’InvoiceReference:

Camp	Tipus	Descripció
`id`	int	Identificador de només lectura
`reference_type`	cadena	`amend` o `prepayment` (obligatori)
`number`	cadena	Número de factura de la factura referenciada
`series_code`	cadena	Codi de sèrie de la factura referenciada
`date`	data	Data d’emissió de la factura referenciada
`invoicing_period_start`	data	Inici del període de facturació (només escriptura; no es retorna)
`invoicing_period_end`	data	Final del període de facturació (només escriptura; no es retorna)
`reason`	cadena	Motiu de la correcció
`correction_method`	cadena	Mètode de correcció (p. ex. Facturae 01-04)
`tax_registration_code`	cadena	Codi de registre de l’autoritat fiscal (p. ex. número NrKSeF de KSeF)
`tax_correction_code`	cadena	Codi de tipus de correcció fiscal (p. ex. TypKorekty de KSeF)
`total_amount`	float	Total de la factura referenciada
`currency`	cadena	Moneda de total_amount (ISO 4217)

Exemple: Crear una nota de crèdit 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 }] }
         ]
       }
     }'

Exemple: Crear una factura ROZ (liquidació) amb referències de bestreta

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

Exemple: Crear un KOR_ZAL (correcció de bestreta) amb referència de rectificació

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

Canvis al transport Peppol

🚨 Breaking

La resposta del transport Peppol s’ha actualitzat amb nous camps que substitueixen els indicadors d’estat de publicació anteriors. Les operacions de publicació i retirada ara s’executen de manera asíncrona — consulta aquests camps per seguir el progrés.

Camps eliminats:

standard_documents — ja no es retorna a les respostes. Si s’envia en una petició, s’ignora silenciosament. El sistema ara configura automàticament els documents estàndard per a tots els transports Peppol.
pending_peppol_directory_publish — substituït per peppol_directory_status.

Nous camps:

sml_status — cadena. Estat de registre al SML (Service Metadata Locator).
peppol_directory_status — cadena. Estat de llistat al Directori Peppol.
reception_document_types — array d’objectes de tipus de document (code, name) que llista els tipus de document que aquest participant pot rebre via Peppol. Buit quan reception és false o l’empresa no té serveis de recepció configurats.

Valors possibles per als dos camps d’estat: "not_published", "processing" (operació asíncrona pendent) i "published". Aquests camps reflecteixen l’estat de publicació d’aquest participant a la xarxa Peppol via B2Brouter com a Punt d’Accés.

Exemple de resposta (transport Peppol, participant publicat):

{
  "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 afectats:

GET /accounts/{account}/transports — la resposta inclou sml_status, peppol_directory_status i reception_document_types; ja no retorna standard_documents ni pending_peppol_directory_publish.
PATCH /transports/{code} — el paràmetre standard_documents s’ignora silenciosament.
PUT /transports/{code} — el paràmetre standard_documents s’ignora silenciosament.

Afegir `exchange_rate` i `exchange_date` a la resposta de factura

Nous camps a la resposta de factura:

exchange_rate (decimal, nul·lable) — el tipus de canvi utilitzat per a la conversió de moneda quan la moneda de la factura difereix de la moneda local de l’autoritat fiscal.
exchange_date (data, nul·lable) — la data del tipus de canvi.

Aquests camps s’acceptaven anteriorment en l’entrada (només escriptura) però no es retornaven a les respostes de l’API. A partir de la v2026-04-20, s’inclouen a la resposta.

Endpoints afectats:

GET /invoices/{id} — retorna exchange_rate i exchange_date.
POST /accounts/{account}/invoices — retorna els dos camps a la resposta.
PATCH /invoices/{id} — retorna els dos camps a la resposta.

Afegir `order_date` a la resposta de factura

Nou camp order_date (data, nul·lable) a la resposta de factura. És la data de la comanda de compra, que complementa el camp existent ponumber (referència de la comanda de compra). Anteriorment s’acceptava en l’entrada però no es retornava a les respostes de l’API.

Endpoints afectats:

GET /invoices/{id} — retorna order_date.
POST /accounts/{account}/invoices — retorna order_date a la resposta.
PATCH /invoices/{id} — retorna order_date a la resposta.

Corregir el tipogràfic `clasification_code_scheme` a les respostes de línies de factura

🚨 Breaking

El camp de resposta de línia de factura clasification_code_scheme estava mal escrit (faltava una ‘s’) en totes les versions anteriors de l’API. A partir de la v2026-04-20, la resposta retorna l’ortografia correcta: classification_code_scheme.

Petició (entrada): classification_code_scheme — sense canvis, totes les versions ja acceptaven l’ortografia correcta.
Resposta (sortida): classification_code_scheme — corregit a la v2026-04-20. Les versions anteriors (v2025-01-01, v2025-10-13, v2026-03-02) continuen retornant clasification_code_scheme per evitar trencar les integracions existents.

Si el teu codi llegeix clasification_code_scheme de les respostes de línies de factura, actualitza’l a classification_code_scheme en migrar a la v2026-04-20.

Endpoints afectats:

GET /invoices/{id} — lines[].classification_code_scheme ara utilitza l’ortografia correcta a la resposta.
POST /accounts/{account}/invoices — el cos de la resposta utilitza l’ortografia correcta.
PATCH /invoices/{id} — el cos de la resposta utilitza l’ortografia correcta.

Afegir `total_amount_due` a la petició de factura

Nou camp de només escriptura total_amount_due al recurs Factura. Permet indicar el total de la factura directament, sense que es calculi a partir de les línies.

Principalment pensat per a les factures KSeF ZAL (pagament a compte) i KOR_ZAL (correcció de bestreta), on el total de la factura no es pot derivar de les línies de factura de la manera habitual. Es mapeja al camp P_15 a l’XML FA(3) de KSeF.

total_amount_due no es retorna a la resposta (només escriptura). El total resolt es retorna a través dels camps estàndard total i payable_amount.

Endpoints afectats:

POST /accounts/{account}/invoices — accepta total_amount_due al cos de la petició.
PATCH /invoices/{id} — accepta total_amount_due al cos de la petició.

Canvis KSeF

Afegir suport a `third_party` a les factures

Tres nous camps al recurs Factura suporten escenaris de facturació KSeF polonesa on intervé un tercer (Podmiot3):

apply_to_local_government_unit — booleà, marca la factura com adreçada a una JST (Jednostka Samorządu Terytorialnego), una unitat subordinada de govern local.
apply_to_vat_group_member — booleà, marca la factura com adreçada a un membre de GV (Grupa VAT).
third_party — objecte niat amb el nom del tercer, NIP (tin_value) i adreça. Obligatori quan qualsevol dels indicadors és true.

Aquests camps són mútuament excloents: només un de apply_to_local_government_unit o apply_to_vat_group_member pot ser true a la mateixa factura.

Aquests camps utilitzen un patró de resposta expandible: no s’inclouen a les respostes de l’API per defecte. Sol·licita’ls via el paràmetre de consulta include.

En generar un informe fiscal KSeF a partir d’una factura, B2Brouter utilitza aquests indicadors per establir automàticament els rols del comprador/tercer. El contacte de la factura passa a ser el comprador (Podmiot2) i el third_party passa a ser Podmiot3 (rol 8 per a JST, rol 10 per a GV).

Endpoints afectats:

GET /invoices/{id} — retorna els nous camps quan es sol·liciten via ?include=apply_to_local_government_unit,apply_to_vat_group_member,third_party
POST /accounts/{account}/invoices — accepta els nous camps al cos de la petició
PATCH /invoices/{id} — accepta els nous camps al cos de la petició

Exemple: Crear una factura per a una unitat de govern (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" }
         ]
       }
     }'

Exemple: Llegir factura amb camps expandits

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"
    },
    ...
  }
}

Afegir `customer_party_jst` i `customer_party_gv` als informes fiscals KSeF

Dos nous camps booleans als informes fiscals KSeF indiquen si el comprador és una unitat de govern o un membre d’un grup de VAT:

customer_party_jst — true si el comprador és una unitat subordinada de govern local. Per defecte false.
customer_party_gv — true si el comprador és un membre d’un grup de VAT. Per defecte false.

En crear informes fiscals a partir de factures, aquests camps s’estableixen automàticament basant-se en els indicadors apply_to_local_government_unit i apply_to_vat_group_member de la factura. En crear informes fiscals directament via l’API, cal establir-los explícitament.

Endpoints afectats:

POST /accounts/{account}/tax_reports — accepta i retorna customer_party_jst i customer_party_gv quan el tipus d’informe fiscal és KSeF.
POST /accounts/{account}/tax_reports/import — accepta els nous camps en importar informes fiscals KSeF.

Exemple: Crear un informe fiscal KSeF per a una unitat de govern

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

Afegir `purchase_order_date` i `despatch_advice_reference` als informes fiscals KSeF

Dos nous camps als informes fiscals KSeF per suportar la traçabilitat de comandes i albarans:

purchase_order_date — data (YYYY-MM-DD), nul·lable. La data de la comanda de compra (BT-92). Es mapeja automàticament des de la data de comanda de la factura.
despatch_advice_reference — cadena, nul·lable. El número de referència de l’albarà (BT-16). Es mapeja automàticament des del número de nota d’entrega de la factura.

Els dos camps es poden llegir i escriure via l’API.

Endpoints afectats:

POST /accounts/{account}/tax_reports — accepta i retorna els dos camps quan el tipus d’informe fiscal és KSeF.
GET /tax_reports/{id} — retorna els dos camps per als informes fiscals KSeF.

Afegir `supplier_party_krs`, `supplier_party_regon` i `supplier_party_bdo` als informes fiscals KSeF

Tres nous camps als informes fiscals KSeF per als identificadors del registre d’empreses polonès:

supplier_party_krs — cadena, nul·lable. Número KRS (Krajowy Rejestr Sądowy) del proveïdor. Ha de tenir exactament 10 dígits si es proporciona.
supplier_party_regon — cadena, nul·lable. REGON (número d’identificació estadística) del proveïdor. Ha de tenir exactament 9 o 14 dígits si es proporciona.
supplier_party_bdo — cadena, nul·lable. Número BDO (registre de base de dades de residus) del proveïdor.

Es mapegen automàticament des dels valors CIN de l’empresa de la factura quan els codis d’esquema coincideixen (8036 per a REGON, 8037 per a KRS, 8038 per a BDO). Si es proporcionen directament via l’API, supplier_party_krs i supplier_party_regon es validen i retornen 422 Unprocessable Entity si no compleixen els requisits de dígits.

Endpoints afectats:

POST /accounts/{account}/tax_reports — accepta i retorna els camps quan el tipus d’informe fiscal és KSeF.
GET /tax_reports/{id} — retorna els camps per als informes fiscals KSeF.

Afegir `supplier_contact_phone` i `supplier_contact_email` als informes fiscals KSeF

Dos nous camps als informes fiscals KSeF per a les dades de contacte del proveïdor (EN16931 BT-41, BT-42, BT-43):

supplier_contact_phone — cadena, nul·lable. Número de telèfon de contacte del proveïdor (BT-42). Es mapeja des del telèfon de l’empresa de la factura. S’exporta a l’XML FA(3) com a DaneKontaktowe/Telefon.
supplier_contact_email — cadena, nul·lable. Adreça de correu electrònic de contacte del proveïdor (BT-43). Es mapeja des del correu electrònic de l’empresa de la factura. S’exporta a l’XML FA(3) com a DaneKontaktowe/Email.

Endpoints afectats:

POST /accounts/{account}/tax_reports — accepta i retorna els camps quan el tipus d’informe fiscal és KSeF.
GET /tax_reports/{id} — retorna els camps per als informes fiscals KSeF.

Afegir `previous_advance_total` als informes fiscals KSeF

Nou camp als informes fiscals KSeF per a factures de correcció de bestreta (KOR_ZAL):

previous_advance_total — decimal, nul·lable. El total brut de la factura ZAL (pagament a compte) original que s’està corregint. Es mapeja al camp P_15ZK a l’XML FA(3) de KSeF. Obligatori quan invoice_type_code és KOR_ZAL.

En generar un informe fiscal a partir d’una factura, aquest valor es mapeja automàticament des de la referència de rectificació total_amount de la factura. En crear un informe fiscal directament via l’API, cal establir-lo explícitament.

Endpoints afectats:

POST /accounts/{account}/tax_reports — accepta i retorna el camp quan el tipus d’informe fiscal és KSeF.
GET /tax_reports/{id} — retorna el camp per als informes fiscals KSeF.

Exemple: Crear un informe fiscal KOR_ZAL

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

Afegir `order_total_amount` als informes fiscals KSeF

Nou camp als informes fiscals KSeF per a factures de pagament a compte i correcció de bestreta:

order_total_amount — decimal, nul·lable. El valor total de la comanda (WartoscZamowienia). Obligatori quan invoice_type_code és ZAL o KOR_ZAL.

En generar un informe fiscal a partir d’una factura, aquest valor es mapeja automàticament des de la factura. En crear un informe fiscal directament via l’API, cal establir-lo explícitament per a les factures ZAL i KOR_ZAL.

Endpoints afectats:

POST /accounts/{account}/tax_reports — accepta i retorna el camp quan el tipus d’informe fiscal és KSeF.
GET /tax_reports/{id} — retorna el camp per als informes fiscals KSeF.

Afegir `prepayment_references` als informes fiscals KSeF

Nou camp d’array als informes fiscals KSeF per a factures de liquidació (ROZ/KOR_ROZ):

prepayment_references — array d’objectes, cadascun referenciant una factura de pagament a compte que aquesta factura ROZ liquida. Cada entrada es mapeja a un element FakturaZaliczkowa a l’XML FA(3) de KSeF. Obligatori (no buit) quan invoice_type_code és ROZ o KOR_ROZ.

Cada objecte de l’array té:

Camp	Tipus	Descripció
`id`	enter	Identificador intern de només lectura (retornat a la resposta)
`number`	cadena	Número de factura de la factura de pagament a compte (`NrFaZaliczkowej`). Obligatori quan `registration_code` és absent.
`registration_code`	cadena	Número de registre KSeF de la factura de pagament a compte (`NrKSeFFaZaliczkowej`). Obligatori quan `number` és absent.
`_destroy`	booleà	Estableix a `true` (amb `id`) per eliminar la referència

En generar un informe fiscal a partir d’una factura, les referències es mapegen automàticament des de les referències de factura prepayment de la factura. En crear directament via l’API, cal establir-les explícitament.

Endpoints afectats:

POST /accounts/{account}/tax_reports — accepta i retorna l’array quan el tipus d’informe fiscal és KSeF.
GET /tax_reports/{id} — retorna l’array per als informes fiscals KSeF.

Exemple: 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" }
    ],
    ...
  }
}

Fer editables els camps `third_party` als informes fiscals KSeF

Els camps d’identificador third_party_* als informes fiscals KSeF eren anteriorment de només lectura — es poblaven únicament en generar un informe fiscal a partir d’una factura. A partir de la v2026-04-20, es poden escriure perquè els consumidors de l’API puguin establir les dades de Podmiot3 en crear informes fiscals directament.

Camps nous amb permís d’escriptura:

third_party_name — cadena, nul·lable.
third_party_id — cadena, nul·lable. Valor de l’identificador (p. ex. GLN).
third_party_scheme — cadena, nul·lable. Esquema de l’identificador (p. ex. "0088" per a GLN).
third_party_tax_id — cadena, nul·lable. NIP / número de VAT del tercer.
third_party_tax_scheme — cadena, nul·lable. Codi d’esquema fiscal.
third_party_country — cadena, nul·lable. Codi de país ISO 3166-1 alfa-2.
third_party_endpoint_id — cadena, nul·lable. Identificador de punt final Peppol per a propòsits d’encaminament.

Camps ja escrits en versions anteriors (sense canvis): third_party_role (codi KSeF 2–11, p. ex. 2 = receptor de lliurament, 8 = unitat de govern local, 10 = membre de grup de VAT), third_party_address, third_party_postalcode, third_party_city.

Validació: quan third_party_role està establert, third_party_country ara és obligatori. L’API retorna 422 Unprocessable Entity amb param: "third_party_country" si falta. (Aquesta validació és nova a la v2026-04-20 — possible perquè third_party_country ara és editable.)

Endpoints afectats:

POST /accounts/{account}/tax_reports — accepta els camps de tercer al cos de la petició.
PATCH /tax_reports/{id} — accepta els camps de tercer al cos de la petició.

Afegir codis de tipus de factura KSeF

Nous valors de type_code per als fluxos de treball de factures de pagament a compte i correcció de KSeF polonès:

`type_code`	Descripció
`ZAL`	Factura de pagament a compte (Faktura zaliczkowa)
`ROZ`	Factura de liquidació (Faktura rozliczeniowa) — liquida una o més factures ZAL
`KOR_ZAL`	Correcció d’una factura de pagament a compte
`KOR_ROZ`	Correcció d’una factura de liquidació
`KOR`	Factura de correcció genèrica (KSeF FA(3) Korekta)
`VAT`	Factura només de VAT (Faktura VAT)
`UPR`	Factura simplificada (Faktura uproszczona)

Aquests valors s’accepten en crear (POST /accounts/{account}/invoices) i actualitzar (PUT /invoices/{id}), i es retornen a les respostes de factura. Els codis de tipus existents (IssuedInvoice, ReceivedInvoice, etc.) no canvien.

Endpoints afectats:

POST /accounts/{account}/invoices — accepta els nous valors de type_code.
PUT /invoices/{id} — accepta els nous valors de type_code.
GET /invoices/{id} — pot retornar els nous valors al camp type_code.

Eliminat

Eliminar `payment_method_info` de la resposta de factura

🚨 Breaking

El camp payment_method_info s’ha eliminat de la resposta de factura. Aquest camp contenia un resum en format HTML dels detalls de pagament (p. ex. "Bank transfer to<br />IBAN ES13 210..."), que duplicava la informació ja disponible en camps estructurats a la resposta (payment_method, contact_iban, contact_bic, etc.) i es renderitzava malament als consumidors JSON.

Endpoints afectats:

GET /invoices/{id} — ja no retorna payment_method_info.
POST /accounts/{account}/invoices — ja no retorna payment_method_info a la resposta.
PATCH /invoices/{id} — ja no retorna payment_method_info a la resposta.

v2026-04-20

Changelog

Resum dels canvis

Afegit

Endpoint de verificació de NIF

Webhook de verificació de NIF

Afegir identificadors addicionals als comptes (routing_codes)

Afegir auto_remittance als comptes

Afegir skip_line_taxable_base_rounding als comptes

Exposar cin_value i cin_scheme als camps de contacte de factura

Modificat

Validar tin_value i tin_scheme contra el contacte pare

Requerir tin_value o cin_value en crear un contacte en línia a factures

Substituir els camps de rectificació per invoice_references

Canvis al transport Peppol

Afegir exchange_rate i exchange_date a la resposta de factura

Afegir order_date a la resposta de factura

Corregir el tipogràfic clasification_code_scheme a les respostes de línies de factura

Afegir total_amount_due a la petició de factura

Canvis KSeF

Afegir suport a third_party a les factures

Afegir customer_party_jst i customer_party_gv als informes fiscals KSeF

Afegir purchase_order_date i despatch_advice_reference als informes fiscals KSeF

Afegir supplier_party_krs, supplier_party_regon i supplier_party_bdo als informes fiscals KSeF

Afegir supplier_contact_phone i supplier_contact_email als informes fiscals KSeF

Afegir previous_advance_total als informes fiscals KSeF

Afegir order_total_amount als informes fiscals KSeF

Afegir prepayment_references als informes fiscals KSeF

Fer editables els camps third_party als informes fiscals KSeF

Afegir codis de tipus de factura KSeF

Eliminat

Eliminar payment_method_info de la resposta de factura

Afegir identificadors addicionals als comptes (`routing_codes`)

Afegir `auto_remittance` als comptes

Afegir `skip_line_taxable_base_rounding` als comptes

Exposar `cin_value` i `cin_scheme` als camps de contacte de factura

Validar `tin_value` i `tin_scheme` contra el contacte pare

Requerir `tin_value` o `cin_value` en crear un contacte en línia a factures

Substituir els camps de rectificació per `invoice_references`

Afegir `exchange_rate` i `exchange_date` a la resposta de factura

Afegir `order_date` a la resposta de factura

Corregir el tipogràfic `clasification_code_scheme` a les respostes de línies de factura

Afegir `total_amount_due` a la petició de factura

Afegir suport a `third_party` a les factures

Afegir `customer_party_jst` i `customer_party_gv` als informes fiscals KSeF

Afegir `purchase_order_date` i `despatch_advice_reference` als informes fiscals KSeF

Afegir `supplier_party_krs`, `supplier_party_regon` i `supplier_party_bdo` als informes fiscals KSeF

Afegir `supplier_contact_phone` i `supplier_contact_email` als informes fiscals KSeF

Afegir `previous_advance_total` als informes fiscals KSeF

Afegir `order_total_amount` als informes fiscals KSeF

Afegir `prepayment_references` als informes fiscals KSeF

Fer editables els camps `third_party` als informes fiscals KSeF

Eliminar `payment_method_info` de la resposta de factura