Comply with KSeF (Polish e-Invoicing System) using B2Brouter API

[BETA] The KSeF (Krajowy System e-Faktur - National e-Invoice System) is Poland's mandatory electronic invoicing system operated by the Polish Ministry of Finance. KSeF ensures the integrity and authenticity of invoices through structured XML format submission and digital certification.

These regulations require businesses operating in Poland to adopt systems capable of securely generating, validating, and transmitting invoices to the KSeF platform. B2Brouter's REST API provides a technical solution that allows your business to be compliant with KSeF, offloading the complexities to B2Brouter and allowing you to focus on your business logic.

What is KSeF?

KSeF is Poland's centralized e-invoicing platform that became mandatory for VAT taxpayers. It ensures that all invoices are:

Validated against official XML schemas (FA structure)
Digitally certified using qualified certificates
Securely stored by the Polish tax authority
Verifiable through an official receipt (UPO - Urzędowe Poświadczenie Odbioru)

In practice, KSeF requires:

Creating a structured invoice XML file conforming to FA schema variant 3 - FA(3)
Authenticating with the KSeF platform using a qualified electronic certificate linked to your Polish NIP
Submitting the invoice to KSeF for validation and registration
Receiving and storing the UPO (Official Receipt) as proof of registration
Including the QR code with the KSeF reference number on issued invoices

With B2Brouter you can abstract much of the complexities of this process and comply with KSeF. You will need to provide your qualified electronic certificate (PKCS#12 format), and B2Brouter will handle authentication, submission, and UPO retrieval.

B2Brouter generates tax reports using the FA(3) format (Form variant 3, schema version 1-0E), which is the current standard for KSeF submissions.

Setting up KSeF with B2Brouter API

The first step is to configure KSeF for each account (identified by Polish NIP) for which you want to submit tax reports. You can refer to the Tax Report Settings Guide for a full description of the process.

B2Brouter Environments and KSeF Integration

B2Brouter automatically connects to the appropriate KSeF environment based on which API endpoint you use:

B2Brouter Environment	KSeF Environment	Certificate Requirements
Production API `api.b2brouter.net`	KSeF Production `ksef.mf.gov.pl`	Qualified certificate issued by trusted CA
Staging API `api-staging.b2brouter.net`	KSeF Test `ksef-test.mf.gov.pl`	Self-signed certificates accepted for testing

For development and testing:

Use the Staging API (api-staging.b2brouter.net) which connects to KSeF's test environment
The test environment accepts self-signed certificates, making it ideal for development and integration testing
You can generate test certificates without needing a qualified certificate from a trusted CA

Certificate Requirements

The authentication towards KSeF uses KSeF Digital certificates. To request a KSeF certificate for production use, the client must log in to the Ministry of Finance’s e-Urząd Skarbowy portal using their qualified signature or trusted profile (Profil Zaufany). From there, they access the KSeF section and generate a dedicated KSeF certificate linked to their NIP. This certificate is then used to authenticate communication with KSeF in production. In the test environment, clients should use self-signed certificates, provided the serial number matches the VAT number (NIP).

Before configuring KSeF, ensure you have:

For Production:

A KSeF certificate in PKCS#12 format (.p12 or .pfx) from a trusted CA
The certificate must be in PKCS#12 format (.p12 or .pfx)
The certificate subject must match your Polish NIP
The password/PIN for the certificate

For Testing/Development (Staging):

Self-signed certificates are accepted in the test environment
The certificate must be in PKCS#12 format (.p12 or .pfx)
The certificate subject should match your test NIP
The password/PIN for the certificate

Example: Encoding your certificate

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

Creating KSeF Tax Report Setting

You need to configure the KSeF integration for each company you want to submit structured invoices for. This configuration defines how B2Brouter handles invoice generation and submission to KSeF on behalf of your system. You must configure these settings per company before submitting any invoice.

This configuration step will onboard the client to KSeF and perform a connection test.
If the certificate or configuration is invalid, the endpoint will return an error.

Example request:

curl --location 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_report_settings' \
--header 'X-B2B-API-Key: {YOUR_API_KEY}' \
--header 'X-B2B-API-Version: 2025-10-13' \
--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
  }
}'

Parameters:

code: Must be "ksef"
type_operation: Default operation type ("services" or "goods")
credit_note_code: Default correction effect code ("1", "2", or "3")
certificate: Your PKCS#12 certificate encoded in base64
certificate_pin: Password for the certificate
auto_generate: Automatically generate tax reports for invoices
auto_send: Automatically send tax reports to KSeF

Working with KSeF Tax Reports

B2Brouter provides two ways to work with KSeF:

