KSeF

El KSeF (Krajowy System e-Faktur, o sistema nacional polonès de factura electrònica) és el sistema obligatori de facturació electrònica de Polònia, operat pel Ministeri de Finances polonès. El KSeF garanteix la integritat i l’autenticitat de les factures mitjançant l’enviament en format XML estructurat i la certificació digital.

Aquesta normativa obliga les empreses que operen a Polònia a adoptar sistemes capaços de generar, validar i transmetre factures de manera segura a la plataforma KSeF. La REST API de B2Brouter proporciona una solució tècnica que permet que la teva empresa compleixi amb KSeF, traslladant la complexitat a B2Brouter i deixant-te centrar en la lògica de negoci.

Què és KSeF?

KSeF és la plataforma centralitzada de facturació electrònica de Polònia, esdevinguda obligatòria per als subjectes passius d’IVA. Garanteix que totes les factures siguin:

Validades contra esquemes XML oficials (estructura FA)
Certificades digitalment amb certificats qualificats
Emmagatzemades de manera segura per l’autoritat fiscal polonesa
Verificables mitjançant un comprovant oficial (UPO - Urzędowe Poświadczenie Odbioru)

En la pràctica, KSeF requereix:

Crear un fitxer XML de factura estructurada conforme a la variant d’esquema FA 3 - FA(3)
Autenticar-se a la plataforma KSeF amb un certificat electrònic qualificat vinculat al teu NIP polonès
Enviar la factura a KSeF perquè sigui validada i registrada
Rebre i conservar l’UPO com a prova del registre
Incloure el codi QR amb el número de referència KSeF a les factures emeses

Amb B2Brouter pots abstraure bona part de la complexitat d’aquest procés i complir amb KSeF. Hauràs de proporcionar el teu certificat electrònic qualificat en format PKCS#12, i B2Brouter s’encarregarà de l’autenticació, l’enviament i la recuperació de l’UPO.

B2Brouter genera tax reports en format FA(3) (variant de formulari 3, versió d’esquema 1-0E), que és l’estàndard actual per als enviaments KSeF.

Configurar KSeF amb l’API de B2Brouter

El primer pas és configurar KSeF per a cada compte, identificat per NIP polonès, per al qual vulguis enviar tax reports. Pots consultar la Tax Report Settings Guide per a una descripció completa del procés.

Entorns de B2Brouter i integració amb KSeF

Comença amb sandbox per a les primeres proves d’API i validació de payloads. Els enviaments a KSeF es simulen al sandbox, així que no cal cap certificat KSeF. Passa a l’entorn staging quan estiguis a punt per provar amb un certificat KSeF real contra l’entorn de proves o demo de KSeF.

B2Brouter es connecta a diferents entorns KSeF segons la teva configuració:

Entorn de B2Brouter	Entorns KSeF disponibles	Requisits del certificat
Production API `api.b2brouter.net`	KSeF Production només	Certificat KSeF de producció
Staging API `api-staging.b2brouter.net`	KSeF Test (per defecte) KSeF Demo (configurable)	Test: certificat KSeF de proves o autosignat Demo: certificat KSeF de preproducció

Per a desenvolupament i proves:

Utilitza la Staging API (api-staging.b2brouter.net)
Per defecte es connecta a l’entorn test de KSeF
- Accepta certificats KSeF de proves (recomanat)
- També accepta certificats autosignats per a desenvolupament ràpid i proves d’integració
Pots configurar opcionalment l’entorn demo establint environment: "demo" en crear el tax report setting
- Requereix un certificat KSeF de preproducció
Per a producció, només funcionaran certificats KSeF de producció

Requisits del certificat

L’autenticació cap a KSeF utilitza certificats digitals en format PKCS#12 (.p12 o .pfx). El tipus de certificat necessari depèn de l’entorn KSeF:

Per a l’entorn de producció:

Certificat KSeF de producció
El client ha d’iniciar sessió amb signatura qualificada o perfil de confiança (Profil Zaufany)
Ha d’accedir a la secció KSeF i generar un certificat KSeF dedicat vinculat al seu NIP
El subject del certificat ha de coincidir amb el teu NIP polonès o estar autoritzat via ZAW-FA
Contrasenya/PIN del certificat

Per a l’entorn demo (preproducció):

Certificat KSeF de preproducció
El certificat ha d’estar en format PKCS#12
El subject del certificat ha de coincidir amb el teu NIP polonès o estar autoritzat via ZAW-FA
Contrasenya/PIN del certificat

Per a l’entorn test (desenvolupament):

Certificat KSeF de proves (recomanat) o certificat autosignat (només per a desenvolupament)
El certificat ha d’estar en format PKCS#12
En certificats autosignats, el número de sèrie hauria de coincidir amb el VAT number (NIP)
Contrasenya/PIN del certificat

Exemple: codificar el teu certificat

# Encode your certificate to base64 without line breaks
base64 -w 0 your-certificate.p12 > certificate-base64.txt

Crear KSeF Tax Report Setting

Has de configurar la integració KSeF per a cada empresa per a la qual vulguis enviar factures estructurades. Aquesta configuració defineix com B2Brouter gestiona la generació i enviament de factures a KSeF en nom del teu sistema. Ho has de configurar per empresa abans d’enviar cap factura.

Aquest pas de configuració donarà d’alta el client a KSeF i farà una prova de connexió.
Si el certificat o la configuració són invàlids, l’endpoint retornarà un error.

Exemple de petició:

curl --request GET \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_report_settings \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report_setting": {
      "code": "ksef",
      "type_operation": "services",
      "credit_note_code": "1",
      "certificate": "MIIKZAIBAzCCCh4GCSqGSIb3DQEHAaCCCg8Egg...",
      "certificate_pin": "YourCertificatePassword",
      "auto_generate": true,
      "auto_send": true,
      "enabled": true
    }
  }'

Paràmetres:

code: ha de ser "ksef"
type_operation: tipus d’operació per defecte ("services" o "goods")
credit_note_code: codi d’efecte de rectificació per defecte ("1", "2" o "3")
certificate: certificat PKCS#12 codificat en base64
certificate_pin: contrasenya del certificat
auto_generate: genera automàticament tax reports per a les factures
auto_send: envia automàticament tax reports a KSeF

Treballar amb tax reports KSeF

B2Brouter ofereix dues maneres de treballar amb KSeF:

Tax Report API: per tenir control directe sobre la creació i enviament del tax report.
Invoice API: si utilitzes B2Brouter per emetre factures, els tax reports es generen automàticament.

Tax Report API

La Tax Report API et dona el màxim control sobre el procés d’enviament a KSeF. Pots crear tax reports proporcionant dades JSON estructurades que B2Brouter convertirà a format XML FA(3).

L’estructura del JSON per als tax reports de B2Brouter es basa en PEPPOL Continuous Transaction Control (CTC). Això significa que la Tax Report API de B2Brouter és una API universal, no només orientada a KSeF sinó pensada per gestionar tax reporting arreu del món.

Important: els tax reports per a KSeF utilitzen tax_report_lines i tax_breakdowns. Cada tax_report_line representa una línia de factura amb quantitat, posició, unitat, preu i informació fiscal pròpies.

Crear un tax report

Per crear un tax report KSeF, crida l’endpoint create tax report.

Exemple: factura bàsica amb IVA

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/001",
      "description": "Consulting services",
      "customer_party_name": "Example Company Sp. z o.o.",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "Consulting hours",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 1000.0,
          "tax_amount": 230.00
        }
      ]
    }
  }'

Exemple: factura rectificativa (KOR)

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "KOR",
      "amend_type": "2",
      "invoice_date": "2025-11-08",
      "tax_point_date": "2025-11-07",
      "invoice_number": "FK/2025/11/001",
      "description": "Correction of invoice F/2025/11/001",
      "amended_ksef_number": "1234567890-20251107-ABCD1234-EF",
      "amended_date": "2025-11-07",
      "amended_number":  "F/2025/11/001",
      "customer_party_name": "Example Company Sp. z o.o.",
      "customer_party_tax_scheme": "9945",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "Consulting hours",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00,
          "ksef_amended": true
        },
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "PCE",
          "description": "Consulting hours - new line",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 1000.0,
          "tax_amount": 230.00
        }
      ]
    }
  }'