Tax Report API: For direct control over tax report creation and submission (RECOMMENDED).
Invoice API: If you use B2Brouter for issuing invoices, tax reports are automatically generated.

Tax Report API

The Tax Report API gives you maximum control over the KSeF submission process. You can create tax reports by providing structured JSON data that B2Brouter will convert to FA(3) XML format.

The structure of the JSON format for B2Brouter tax reports is based on PEPPOL Continuous Transaction Control (CTC). This means that B2Brouter Tax Report API is a universal API not only geared towards KSeF but designed to handle tax reporting around the world.

Important: Tax reports for KSeF use tax_report_lines and tax_breakdowns. Each tax_report_line represents an invoice line item with its own quantity, position, unit_code, price, and tax information.

Create a Tax Report

To create a KSeF tax report, call the create tax report endpoint.

Example: Basic VAT Invoice

curl -X POST 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports' \
--header 'X-B2B-API-Key: {YOUR_API_KEY}' \
--header 'X-B2B-API-Version: 2025-10-13' \
--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
      }
    ]
  }
}'

Example: Corrective Invoice (KOR)

curl -X POST 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports' \
--header 'X-B2B-API-Key: {YOUR_API_KEY}' \
--header 'X-B2B-API-Version: 2025-10-13' \
--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
      }
    ]
  }
}'

Example: Exempt Export of Goods - VAT Invoice (foreign currency)

curl -X POST 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports' \
--header 'X-B2B-API-Key: {YOUR_API_KEY}' \
--header 'X-B2B-API-Version: 2025-10-13' \
--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"
      }
    ]
  }
}'

Example: VAT Invoice (includes information that full payment has been received at the time of issue) - Zaplacono

curl -X POST 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports' \
--header 'X-B2B-API-Key: {YOUR_API_KEY}' \
--header 'X-B2B-API-Version: 2025-10-13' \
--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
      }
    ]
  }
}'

Example: ZAL Invoice (includes information that full payment has been received at the time of issue) - Zaplacono

curl -X POST 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports' \
--header 'X-B2B-API-Key: {YOUR_API_KEY}' \
--header 'X-B2B-API-Version: 2025-10-13' \
--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
      }
    ]
  }
}'

Example: UPR Invoice

For UPR is required the customer_party_tax_id and customer_party_country.

curl -X POST 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports' \
--header 'X-B2B-API-Key: {YOUR_API_KEY}' \
--header 'X-B2B-API-Version: 2025-10-13' \
--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
      }
    ]
  }
}'

Example: Domestic Reverse Charge Invoice

curl -X POST 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports' \
--header 'X-B2B-API-Key: {YOUR_API_KEY}' \
--header 'X-B2B-API-Version: 2025-10-13' \
--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"
      }
    ]
  }
}'

Example: Cross-border Reverse Charge (Services)

curl -X POST 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports' \
--header 'X-B2B-API-Key: {YOUR_API_KEY}' \
--header 'X-B2B-API-Version: 2025-10-13' \
--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
      }
    ]
  }
}'

Response Structure

The response will include the tax report with state "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: Unlike traditional clearance models, B2Brouter can generate the fingerprint, identifier (QR code URL), and qr (QR code image) immediately when creating the tax report, without waiting for KSeF confirmation. This is possible because these fields are calculated from data we already have:

fingerprint: SHA-256 hash of the FA(3) XML document
identifier: URL constructed from: supplier NIP + invoice date + fingerprint (Base64URL format)
qr: QR code image encoding the identifier URL

QR Code Label:

While the tax report is in sending state (before KSeF confirmation), the QR code label should display "OFFLINE"
Once the tax report reaches registered state and you receive the to_net_id (KSeF reference number), you should display the KSeF number under the QR code instead

Best Practice: Although the QR code data is available immediately, it is recommended to wait until the tax report reaches registered state before printing/sending invoices to customers. This ensures the invoice has been successfully accepted by KSeF and avoids potential issues if the submission fails.

Check Tax Report State

The submission to KSeF is asynchronous. You must monitor the tax report state:

Option 1: Using Webhooks (Recommended)

Configure a tax report webhook to receive notifications when the state changes to a final state: registered or error.

Option 2: Polling

Poll the get tax report endpoint until the state is final:

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

Understanding the Registered State Response

When the tax report reaches registered state, the response includes the official KSeF reference number:

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

Field descriptions:

Field	Available	Description
`to_net_id`	After KSeF confirmation	KSeF Reference Number - The unique identifier assigned by KSeF (e.g., `1234567890-20251107-ABCD1234-EF`). Display this number under the QR code on printed/PDF invoices.
`fingerprint`	Immediately on creation	SHA-256 hash of the submitted FA(3) XML document. Used for document integrity verification and QR code generation.
`identifier`	Immediately on creation	QR code URL - The complete URL that the QR code points to. Constructed from: supplier NIP + invoice date + fingerprint. When scanned, allows verification of the invoice on the KSeF platform.
`qr`	Immediately on creation	QR code image - Base64-encoded PNG image of the QR code. Can be embedded in invoices immediately, even before KSeF confirmation.

Important:

The fingerprint, identifier, and qr fields are available immediately in the response, even while the tax report is in sending state
The to_net_id is only available after KSeF successfully registers the invoice
- Recommended: Wait until the tax report reaches registered state before printing/sending invoices to customers to ensure successful KSeF acceptance

Download the UPO (Official Receipt)

Once the tax report reaches registered state, you can download the UPO using the download response endpoint:

curl -X GET '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: 2025-10-13' \
--header 'Accept: application/xml'

Download the FA(3) XML

You can also download the complete FA(3) XML that was sent to KSeF:

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

Alternatively, the xml_base64 field in the tax report response contains the XML encoded in base64.

Error Handling

If the tax report reaches error state, check the tax report details for error information:

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

Equivalence between B2Brouter Tax Report fields and KSeF FA(3) XML nodes

The structure of the JSON format for B2Brouter tax reports is based on PEPPOL Continuous Transaction Control (CTC). The fields used in the JSON payload have different names than in the FA(3) XML representation. This is because B2Brouter Tax Report API is a universal API designed to handle tax reporting worldwide, not just KSeF.

Main Invoice Fields

B2Brouter Field	KSeF FA(3) XML Node
type	Must be "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) or NrVatUE (EU) or NrID (non-EU)
customer_party_country	Podmiot2 > DaneIdentyfikacyjne > KodUE or 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 > KursWaluty
payment_date	Fa > TerminPlatnosci > Termin
amended_ksef_number	Fa > DaneFaKorygowanej > NrKSeFFaKorygowanej
tax_inclusive_amount	Fa > P_15 (total amount)

Tax Report Lines (FaWiersz)

Each line represents an item on the invoice.

B2Brouter Field	KSeF FA(3) XML Node
position	FaWiersz > NrWierszaFa
description	FaWiersz > P_7
quantity	FaWiersz > P_8A
unit_code	FaWiersz > P_8B
price	FaWiersz > P_9A
tax_code	FaWiersz > P_12
tax_exclusive_amount	FaWiersz > P_11
tax_amount	FaWiersz > P_11Vat
ksef_amended	FaWiersz > StanPrzed (marks corrected line)

FA(3) Structure Overview

The FA(3) XML generated by B2Brouter has the following main sections:

<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 --></tns:Fa>

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

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

Code Descriptions for KSeF-Specific Fields

Invoice Type Codes

The type of invoice. This determines the structure and validation rules. Param: invoice_type_code

Code	Description	Used for
VAT	Basic invoice	Regular invoices
KOR	Corrective invoice	Corrections
ZAL	Advance payment invoice (Article 106f sec. 4)	Advance payments
ROZ	Invoice per Article 106f sec. 3	Settlements
UPR	Simplified invoice (Article 106e sec. 5 item 3)	Simplified
KOR_ZAL	Corrective invoice for advance payment	Corrections
KOR_ROZ	Corrective invoice for ROZ	Corrections

Credit Note Effect Codes

Type of effect of correction in VAT records. Used for corrective invoices (KOR, KOR_ZAL, KOR_ROZ). Param: credit_note_code (in Tax Report Setting)

Code	Description
1	Correction with effect on the date of recognition of the original invoice
2	Correction with effect on the date of issue of the corrective invoice
3	Correction with effect on a different date (or different dates for different items)

Tax Codes

VAT rates and categories used in Poland. Used at line level. Param: tax_code (in tax_report_lines)

Code	Description
23	Standard VAT rate 23%
22	Standard VAT rate 22%
8	Reduced VAT rate 8%
7	Reduced VAT rate 7%
5	Reduced VAT rate 5%
4	Reduced VAT rate 4%
3	Reduced VAT rate 3%
0 WDT	Intra-Community Supply 0% (Wewnątrzwspólnotowa Dostawa Towarów)
0 EX	Export 0%
0 KR	Domestic zero-rated 0%
zw	Exempt from VAT (zwolniona)
oo	Reverse charge domestic (odwrotne obciążenie)
np I	Not subject to VAT - cross-border services (nie podlega)
np II	Not subject to VAT - domestic services

Operation Types

Default type of operation for invoices. Param: type_operation (in Tax Report Setting)

Code	Description
services	Services
goods	Goods