Exemple: exportació exempta de béns - factura IVA en moneda estrangera

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/003",
      "description": "Sample Exempt VAT Invoice -  Export of Goods",
      "customer_party_name": "EFG Ltd.",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Flower (St) 1, Seattle, WA 99999",
      "customer_party_country": "us",
      "currency": "USD",
      "exchange_rate": 3.65,
      "tax_inclusive_amount": 8000,
      "tax_amount": 0,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 20,
          "unit_code": "szt.",
          "description": "lodówka Zimnotech mk1",
          "price": 400,
          "tax_code": "0 EX",
          "tax_exclusive_amount": 8000,
          "tax_amount": 0,
          "tax_inclusive_amount": 8000
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "E",
          "percent": 0.0,
          "taxable_base": 8000,
          "tax_amount": 0,
          "comment": "reason why exempt"
        }
      ]
    }
  }'

Exemple: factura IVA amb pagament complet rebut en el moment de l’emissió - Zaplacono

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "payment_date": "2025-11-07",
      "payable_amount": 0,
      "invoice_number": "F/2025/11/004",
      "description": "Sample VAT Invoice (full payment has been received at the time of issue)",
      "customer_party_name": "Example Company Sp. z o.o.",
      "customer_party_tax_scheme": "9945",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "product 1",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 1000.0,
          "tax_amount": 230.00
        }
      ]
    }
  }'

Exemple: factura ZAL (bestreta)

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "ZAL",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "payment_date": "2025-11-07",
      "payable_amount": 0,
      "invoice_number": "F/2025/11/005",
      "description": "Sample ZAL Invoice (full payment has been received at the time of issue)",
      "customer_party_name": "Example Company Sp. z o.o.",
      "customer_party_tax_scheme": "9945",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "product 1",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 1000.0,
          "tax_amount": 230.00
        }
      ]
    }
  }'

Exemple: factura ROZ (liquidació de bestretes)

Una factura ROZ liquida l’import restant després de totes les bestretes. Referencia factures ZAL anteriors a través de prepayment_references. Cada referència es mapeja a un element FakturaZaliczkowa dins de l’XML FA(3).

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "ROZ",
      "invoice_date": "2026-08-17",
      "tax_point_date": "2026-09-17",
      "invoice_number": "FV2026/08/12",
      "description": "Settlement invoice",
      "customer_party_name": "Jan Kowalski",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "ul. Przykładowa 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 306899.80,
      "tax_amount": 22720.76,
      "type_operation": "goods",
      "prepayment_references": [
        { "registration_code": "9999999999-20260215-8BEF280C8D35-4D" },
        { "number": "FZ2026/03/200" }
      ],
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 1,
          "unit_code": "C62",
          "description": "mieszkanie 50m^2",
          "price": 280177.59,
          "tax_code": "8",
          "tax_exclusive_amount": 280177.59,
          "tax_amount": 22414.21,
          "tax_inclusive_amount": 302591.80
        },
        {
          "position": 2,
          "quantity": 1,
          "unit_code": "C62",
          "description": "usługi dodatkowe",
          "price": 4001.55,
          "tax_code": "23",
          "tax_exclusive_amount": 4001.55,
          "tax_amount": 306.55,
          "tax_inclusive_amount": 4308.00
        }
      ],
      "tax_breakdowns": [
        { "name": "PTU", "category": "S", "percent": 8.0, "taxable_base": 280177.59, "tax_amount": 22414.21 },
        { "name": "PTU", "category": "S", "percent": 23.0, "taxable_base": 4001.55, "tax_amount": 306.55 }
      ]
    }
  }'

prepayment_references: utilitza registration_code per al número KSeF (NrKSeFFaZaliczkowej) o number per al número de factura (NrFaZaliczkowej) quan la ZAL s’ha emès fora de KSeF.

Exemple: factura KOR_ZAL (rectificació de bestreta)

Una KOR_ZAL rectifica una factura ZAL emesa anteriorment. Utilitza previous_advance_total per indicar l’import original de la bestreta (P_15ZK a l’XML FA(3)).

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "KOR_ZAL",
      "amend_type": "1",
      "invoice_date": "2026-03-17",
      "tax_point_date": "2026-02-15",
      "invoice_number": "FK2026/03/7",
      "description": "Correction of advance invoice FZ2026/02/150",
      "amended_ksef_number": "9999999999-20260215-8BEF280C8D35-4D",
      "amended_date": "2026-02-15",
      "amended_number": "FZ2026/02/150",
      "customer_party_name": "Jan Kowalski",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "ul. Przykładowa 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 25000.00,
      "tax_amount": 4674.80,
      "previous_advance_total": 20000.00,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 1,
          "unit_code": "C62",
          "description": "mieszkanie 50m^2",
          "price": 300000,
          "tax_code": "23",
          "tax_exclusive_amount": 20325.20,
          "tax_amount": 4674.80,
          "tax_inclusive_amount": 25000.00
        }
      ],
      "tax_breakdowns": [
        { "name": "PTU", "category": "S", "percent": 23.0, "taxable_base": 20325.20, "tax_amount": 4674.80 }
      ]
    }
  }'

previous_advance_total: 20000.00: total brut de la ZAL original que es rectifica.

Exemple: factura JST (unitat de govern local)

Factura adreçada a una unitat subordinada del govern local (JST). El comprador (Podmiot2) és l’entitat mare; el destinatari real és un Podmiot3 amb rol 8.

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2026-03-23",
      "tax_point_date": "2026-03-23",
      "invoice_number": "F/2026/JST/001",
      "description": "Services for local government unit",
      "customer_party_name": "Gmina Kraków",
      "customer_party_tax_id": "6762450871",
      "customer_party_address": "Plac Wszystkich Świętych 3-4",
      "customer_party_country": "pl",
      "customer_party_jst": true,
      "third_party_name": "Szkoła Podstawowa nr 7",
      "third_party_tax_id": "7654321098",
      "third_party_tax_scheme": "9945",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "Consulting services",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        { "name": "PTU", "category": "S", "percent": 23.0, "taxable_base": 1000.0, "tax_amount": 230.00 }
      ]
    }
  }'

customer_party_jst: true: estableix Podmiot2/JST a 1 a l’XML FA(3).
third_party_name / third_party_tax_id: destinatari JST, representat com Podmiot3 amb rol 8.
Per a factures d’un membre d’un grup d’IVA, utilitza customer_party_gv: true.

Exemple: factura UPR

Per a UPR, els camps customer_party_tax_id i customer_party_country són obligatoris.

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "UPR",
      "ticket": true,
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/006",
      "description": "Sample UPR Invoice",
      "customer_party_tax_id": "1234567890",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 12.30,
      "tax_amount": 2.30,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 1,
          "unit_code": "EA",
          "description": "product 1",
          "price": 10.00,
          "tax_code": "23",
          "tax_exclusive_amount": 10.00,
          "tax_amount": 2.30,
          "tax_inclusive_amount": 12.30
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 10.0,
          "tax_amount": 2.30
        }
      ]
    }
  }'

Exemple: factura domèstica amb reverse charge

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/007",
      "description": "Construction services - reverse charge",
      "customer_party_name": "Example Construction Sp. z o.o.",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 5000.00,
      "tax_amount": 0.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 1,
          "unit_code": "EA",
          "description": "Construction services per contract X",
          "price": 5000.00,
          "tax_code": "oo",
          "tax_exclusive_amount": 5000.00,
          "tax_amount": 0.00,
          "tax_inclusive_amount": 5000.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "VAT",
          "category": "AE",
          "percent": 0.0,
          "taxable_base": 5000.0,
          "tax_amount": 0.0,
          "scope": "domestic"
        }
      ]
    }
  }'

Exemple: reverse charge transfronterer (serveis)

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/008",
      "description": "Consulting services - cross-border",
      "customer_party_name": "Example Company GmbH",
      "customer_party_tax_id": "DE123456789",
      "customer_party_address": "Berlin Street 1, 10115 Berlin",
      "customer_party_country": "de",
      "currency": "EUR",
      "exchange_rate": 4.30,
      "tax_inclusive_amount": 3000.00,
      "tax_amount": 0.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 20,
          "unit_code": "HUR",
          "description": "IT consulting services",
          "price": 150.00,
          "tax_code": "np I",
          "tax_exclusive_amount": 3000.00,
          "tax_amount": 0.00,
          "tax_inclusive_amount": 3000.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "VAT",
          "category": "AE",
          "percent": 0.0,
          "taxable_base": 3000.0,
          "tax_amount": 0.0
        }
      ]
    }
  }'

Estructura de la resposta

La resposta inclourà el tax report en estat sending:

{
  "tax_report": {
    "id": 12345,
    "type": "KSeF",
    "state": "sending",
    "fingerprint": "a3f2c1b9e8d7...",
    "identifier": "https://ksef-test.mf.gov.pl/client-app/invoice/5792000046/2025-11-07/a3f2c1b9e8d7...",
    "qr": "iVBORw0KGgoAAAANSUhEUgAA...",
    ...
  }
}

Important: a diferència dels models tradicionals de clearance, B2Brouter pot generar fingerprint, identifier i qr immediatament en crear el tax report, sense esperar la confirmació de KSeF. Això és possible perquè aquests camps es calculen a partir de dades que ja tenim:

fingerprint: hash SHA-256 del document XML FA(3)
identifier: URL construïda a partir de NIP del proveïdor + data de factura + fingerprint
qr: imatge del codi QR que codifica la URL identifier

Etiqueta del codi QR:

Mentre el tax report és en estat sending, sota el codi QR s’hauria de mostrar “OFFLINE”
Quan el tax report arribi a registered i rebis el to_net_id, s’hauria de mostrar el número KSeF

Bona pràctica: tot i que les dades del QR són disponibles immediatament, es recomana esperar que el tax report arribi a estat registered abans d’imprimir o enviar la factura al client.

Comprovar l’estat del tax report

L’enviament a KSeF és asíncron. Has de supervisar l’estat del tax report.

Opció 1: webhooks (recomanat)

Configura un tax report webhook per rebre notificacions quan l’estat canviï a un estat final: registered o error.

Opció 2: polling

Consulta repetidament el get tax report endpoint fins que l’estat sigui final:

curl --request GET \
  --url https://api-staging.b2brouter.net/tax_reports/{TAX_REPORT_ID} \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

Entendre la resposta en estat `registered`

Quan el tax report arriba a registered, la resposta inclou el número oficial de referència KSeF:

{
  "tax_report": {
    "id": 12345,
    "type": "KSeF",
    "state": "registered",
    "to_net_id": "1234567890-20251107-ABCD1234-EF",
    "fingerprint": "a3f2c1b9e8d7...",
    "identifier": "https://ksef-test.mf.gov.pl/client-app/invoice/1234567890/2025-11-07/a3f2c1b9e8d7...",
    "qr": "iVBORw0KGgoAAAANSUhEUgAA...",
    ...
  }
}

Camp	Disponible	Descripció
`to_net_id`	Després de la confirmació KSeF	Número de referència KSeF. Mostra’l sota el codi QR en factures impreses o PDF
`fingerprint`	Immediatament en crear-lo	Hash SHA-256 de l’XML FA(3) enviat
`identifier`	Immediatament en crear-lo	URL del codi QR
`qr`	Immediatament en crear-lo	Imatge PNG codificada en base64 del codi QR

Descarregar l’UPO (comprovant oficial)

Quan el tax report arribi a registered, pots descarregar l’UPO amb el download response endpoint:

curl --request GET \
  --url https://api-staging.b2brouter.net/tax_reports/{TAX_REPORT_ID}/download_response \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Accept: application/xml'

Descarregar l’XML FA(3)

També pots descarregar l’XML FA(3) complet enviat a KSeF:

curl --request GET \
  --url https://api-staging.b2brouter.net/tax_reports/{TAX_REPORT_ID}/download \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Accept: application/xml'

Alternativament, el camp xml_base64 de la resposta del tax report conté l’XML en base64.

Gestió d’errors

Si el tax report arriba a estat error, consulta’n els detalls per obtenir la informació de l’error:

curl --request GET \
  --url https://api-staging.b2brouter.net/tax_reports/{TAX_REPORT_ID} \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

Equivalència entre els camps de Tax Report de B2Brouter i els nodes XML FA(3) de KSeF

L’estructura del JSON dels tax reports de B2Brouter es basa en PEPPOL Continuous Transaction Control (CTC). Els camps del payload JSON tenen noms diferents dels de la representació XML FA(3), perquè la Tax Report API de B2Brouter és una API universal pensada per gestionar tax reporting globalment.

Camps principals de factura

Camp de B2Brouter	Node XML FA(3) de KSeF
type	Ha de ser `"KSeF"`
invoice_type_code	`Fa > RodzajFaktury`
invoice_date	`Fa > P_1`
invoice_number	`Fa > P_2`
tax_point_date	`Fa > P_6`
customer_party_name	`Podmiot2 > DaneIdentyfikacyjne > Nazwa`
customer_party_tax_id	`Podmiot2 > DaneIdentyfikacyjne > NIP (PL)` o `NrVatUE (EU)` o `NrID (no UE)`
customer_party_country	`Podmiot2 > DaneIdentyfikacyjne > KodUE` o `KodKraju`
supplier_party_name	`Podmiot1 > DaneIdentyfikacyjne > Nazwa`
supplier_party_tax_id	`Podmiot1 > DaneIdentyfikacyjne > NIP`
supplier_party_country	`Podmiot1 > PrefiksPodatnika`
description	`Stopka > Informacje > StopkaFaktury`
currency	`Fa > KodWaluty`
exchange_rate	`Fa > KursWalutyZ`
payment_date	`Fa > Platnosc > TerminPlatnosci > Termin` o `Fa > Platnosc > DataZaplaty`
payable_amount	Quan és `0` juntament amb `payment_date`, marca la factura com a pagada
payment_means_type_code	`Fa > Platnosc > FormaPlatnosci`
payment_account_identifier	`Fa > Platnosc > RachunekBankowy > NrRB`
payment_service_provider_identifier	`Fa > Platnosc > RachunekBankowy > SWIFT`
amended_ksef_number	`Fa > DaneFaKorygowanej > NrKSeFFaKorygowanej`
tax_inclusive_amount	`Fa > P_15`
customer_party_jst	`Podmiot2 > JST`
customer_party_gv	`Podmiot2 > GV`
third_party_name	`Podmiot3 > DaneIdentyfikacyjne > Nazwa`
third_party_tax_id	`Podmiot3 > DaneIdentyfikacyjne > NIP`, `NrVatUE` o `NrID`
purchase_order_date	`Fa > WarunkiTransakcji > Zamowienia > DataZamowienia`
despatch_advice_reference	`Fa > WZ`
supplier_contact_email	`Podmiot1 > DaneKontaktowe > Email`
supplier_contact_phone	`Podmiot1 > DaneKontaktowe > Telefon`
supplier_party_regon	`Stopka > Rejestry > REGON`
supplier_party_krs	`Stopka > Rejestry > KRS`
supplier_party_bdo	`Stopka > Rejestry > BDO`
previous_advance_total	`Fa > P_15ZK`
prepayment_references	`Fa > FakturaZaliczkowa`

Línies del tax report (FaWiersz)

Camp de B2Brouter	Node XML FA(3) de KSeF
position	`FaWiersz > NrWierszaFa`
description	`FaWiersz > P_7`
unit_code	`FaWiersz > P_8A`
quantity	`FaWiersz > P_8B`
price	`FaWiersz > P_9A`
discount_amount	`FaWiersz > P_10`
tax_code	`FaWiersz > P_12`
tax_exclusive_amount	`FaWiersz > P_11`
tax_amount	`FaWiersz > P_11Vat`
ksef_amended	`FaWiersz > StanPrzed`

Desglossaments fiscals

Camp de B2Brouter	Node XML FA(3) de KSeF
name	Nom de l’esquema fiscal (`PTU`, `VAT`, etc.)
category	Categoria fiscal: `"S"`, `"E"`, `"AE"`
percent	Percentatge del tipus impositiu
taxable_base	`P_13_x`
tax_amount	`P_14_x`
comment	`Adnotacje > Zwolnienie > P_19A`
exemption_code	Override de `P_12`, accepta `zw`
no_subject_code	Override de `P_12`, accepta `np I`, `np II`
non_exemption_code	Override de `P_12`, accepta `0 KR`, `0 WDT`, `0 EX`, `oo`

Els tres camps *_code són opcionals. Si no s’estableixen, B2Brouter deriva el codi P_12 a partir de category, percent, scope i type_operation.

Resum de l’estructura FA(3)

<tns:Faktura xmlns:tns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <tns:Naglowek>
    <tns:KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</tns:KodFormularza>
    <tns:WariantFormularza>3</tns:WariantFormularza>
    <tns:DataWytworzeniaFa><!-- Timestamp --></tns:DataWytworzeniaFa>
    <tns:SystemInfo>B2Brouter</tns:SystemInfo>
  </tns:Naglowek>

  <tns:Podmiot1><!-- Supplier (Seller) --></tns:Podmiot1>
  <tns:Podmiot2><!-- Customer (Buyer) --></tns:Podmiot2>

  <tns:Fa>
    <!-- Invoice details: currency, dates, tax amounts -->
    <!-- Tax breakdown totals: P_13_x, P_14_x, P_15 -->
    <!-- Adnotacje (annotations/flags) -->
    <!-- RodzajFaktury (invoice type) -->

    <tns:FaWiersz><!-- Invoice line 1 --></tns:FaWiersz>
    <tns:FaWiersz><!-- Invoice line 2 --></tns:FaWiersz>

    <tns:Platnosc><!-- Payment details (optional) --></tns:Platnosc>
    <tns:WarunkiTransakcji><!-- Transaction conditions (optional) --></tns:WarunkiTransakcji>
  </tns:Fa>

  <tns:Stopka><!-- Footer/notes (optional) --></tns:Stopka>
</tns:Faktura>

Descripció de codis per a camps específics de KSeF

Codis de tipus de factura

Paràmetre: invoice_type_code

Codi	Descripció	S’utilitza per a
VAT	Factura bàsica	Factures regulars
KOR	Factura rectificativa	Rectificacions
ZAL	Factura de bestreta	Bestretes
ROZ	Factura segons l’article 106f sec. 3	Liquidacions
UPR	Factura simplificada	Simplificades
KOR_ZAL	Factura rectificativa de bestreta	Rectificacions
KOR_ROZ	Factura rectificativa de ROZ	Rectificacions

Codis d’efecte de nota de crèdit

Tipus d’efecte de la rectificació als registres d’IVA. S’utilitza per a factures rectificatives (KOR, KOR_ZAL, KOR_ROZ). Paràmetre: credit_note_code

Codi	Descripció
1	Rectificació amb efecte a la data de reconeixement de la factura original
2	Rectificació amb efecte a la data d’emissió de la factura rectificativa
3	Rectificació amb efecte en una altra data

Codis fiscals

Tipus i categories d’IVA utilitzats a Polònia. S’utilitzen a nivell de línia. Paràmetre: tax_code

Codi	Descripció
23	IVA estàndard del 23%
22	IVA estàndard del 22%
8	IVA reduït del 8%
7	IVA reduït del 7%
5	IVA reduït del 5%
4	IVA reduït del 4%
3	IVA reduït del 3%
0 WDT	Subministrament intracomunitari 0%
0 EX	Exportació 0%
0 KR	Tipus zero domèstic 0%
zw	Exempt d’IVA
oo	Reverse charge domèstic
np I	No subjecte a IVA - serveis transfronterers
np II	No subjecte a IVA - serveis domèstics

Codis de mitjà de pagament

Paràmetre: payment_means_type_code

Codi	Descripció
1	Efectiu
2	Targeta
3	Bo
4	Mòbil
5	Xec
6	Transferència bancària
7	Altres

Tipus d’operació

Paràmetre: type_operation

Codi	Descripció
services	Serveis
goods	Béns