> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invopop.com/llms.txt
> Use this file to discover all available pages before exploring further.
# KSeF 2.0 Poland Guide
> Register suppliers and issue electronic invoices through Poland's KSeF 2.0 system
## Introduction
KSeF (Krajowy System e-Faktur) 2.0 is Poland's mandatory national e-invoicing system operated by the [Ministry of Finance](https://www.gov.pl/web/finanse). The system uses the FA(3) XML schema format for structured invoice data and provides real-time clearance for all B2B invoices.
Invoices are encoded in FA(3), a strict XML format that enforces standardized fields for domestic and cross-border transactions. The KSeF system validates all submitted invoices in real-time and assigns a unique KSeF ID upon successful clearance.
This guide covers three key processes:
* [Party registration](#running): Registering suppliers in the KSeF system
* [Invoice issuance](#send-an-invoice): Creating and sending FA(3) invoices through KSeF
* [Invoice import](#import-received-invoices): Importing received invoices from KSeF
Invopop supports two use cases that require different configurations:
* **Send only**: You issue invoices through KSeF on behalf of your suppliers. This is the simplest setup and does not require the Cron app or import/sync workflows.
* **Send & receive**: In addition to sending, you also want to automatically import invoices received by your suppliers from KSeF. This requires the Cron app to periodically check for new invoices.
The table below summarizes which components are needed for each use case:
| Component | Send only | Send & receive |
| ----------------------- | :---------------------------------: | :---------------------------------------------------------: |
| Poland app | ✓ | ✓ |
| Cron app | — | ✓ |
| Send invoice workflow | ✓ | ✓ |
| Import invoice workflow | — | ✓ |
| Sync invoices workflow | — | ✓ |
| Registration workflow | [Send](#setup-for-sending-invoices) | [Send & receive](#setup-for-sending-and-receiving-invoices) |
| - | Sandbox | Live |
| ------------ | ----------------------------------------------------------- | ---------------------------------------------- |
| **Supplier** | Fake NIP allowed (test mode); real NIP needed for demo mode | Valid NIP and KSeF portal credentials required |
| **Mode** | Defaults to test; demo available via config | Automatically targets KSeF production |
## Prerequisites
To issue invoices through KSeF, you will need:
| Environment | Requirements |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Invopop Sandbox
Test mode | **Test Polish Tax ID (NIP)**
You can generate fake NIPs for testing at [http://generatory.it/](http://generatory.it/). In test mode, a self-signed certificate will be generated automatically, and you can start sending invoices immediately.
|
| Invopop Sandbox
Demo mode | **Real Polish Tax ID (NIP) and credentials to access the [KSeF Demo Portal](https://ap-demo.ksef.mf.gov.pl/web/)**
Demo mode follows the same registration process as production but operates in the demo environment. |
| Invopop Live | **Valid company NIP and credentials to access the [KSeF Portal](https://ap.ksef.mf.gov.pl/)**
You will need to generate a certificate through the KSeF portal. Registration will automatically target the KSeF production environment. |
## Setup
All of the following steps must be carried out from the [Invopop Console](https://console.invopop.com). Choose the path that matches your use case:
* [Setup for sending invoices](#setup-for-sending-invoices) — issue invoices through KSeF on behalf of your suppliers.
* [Setup for sending and receiving invoices](#setup-for-sending-and-receiving-invoices) — issue invoices and automatically import invoices received by your suppliers.
### Setup for sending invoices
Follow these steps to configure Invopop to issue invoices through KSeF.
1. Navigate to **Configuration** → **Apps**
2. Find **Poland** in the app discovery list
3. Click **Connect** to activate
The initial connection requires no configuration.
This workflow signs the GOBL document, converts it to FA(3) XML, and submits it to KSeF.
Signs and converts the [GOBL](https://docs.gobl.org) document into the FA(3) XML format and sends it to KSeF.
Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view.
```json Example KSeF issue invoice workflow theme={"system"}
{
"name": "KSeF issue invoice",
"description": "Issue an invoice through KSeF",
"schema": "bill/invoice",
"steps": [
{
"id": "20bbac70-fb6e-11f0-8a4e-79beeb9e3cf2",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `processing`{.state .processing}",
"config": {
"state": "processing"
}
},
{
"id": "9b5f5330-fb70-11f0-bcdd-bdb71eaf1fb4",
"name": "Add sequential code",
"provider": "sequence.enumerate",
"summary": "Dynamic · KSeF · 000001",
"config": {
"name": "KSeF",
"padding": 6,
"start": 1
}
},
{
"id": "2f41c860-fb6e-11f0-8a4e-79beeb9e3cf2",
"name": "Sign envelope",
"provider": "silo.close"
},
{
"id": "2b064190-fb6e-11f0-8a4e-79beeb9e3cf2",
"name": "Generate FA_VAT v3 XML",
"provider": "gov-pl.generate"
},
{
"id": "36ec8550-fb6e-11f0-8a4e-79beeb9e3cf2",
"name": "Send invoice to KSeF",
"provider": "gov-pl.send"
},
{
"id": "3a3e2150-fb6e-11f0-8a4e-79beeb9e3cf2",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `sent`{.state .sent}",
"config": {
"state": "sent"
}
}
],
"rescue": [
{
"id": "3eca1210-fb6e-11f0-8a4e-79beeb9e3cf2",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `error`{.state .error}",
"config": {
"state": "error"
}
}
]
}
```
Before starting, review the [workflows guide](/guides/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) as the base. Then add the following steps:
1. **Set state** - To `Processing`
2. **Add sequential code** - Add the desired sequence for your invoices
3. **Sign envelope** - Signs the [GOBL](https://docs.gobl.org) document preventing further modifications
4. **Generate FA(3) XML** - Generates the FA(3) XML
5. **Send invoice to KSeF** - Sends the FA(3) XML to KSeF
6. **Set state** - To `Sent`
In the **Error handling** section, add a **Set state** step with the state set to `Error` to capture and flag failed submissions.
This workflow registers a supplier in KSeF so you can issue invoices on their behalf.
In **Sandbox** the **Register supplier with KSeF** step allows you to configure the environment:
* **Test**: Self-signed certificate generated automatically, no manual steps required.
* **Demo**: Requires manual certificate generation from the demo portal.
Test is more convenient while Demo is more accurate simulating the production environment. It is convenient to create two workflows configured differently to easily switch between the Demo and Test options.
In **live workspaces** no configuration is available, all suppliers are registered in the KSeF production environment.
Registers a party (supplier) with the KSeF system for sending invoices.
Copy and paste into a new [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) code view.
The template uses test mode by default (for sandbox). To use demo mode in sandbox, add `"config": {"environment": "demo"}` to the **Register supplier with KSeF** step. In Invopop production, the workflow automatically targets the KSeF production environment.
```json Example KSeF register supplier (send) workflow theme={"system"}
{
"name": "KSeF register supplier (send)",
"description": "Register a supplier with KSeF for sending e-invoices",
"schema": "org/party",
"steps": [
{
"id": "f6ca2240-fb6b-11f0-b2f4-37a8eb8f9eb9",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `processing`{.state .processing}",
"config": {
"state": "processing"
}
},
{
"id": "f7315970-fb74-11f0-8137-27e02839a7ca",
"name": "Register supplier with KSeF",
"provider": "gov-pl.register"
},
{
"id": "3166cb10-fdba-11f0-a562-870ebfef62f3",
"name": "Wait for KSeF certificate upload",
"provider": "gov-pl.wait.upload"
},
{
"id": "f0b45d30-fb6b-11f0-b2f4-37a8eb8f9eb9",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `registered`{.state .registered}",
"config": {
"state": "registered"
}
}
],
"rescue": [
{
"id": "ebf99440-fb6b-11f0-b2f4-37a8eb8f9eb9",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `error`{.state .error}",
"config": {
"state": "error"
}
}
]
}
```
Before starting, review the [workflows guide](/guides/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) as the base. Then name the workflow with a descriptive label such as "KSeF Register Party (Send)".
The new workflow will need to perform these steps:
1. **Set state** - To `Processing`
2. **Register supplier with KSeF** - Registers the party with KSeF and generates a registration link. Configure with your chosen environment (test, demo, or production).
3. **Wait for KSeF certificate upload** - Waits for the supplier to generate and upload their KSeF certificate (automatically skipped in test mode)
4. **Set state** - To `Registered`
Finally, in the **Error handling** area, add the **Set state** action and select `Error`.
### Setup for sending and receiving invoices
Follow these steps to configure Invopop to both issue invoices through KSeF **and** automatically import invoices received by your suppliers. The Cron app periodically triggers a sync workflow that checks KSeF for new invoices and creates import jobs for each one found.
1. Navigate to **Configuration** → **Apps**
2. Find **Poland** in the app discovery list
3. Click **Connect** to activate
The initial connection requires no configuration.
1. Navigate to **Configuration** → **Apps**
2. Find **Cron** in the app discovery list
3. Click **Connect** to activate
No additional configuration is needed. The [Cron app](/apps/cron) handles scheduling periodic workflow execution for importing received invoices.
This workflow signs the GOBL document, converts it to FA(3) XML, and submits it to KSeF.
Signs and converts the [GOBL](https://docs.gobl.org) document into the FA(3) XML format and sends it to KSeF.
Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view.
```json Example KSeF issue invoice workflow theme={"system"}
{
"name": "KSeF issue invoice",
"description": "Issue an invoice through KSeF",
"schema": "bill/invoice",
"steps": [
{
"id": "20bbac70-fb6e-11f0-8a4e-79beeb9e3cf2",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `processing`{.state .processing}",
"config": {
"state": "processing"
}
},
{
"id": "9b5f5330-fb70-11f0-bcdd-bdb71eaf1fb4",
"name": "Add sequential code",
"provider": "sequence.enumerate",
"summary": "Dynamic · KSeF · 000001",
"config": {
"name": "KSeF",
"padding": 6,
"start": 1
}
},
{
"id": "2f41c860-fb6e-11f0-8a4e-79beeb9e3cf2",
"name": "Sign envelope",
"provider": "silo.close"
},
{
"id": "2b064190-fb6e-11f0-8a4e-79beeb9e3cf2",
"name": "Generate FA_VAT v3 XML",
"provider": "gov-pl.generate"
},
{
"id": "36ec8550-fb6e-11f0-8a4e-79beeb9e3cf2",
"name": "Send invoice to KSeF",
"provider": "gov-pl.send"
},
{
"id": "3a3e2150-fb6e-11f0-8a4e-79beeb9e3cf2",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `sent`{.state .sent}",
"config": {
"state": "sent"
}
}
],
"rescue": [
{
"id": "3eca1210-fb6e-11f0-8a4e-79beeb9e3cf2",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `error`{.state .error}",
"config": {
"state": "error"
}
}
]
}
```
Before starting, review the [workflows guide](/guides/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) as the base. Then add the following steps:
1. **Set state** - To `Processing`
2. **Add sequential code** - Add the desired sequence for your invoices
3. **Sign envelope** - Signs the [GOBL](https://docs.gobl.org) document preventing further modifications
4. **Generate FA(3) XML** - Generates the FA(3) XML
5. **Send invoice to KSeF** - Sends the FA(3) XML to KSeF
6. **Set state** - To `Sent`
In the **Error handling** section, add a **Set state** step with the state set to `Error` to capture and flag failed submissions.
This workflow imports an individual invoice from KSeF when it is received. It is automatically triggered by the sync workflow (configured in the next step) for each invoice found.
Imports a received invoice from KSeF and converts it to GOBL format.
Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view.
This workflow receives KSeF number and NIP as input arguments, not a silo entry. It's designed to be triggered automatically by the sync workflow.
```json Example KSeF import invoice workflow theme={"system"}
{
"name": "KSeF import invoice",
"description": "Import an invoice received through KSeF",
"schema": "bill/invoice",
"steps": [
{
"id": "ba8faad0-01d7-11f1-8b4e-fdb288ce1d84",
"name": "Import invoice from KSeF",
"provider": "gov-pl.import"
},
{
"id": "5efe18e0-01e7-11f1-8a2b-3f4babb9af4d",
"name": "Set folder",
"provider": "silo.folder",
"summary": "Set folder to `Invoices · Expenses`{.font-medium}",
"config": {
"folder": "expenses"
}
},
{
"id": "653ff700-01e7-11f1-8a2b-3f4babb9af4d",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `registered`{.state .registered}",
"config": {
"state": "registered"
}
}
],
"rescue": [
{
"id": "7d993da0-0275-11f1-94f6-05637523f70d",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `error`{.state .error}",
"config": {
"state": "error"
}
}
]
}
```
Before starting, review the [workflows guide](/guides/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) as the base. Then name the workflow with a descriptive label such as "KSeF Import Invoice".
The new workflow will need to perform these steps:
1. **Import invoice from KSeF** - Downloads the invoice from KSeF and converts it to GOBL format
2. **Set folder** - To `Invoices · Expenses` (or your preferred folder)
3. **Set state** - To `Registered`
Finally, in the **Error handling** area, add the **Set state** action and select `Error`.
We recommend adding notification steps (email, Slack, etc.) in the error handling section to alert you when invoice imports fail.
This workflow syncs all received invoices for a party within a specific time range. It creates an import job for each invoice found, using the import workflow you configured in the previous step.
Configure the **Sync received invoices from KSeF** step to reference the import workflow created in the previous step.
Creates import jobs for each received invoice of a party in KSeF.
Copy and paste into a new [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) code view.
```json Example KSeF sync received invoices workflow theme={"system"}
{
"name": "KSeF sync received invoices",
"description": "Sync received invoices from KSeF and dispatch import jobs",
"schema": "org/party",
"steps": [
{
"id": "5bddfd40-0220-11f1-bd80-c7df39ccdf0b",
"name": "Sync received invoices from KSeF",
"provider": "gov-pl.sync"
}
],
"rescue": []
}
```
Before starting, review the [workflows guide](/guides/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) as the base. Then name the workflow with a descriptive label such as "KSeF Sync Received Invoices".
The new workflow will need to perform this step:
1. **Sync received invoices from KSeF** - Queries KSeF for all received invoices in the time range and creates import jobs
When configuring the sync step, select the import workflow you created earlier. Each invoice found will trigger a new job using that workflow.
This workflow registers a supplier in KSeF and subscribes them to periodic invoice imports via the [Cron app](/apps/cron). The Cron subscription step periodically triggers the sync workflow to check for new invoices.
In **Sandbox** the **Register supplier with KSeF** step allows you to configure the environment:
* **Test**: Self-signed certificate generated automatically, no manual steps required.
* **Demo**: Requires manual certificate generation from the demo portal.
Test is more convenient while Demo is more accurate simulating the production environment. It is convenient to create two workflows configured differently to easily switch between the Demo and Test options.
In **live workspaces** no configuration is available, all suppliers are registered in the KSeF production environment.
Registers a party (supplier) with the KSeF system and subscribes them to periodic invoice imports.
Copy and paste into a new [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) code view.
The template uses test mode by default (for sandbox). To use demo mode in sandbox, add `"config": {"environment": "demo"}` to the **Register supplier with KSeF** step. In Invopop production, the workflow automatically targets the KSeF production environment.
```json Example KSeF register supplier (receive) workflow theme={"system"}
{
"name": "KSeF register supplier (receive)",
"description": "Register a supplier with KSeF for receiving e-invoices",
"schema": "org/party",
"steps": [
{
"id": "f6ca2240-fb6b-11f0-b2f4-37a8eb8f9eb9",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `processing`{.state .processing}",
"config": {
"state": "processing"
}
},
{
"id": "f7315970-fb74-11f0-8137-27e02839a7ca",
"name": "Register supplier with KSeF",
"provider": "gov-pl.register"
},
{
"id": "3166cb10-fdba-11f0-a562-870ebfef62f3",
"name": "Wait for KSeF certificate upload",
"provider": "gov-pl.wait.upload"
},
{
"id": "a1b2c3d0-fb75-11f0-b567-89abcdef0123",
"name": "Subscribe to periodic execution",
"provider": "cron.subscribe",
"summary": "Periodic KSeF sync"
},
{
"id": "f0b45d30-fb6b-11f0-b2f4-37a8eb8f9eb9",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `registered`{.state .registered}",
"config": {
"state": "registered"
}
}
],
"rescue": [
{
"id": "ebf99440-fb6b-11f0-b2f4-37a8eb8f9eb9",
"name": "Set state",
"provider": "silo.state",
"summary": "Set state to `error`{.state .error}",
"config": {
"state": "error"
}
}
]
}
```
Before starting, review the [workflows guide](/guides/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) as the base. Then name the workflow with a descriptive label such as "KSeF Register Party (Receive)".
The new workflow will need to perform these steps:
1. **Set state** - To `Processing`
2. **Register supplier with KSeF** - Registers the party with KSeF and generates a registration link. Configure with your chosen environment (test, demo, or production).
3. **Wait for KSeF certificate upload** - Waits for the supplier to generate and upload their KSeF certificate (automatically skipped in test mode)
4. **Subscribe to periodic KSeF sync** - Uses the [Cron app](/apps/cron) to schedule periodic execution of the sync workflow. Configure with the sync workflow and your preferred interval.
5. **Set state** - To `Registered`
Finally, in the **Error handling** area, add the **Set state** action and select `Error`.
#### Configure the cron step to start syncing invoices to Invopop
After adding the workflow (regardless of how you created it), open the **Subscribe to periodic KSeF sync** step and configure the two fields below. This is what tells the [Cron app](/apps/cron) which workflow to run and how often.
1. **Workflow** — select the **KSeF Sync Received Invoices** workflow you created in the previous step. The Cron app will trigger this workflow on each tick.
2. **Interval** — choose how often KSeF should be checked for new invoices (for example, every hour or every day). Pick a frequency that matches how quickly you need received invoices to appear in Invopop.
Once configured, the step should look like this:
## Running
In this section, we'll provide details on how to register parties (suppliers) and issue invoices on their behalf.
### Register a party for test environment
Choose test mode when you want to quickly test the KSeF integration without dealing with real certificates or authentication. Certificates are generated automatically, allowing you to start sending invoices immediately without any manual certificate generation.
In the [Invopop Console](https://console.invopop.com), navigate to **Parties** → **Suppliers** and click + New Supplier.
Use fake Polish Tax IDs (NIP) generated from [http://generatory.it/](http://generatory.it/):
```json theme={"system"}
{
"$schema": "https://gobl.org/draft-0/org/party",
"name": "Test Supplier Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9876543210"
}
}
```
Click Build, ensure there are no errors, and click Save.
In the party entry, click on Select Workflow, choose your **KSeF Register Party (Test)** workflow, and click Run Workflow.
**That's it!** ✓ Registration completes automatically. The party is now in Registered state and ready to issue invoices.
***
### Register a party for demo/production environment
In sandbox workspaces, choose Demo mode when you want to simulate the real production flow with KSeF authentication in a safe demo environment.
Use real Polish Tax IDs (NIP) with access to the [KSeF Demo Portal](https://ap-demo.ksef.mf.gov.pl/web/) or [KSeF Portal](https://ap.ksef.mf.gov.pl/):
```json theme={"system"}
{
"$schema": "https://gobl.org/draft-0/party",
"name": "Real Company Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "1234567890"
}
}
```
Click Build, ensure there are no errors, and click Save.
On the party details page, click **Select Workflow**:
* **For Demo**: Choose your **KSeF Register Party (Demo)** workflow
* **For Production**: Choose your **KSeF Register Party (Production)** workflow
Click Run Workflow. The party will be in Processing state until certificate upload is complete.
Get the registration link to begin certificate generation:
Your own company
In Console, go to the supplier entry → **Meta** tab → click the **gov-pl.invopop.com** link to launch the registration wizard.
Third-party companies (white label)
In Console, go to the supplier entry → **Meta** tab → click the **gov-pl.invopop.com** link to launch the registration wizard.
Add a webhook after the **Register supplier with KSeF** step to receive the `siloEntryId`.
Use the [Fetch an Entry endpoint](/api-ref/silo/entries/fetch-an-entry) to get the registration link from the `meta` object:
```json theme={"system"}
{
"data": {
"meta": [
{
"src": "gov-pl",
"key": "link",
"link_url": "https://ksef.invopop.com/reg/AbC123XyZ"
}
]
}
}
```
Send the `link_url` to your customer.
The registration wizard will guide you through these steps:
1. Visit the KSeF portal
* Demo: [KSeF Demo Portal](https://ap-demo.ksef.mf.gov.pl/web/)
* Production: [KSeF Portal](https://ap.ksef.mf.gov.pl/)
2. Log in with Trusted Profile (Profil Zaufany)
* [Video tutorial: Setting up Trusted Profile](https://www.youtube.com/watch?v=V6E1fGUFPw4)
3. Generate the certificate
* Navigate to certificate generation section
* Enter certificate name and password (save the password!)
* Download the private key (automatically generated)
* Select "Authentication in the KSeF system"
* Set start date to today or earlier (future dates will fail)
* Download the certificate file
* [Video tutorial: Certificate generation](https://www.youtube.com/watch?v=SE0IHuPHtRE)
Save the certificate and private key files, as well as the password. You'll need them in the next step.
There are two ways to upload the certificate:
Web Upload (Wizard)
Return to the registration wizard and upload:
* Certificate file
* Private key file
* Password
Click Upload and verify certificate. The system validates and securely stores your credentials.
API Upload
Upload the certificate programmatically using the [Upload KSeF certificate endpoint](/api-ref/apps/gov-pl/certificate-upload).
This approach is ideal for automated integrations where you want to handle certificate generation and upload programmatically without user interaction with the web wizard.
✓ **Success**: The supplier transitions to Registered state and can begin issuing invoices.
× **Failure**: See [Why did my supplier registration fail?](/faq/poland#why-did-my-supplier-registration-fail) in Poland's FAQ.
### Send an invoice
Once a party is registered, you can issue invoices on their behalf. The following examples show partial [GOBL](https://docs.gobl.org) documents you can copy and paste directly into the [Invopop Console](https://console.invopop.com) or store via the API as silo entries.
GOBL Invoices sent to KSeF require the regime set to PL and addons must include pl-favat-v3 for FA(3) schema compliance.
In this example, we're issuing a standard B2B invoice from a Polish supplier to another Polish business customer.
Notice:
* the minimal version (`ksef-b2b-standard.min.mdx`) contains only the essential fields required to create the invoice,
* the [`pl-ksef-v1`](https://docs.gobl.org/addons/pl-ksef-v1) addon ensures the document will be validated using the KSeF rules built into the [GOBL](https://docs.gobl.org) library,
* there are no totals or calculations in the minimal version; all these will be calculated automatically when running `gobl build`,
* the built version (`ksef-b2b-standard.mdx`) shows the normalized document with calculated totals, line item sums, tax breakdowns, and automatically generated fields like `i` (line index), `sum`, and `total`, and,
* make sure to process it with the "Issue KSeF invoice" workflow created during setup.
```json B2B Standard Invoice theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PL",
"$addons": [
"pl-favat-v3"
],
"series": "INVOICE",
"code": "001",
"issue_date": "2026-01-20",
"supplier": {
"name": "Testowa Firma Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9876543210"
},
"addresses": [
{
"street": "ul. Główna 1",
"locality": "Warsaw",
"code": "00-001",
"country": "PL"
}
],
"emails": [
{
"addr": "kontakt@testowa.pl"
}
]
},
"customer": {
"name": "Klient Testowy Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "1111111111"
},
"addresses": [
{
"street": "ul. Testowa 10",
"locality": "Kraków",
"code": "30-001",
"country": "PL"
}
]
},
"lines": [
{
"quantity": "10",
"item": {
"name": "Software Development Services",
"price": "100.00",
"unit": "h"
},
"taxes": [
{
"cat": "VAT",
"rate": "general",
"key": "standard"
}
]
},
{
"quantity": "5",
"item": {
"name": "Consulting Services",
"price": "150.00",
"unit": "h"
},
"taxes": [
{
"cat": "VAT",
"rate": "reduced",
"key": "standard"
}
]
}
],
"payment": {
"instructions": {
"key": "credit-transfer",
"detail": "Transfer payment to our bank account",
"credit_transfer": [
{
"iban": "PL61109010140000071219812874",
"name": "Testowa Firma Sp. z o.o."
}
]
}
}
}
```
```json Built version theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PL",
"$addons": [
"pl-favat-v3"
],
"type": "standard",
"series": "INVOICE",
"code": "001",
"issue_date": "2026-01-20",
"currency": "PLN",
"tax": {
"ext": {
"pl-favat-invoice-type": "VAT"
}
},
"supplier": {
"name": "Testowa Firma Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9876543210"
},
"addresses": [
{
"street": "ul. Główna 1",
"locality": "Warsaw",
"code": "00-001",
"country": "PL"
}
],
"emails": [
{
"addr": "kontakt@testowa.pl"
}
]
},
"customer": {
"name": "Klient Testowy Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "1111111111"
},
"addresses": [
{
"street": "ul. Testowa 10",
"locality": "Kraków",
"code": "30-001",
"country": "PL"
}
]
},
"lines": [
{
"i": 1,
"quantity": "10",
"item": {
"name": "Software Development Services",
"price": "100.00",
"unit": "h"
},
"sum": "1000.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "general",
"percent": "23.0%",
"ext": {
"pl-favat-tax-category": "1"
}
}
],
"total": "1000.00"
},
{
"i": 2,
"quantity": "5",
"item": {
"name": "Consulting Services",
"price": "150.00",
"unit": "h"
},
"sum": "750.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "reduced",
"percent": "8.0%",
"ext": {
"pl-favat-tax-category": "2"
}
}
],
"total": "750.00"
}
],
"payment": {
"instructions": {
"key": "credit-transfer",
"detail": "Transfer payment to our bank account",
"credit_transfer": [
{
"iban": "PL61109010140000071219812874",
"name": "Testowa Firma Sp. z o.o."
}
],
"ext": {
"pl-favat-payment-means": "6"
}
}
},
"totals": {
"sum": "1750.00",
"total": "1750.00",
"taxes": {
"categories": [
{
"code": "VAT",
"rates": [
{
"key": "standard",
"ext": {
"pl-favat-tax-category": "1"
},
"base": "1000.00",
"percent": "23.0%",
"amount": "230.00"
},
{
"key": "standard",
"ext": {
"pl-favat-tax-category": "2"
},
"base": "750.00",
"percent": "8.0%",
"amount": "60.00"
}
],
"amount": "290.00"
}
],
"sum": "290.00"
},
"tax": "290.00",
"total_with_tax": "2040.00",
"payable": "2040.00"
}
}
```
In this example, we're issuing a reverse charge invoice from a Polish supplier to a customer in another EU member state.
Notice:
* the customer has a valid EU VAT ID, indicating the transaction is subject to reverse charge mechanism,
* the minimal version contains only essential fields; totals and tax calculations are omitted,
* when running `gobl build`, the system automatically calculates totals, applies reverse charge rules, and normalizes the document,
* the built version shows all calculated fields including the reverse charge indicator, tax breakdowns, and final totals, and,
* the invoice is validated using the KSeF rules to ensure compliance with Polish e-invoicing requirements.
```json B2B Reverse Charge Invoice theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PL",
"$addons": [
"pl-favat-v3"
],
"$tags": [
"reverse-charge"
],
"series": "RC",
"code": "001",
"issue_date": "2026-01-20",
"supplier": {
"name": "Testowa Firma Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9876543210"
},
"addresses": [
{
"street": "ul. Główna 1",
"locality": "Warsaw",
"code": "00-001",
"country": "PL"
}
]
},
"customer": {
"name": "EU Business GmbH",
"tax_id": {
"country": "DE",
"code": "111111125"
},
"addresses": [
{
"street": "Hauptstraße 100",
"locality": "Berlin",
"code": "10115",
"country": "DE"
}
]
},
"lines": [
{
"quantity": "1",
"item": {
"name": "IT Services - EU Reverse Charge",
"price": "5000.00"
},
"taxes": [
{
"cat": "VAT",
"key": "reverse-charge"
}
]
}
],
"notes": [
{
"key": "legal",
"text": "Reverse charge mechanism applies - VAT to be accounted for by the customer."
}
]
}
```
```json Built version theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PL",
"$addons": [
"pl-favat-v3"
],
"$tags": [
"reverse-charge"
],
"type": "standard",
"series": "RC",
"code": "001",
"issue_date": "2026-01-20",
"currency": "PLN",
"tax": {
"ext": {
"pl-favat-invoice-type": "VAT",
"pl-favat-reverse-charge": "1"
}
},
"supplier": {
"name": "Testowa Firma Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9876543210"
},
"addresses": [
{
"street": "ul. Główna 1",
"locality": "Warsaw",
"code": "00-001",
"country": "PL"
}
]
},
"customer": {
"name": "EU Business GmbH",
"tax_id": {
"country": "DE",
"code": "111111125"
},
"addresses": [
{
"street": "Hauptstraße 100",
"locality": "Berlin",
"code": "10115",
"country": "DE"
}
]
},
"lines": [
{
"i": 1,
"quantity": "1",
"item": {
"name": "IT Services - EU Reverse Charge",
"price": "5000.00"
},
"sum": "5000.00",
"taxes": [
{
"cat": "VAT",
"key": "reverse-charge",
"ext": {
"pl-favat-tax-category": "9"
}
}
],
"total": "5000.00"
}
],
"totals": {
"sum": "5000.00",
"total": "5000.00",
"taxes": {
"categories": [
{
"code": "VAT",
"rates": [
{
"key": "reverse-charge",
"ext": {
"pl-favat-tax-category": "9"
},
"base": "5000.00",
"amount": "0.00"
}
],
"amount": "0.00"
}
],
"sum": "0.00"
},
"tax": "0.00",
"total_with_tax": "5000.00",
"payable": "5000.00"
},
"notes": [
{
"key": "legal",
"text": "Reverse charge mechanism applies - VAT to be accounted for by the customer."
}
]
}
```
In this example, we're issuing a credit note to correct or refund a previous invoice.
Notice:
* the `type` field is set to `credit-note` to indicate this is a corrective document,
* the `preceding` field references the original invoice being corrected,
* the minimal version contains only the essential fields; calculations are handled by GOBL,
* when running `gobl build`, the system automatically calculates negative totals, tax refunds, and validates the credit note structure,
* the built version shows all calculated fields including negative amounts for the refund, and,
* the document is validated using the KSeF rules to ensure compliance with Polish credit note requirements.
```json B2B Credit Note theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PL",
"$addons": [
"pl-favat-v3"
],
"type": "credit-note",
"series": "KOR",
"code": "001",
"issue_date": "2026-01-20",
"preceding": [
{
"type": "standard",
"issue_date": "2026-01-20",
"series": "INVOICE",
"code": "001",
"reason": "Price correction",
"stamps": [
{
"prv": "favat-ksef-number",
"val": "1234567890-20260120-ABCD1234-EF"
}
],
"ext": {
"pl-favat-effective-date": "1"
}
}
],
"supplier": {
"name": "Testowa Firma Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9876543210"
},
"addresses": [
{
"street": "ul. Główna 1",
"locality": "Warsaw",
"code": "00-001",
"country": "PL"
}
]
},
"customer": {
"name": "Klient Testowy Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9876543210"
},
"addresses": [
{
"street": "ul. Testowa 10",
"locality": "Kraków",
"code": "30-001",
"country": "PL"
}
]
},
"lines": [
{
"quantity": "10",
"item": {
"name": "Software Development Services",
"price": "10.00",
"unit": "h"
},
"taxes": [
{
"cat": "VAT",
"rate": "general",
"ext": {
"pl-favat-tax-category": "1"
}
}
]
}
]
}
```
```json Built version theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PL",
"$addons": [
"pl-favat-v3"
],
"type": "credit-note",
"series": "KOR",
"code": "001",
"issue_date": "2026-01-20",
"currency": "PLN",
"preceding": [
{
"type": "standard",
"issue_date": "2026-01-20",
"series": "INVOICE",
"code": "001",
"reason": "Price correction",
"stamps": [
{
"prv": "favat-ksef-number",
"val": "1234567890-20260120-ABCD1234-EF"
}
],
"ext": {
"pl-favat-effective-date": "1"
}
}
],
"tax": {
"ext": {
"pl-favat-invoice-type": "KOR"
}
},
"supplier": {
"name": "Testowa Firma Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9876543210"
},
"addresses": [
{
"street": "ul. Główna 1",
"locality": "Warsaw",
"code": "00-001",
"country": "PL"
}
]
},
"customer": {
"name": "Klient Testowy Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9876543210"
},
"addresses": [
{
"street": "ul. Testowa 10",
"locality": "Kraków",
"code": "30-001",
"country": "PL"
}
]
},
"lines": [
{
"i": 1,
"quantity": "10",
"item": {
"name": "Software Development Services",
"price": "10.00",
"unit": "h"
},
"sum": "100.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "general",
"percent": "23.0%",
"ext": {
"pl-favat-tax-category": "1"
}
}
],
"total": "100.00"
}
],
"totals": {
"sum": "100.00",
"total": "100.00",
"taxes": {
"categories": [
{
"code": "VAT",
"rates": [
{
"key": "standard",
"ext": {
"pl-favat-tax-category": "1"
},
"base": "100.00",
"percent": "23.0%",
"amount": "23.00"
}
],
"amount": "23.00"
}
],
"sum": "23.00"
},
"tax": "23.00",
"total_with_tax": "123.00",
"payable": "123.00"
}
}
```
In this example, we're issuing a prepayment invoice to document an advance payment received before completing the delivery of goods or services.
Notice:
* the `$tags` field includes `partial`, which tells the FA\_VAT addon to classify this as a `ZAL` (Faktura Zaliczkowa) document type,
* the `payment.advances` array records the advance payment details, including the mandatory `date` field and a `percent` of the total,
* GOBL automatically calculates the advance amount from the percentage and deducts it from the payable total to produce the `due` amount,
* the built version shows `"pl-favat-invoice-type": "ZAL"` automatically set in the tax extensions, and,
* after sending this invoice through KSeF, reference the assigned KSeF number in the subsequent settlement invoice.
```json B2B Prepayment Invoice theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PL",
"$addons": [
"pl-favat-v3"
],
"$tags": ["partial"],
"series": "ZAL",
"code": "001",
"issue_date": "2026-01-20",
"supplier": {
"name": "Testowa Firma Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9876543210"
},
"addresses": [
{
"street": "ul. Główna 1",
"locality": "Warsaw",
"code": "00-001",
"country": "PL"
}
]
},
"customer": {
"name": "Klient Testowy Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "1111111111"
},
"addresses": [
{
"street": "ul. Testowa 10",
"locality": "Kraków",
"code": "30-001",
"country": "PL"
}
]
},
"lines": [
{
"quantity": "10",
"item": {
"name": "Software Development Services",
"price": "100.00",
"unit": "h"
},
"taxes": [
{
"cat": "VAT",
"rate": "general",
"key": "standard"
}
]
}
],
"payment": {
"advances": [
{
"key": "credit-transfer",
"description": "Advance payment for software development project",
"date": "2026-01-20",
"percent": "50%"
}
],
"instructions": {
"key": "credit-transfer",
"credit_transfer": [
{
"iban": "PL61109010140000071219812874",
"name": "Testowa Firma Sp. z o.o."
}
]
}
}
}
```
```json Built version theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PL",
"$addons": [
"pl-favat-v3"
],
"$tags": [
"partial"
],
"type": "standard",
"series": "ZAL",
"code": "001",
"issue_date": "2026-01-20",
"currency": "PLN",
"tax": {
"ext": {
"pl-favat-invoice-type": "ZAL"
}
},
"supplier": {
"name": "Testowa Firma Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9876543210"
},
"addresses": [
{
"street": "ul. Główna 1",
"locality": "Warsaw",
"code": "00-001",
"country": "PL"
}
]
},
"customer": {
"name": "Klient Testowy Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "1111111111"
},
"addresses": [
{
"street": "ul. Testowa 10",
"locality": "Kraków",
"code": "30-001",
"country": "PL"
}
]
},
"lines": [
{
"i": 1,
"quantity": "10",
"item": {
"name": "Software Development Services",
"price": "100.00",
"unit": "h"
},
"sum": "1000.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "general",
"percent": "23.0%",
"ext": {
"pl-favat-tax-category": "1"
}
}
],
"total": "1000.00"
}
],
"payment": {
"advances": [
{
"date": "2026-01-20",
"key": "credit-transfer",
"description": "Advance payment for software development project",
"percent": "50%",
"amount": "615.00",
"ext": {
"pl-favat-payment-means": "6"
}
}
],
"instructions": {
"key": "credit-transfer",
"credit_transfer": [
{
"iban": "PL61109010140000071219812874",
"name": "Testowa Firma Sp. z o.o."
}
],
"ext": {
"pl-favat-payment-means": "6"
}
}
},
"totals": {
"sum": "1000.00",
"total": "1000.00",
"taxes": {
"categories": [
{
"code": "VAT",
"rates": [
{
"key": "standard",
"ext": {
"pl-favat-tax-category": "1"
},
"base": "1000.00",
"percent": "23.0%",
"amount": "230.00"
}
],
"amount": "230.00"
}
],
"sum": "230.00"
},
"tax": "230.00",
"total_with_tax": "1230.00",
"payable": "1230.00",
"advance": "615.00",
"due": "615.00"
}
}
```
In this example, we're issuing a settlement invoice to finalize a transaction after one or more advance payments have been made.
Notice:
* the `$tags` field includes `settlement`, which tells the FA\_VAT addon to classify this as a `ROZ` (Faktura Rozliczeniowa) document type,
* the `preceding` field references the original prepayment invoice, including its KSeF number stamp,
* the `payment.advances` array records the previously paid advance amount, which GOBL deducts from the total to calculate the remaining `due`,
* the line items represent the full value of the delivered goods or services, and,
* the built version shows `"pl-favat-invoice-type": "ROZ"` automatically set in the tax extensions.
```json B2B Settlement Invoice theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PL",
"$addons": [
"pl-favat-v3"
],
"$tags": ["settlement"],
"series": "ROZ",
"code": "001",
"issue_date": "2026-02-15",
"preceding": [
{
"type": "standard",
"issue_date": "2026-01-20",
"series": "ZAL",
"code": "001",
"stamps": [
{
"prv": "favat-ksef-number",
"val": "9876543210-20260120-ABCD1234-EF"
}
]
}
],
"supplier": {
"name": "Testowa Firma Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9876543210"
},
"addresses": [
{
"street": "ul. Główna 1",
"locality": "Warsaw",
"code": "00-001",
"country": "PL"
}
]
},
"customer": {
"name": "Klient Testowy Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "1111111111"
},
"addresses": [
{
"street": "ul. Testowa 10",
"locality": "Kraków",
"code": "30-001",
"country": "PL"
}
]
},
"lines": [
{
"quantity": "10",
"item": {
"name": "Software Development Services",
"price": "100.00",
"unit": "h"
},
"taxes": [
{
"cat": "VAT",
"rate": "general",
"key": "standard"
}
]
}
],
"payment": {
"advances": [
{
"description": "Advance payment per ZAL/001",
"date": "2026-01-20",
"amount": "615.00"
}
],
"instructions": {
"key": "credit-transfer",
"credit_transfer": [
{
"iban": "PL61109010140000071219812874",
"name": "Testowa Firma Sp. z o.o."
}
]
}
}
}
```
```json Built version theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PL",
"$addons": [
"pl-favat-v3"
],
"$tags": [
"settlement"
],
"type": "standard",
"series": "ROZ",
"code": "001",
"issue_date": "2026-02-15",
"currency": "PLN",
"preceding": [
{
"type": "standard",
"issue_date": "2026-01-20",
"series": "ZAL",
"code": "001",
"stamps": [
{
"prv": "favat-ksef-number",
"val": "9876543210-20260120-ABCD1234-EF"
}
]
}
],
"tax": {
"ext": {
"pl-favat-invoice-type": "ROZ"
}
},
"supplier": {
"name": "Testowa Firma Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9876543210"
},
"addresses": [
{
"street": "ul. Główna 1",
"locality": "Warsaw",
"code": "00-001",
"country": "PL"
}
]
},
"customer": {
"name": "Klient Testowy Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "1111111111"
},
"addresses": [
{
"street": "ul. Testowa 10",
"locality": "Kraków",
"code": "30-001",
"country": "PL"
}
]
},
"lines": [
{
"i": 1,
"quantity": "10",
"item": {
"name": "Software Development Services",
"price": "100.00",
"unit": "h"
},
"sum": "1000.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "general",
"percent": "23.0%",
"ext": {
"pl-favat-tax-category": "1"
}
}
],
"total": "1000.00"
}
],
"payment": {
"advances": [
{
"date": "2026-01-20",
"description": "Advance payment per ZAL/001",
"amount": "615.00"
}
],
"instructions": {
"key": "credit-transfer",
"credit_transfer": [
{
"iban": "PL61109010140000071219812874",
"name": "Testowa Firma Sp. z o.o."
}
],
"ext": {
"pl-favat-payment-means": "6"
}
}
},
"totals": {
"sum": "1000.00",
"total": "1000.00",
"taxes": {
"categories": [
{
"code": "VAT",
"rates": [
{
"key": "standard",
"ext": {
"pl-favat-tax-category": "1"
},
"base": "1000.00",
"percent": "23.0%",
"amount": "230.00"
}
],
"amount": "230.00"
}
],
"sum": "230.00"
},
"tax": "230.00",
"total_with_tax": "1230.00",
"payable": "1230.00",
"advance": "615.00",
"due": "615.00"
}
}
```
B2C invoices are excluded from the mandatory e-invoicing requirement. The tax authority already receives B2C sales data through online fiscal cash registers that transmit receipts to the Central Repository of Cash Registers (CRK). However, businesses may voluntarily issue B2C invoices through KSeF.
```json KSeF B2C Invoice theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PL",
"$addons": [
"pl-favat-v3"
],
"$tags": [
"simplified"
],
"uuid": "019c2849-dd61-7001-8c88-3c6d1aa83f8a",
"type": "standard",
"series": "SIMPLE",
"code": "236",
"issue_date": "2026-02-04",
"currency": "PLN",
"tax": {
"ext": {
"pl-favat-invoice-type": "UPR"
}
},
"supplier": {
"name": "Testowa Firma Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9551893317"
},
"addresses": [
{
"street": "ul. Główna 1",
"locality": "Warsaw",
"code": "00-001",
"country": "PL"
}
],
"emails": [
{
"addr": "kontakt@testowa.pl"
}
]
},
"lines": [
{
"i": 1,
"quantity": "10",
"item": {
"name": "Software Development Services",
"price": "100.00",
"unit": "h"
},
"sum": "1000.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "general",
"percent": "23.0%",
"ext": {
"pl-favat-tax-category": "1"
}
}
],
"total": "1000.00"
},
{
"i": 2,
"quantity": "5",
"item": {
"name": "Consulting Services",
"price": "150.00",
"unit": "h"
},
"sum": "750.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "reduced",
"percent": "8.0%",
"ext": {
"pl-favat-tax-category": "2"
}
}
],
"total": "750.00"
}
],
"payment": {
"instructions": {
"key": "credit-transfer",
"detail": "Transfer payment to our bank account",
"credit_transfer": [
{
"iban": "PL61109010140000071219812874",
"name": "Testowa Firma Sp. z o.o."
}
],
"ext": {
"pl-favat-payment-means": "6"
}
}
},
"totals": {
"sum": "1750.00",
"total": "1750.00",
"taxes": {
"categories": [
{
"code": "VAT",
"rates": [
{
"key": "standard",
"ext": {
"pl-favat-tax-category": "1"
},
"base": "1000.00",
"percent": "23.0%",
"amount": "230.00"
},
{
"key": "standard",
"ext": {
"pl-favat-tax-category": "2"
},
"base": "750.00",
"percent": "8.0%",
"amount": "60.00"
}
],
"amount": "290.00"
}
],
"sum": "290.00"
},
"tax": "290.00",
"total_with_tax": "2040.00",
"payable": "2040.00"
}
}
```
```json Built version theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PL",
"$addons": [
"pl-favat-v3"
],
"$tags": [
"simplified"
],
"uuid": "019c2849-dd61-7001-8c88-3c6d1aa83f8a",
"type": "standard",
"series": "SIMPLE",
"code": "236",
"issue_date": "2026-02-04",
"currency": "PLN",
"tax": {
"ext": {
"pl-favat-invoice-type": "UPR"
}
},
"supplier": {
"name": "Testowa Firma Sp. z o.o.",
"tax_id": {
"country": "PL",
"code": "9551893317"
},
"addresses": [
{
"street": "ul. Główna 1",
"locality": "Warsaw",
"code": "00-001",
"country": "PL"
}
],
"emails": [
{
"addr": "kontakt@testowa.pl"
}
]
},
"lines": [
{
"i": 1,
"quantity": "10",
"item": {
"name": "Software Development Services",
"price": "100.00",
"unit": "h"
},
"sum": "1000.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "general",
"percent": "23.0%",
"ext": {
"pl-favat-tax-category": "1"
}
}
],
"total": "1000.00"
},
{
"i": 2,
"quantity": "5",
"item": {
"name": "Consulting Services",
"price": "150.00",
"unit": "h"
},
"sum": "750.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "reduced",
"percent": "8.0%",
"ext": {
"pl-favat-tax-category": "2"
}
}
],
"total": "750.00"
}
],
"payment": {
"instructions": {
"key": "credit-transfer",
"detail": "Transfer payment to our bank account",
"credit_transfer": [
{
"iban": "PL61109010140000071219812874",
"name": "Testowa Firma Sp. z o.o."
}
],
"ext": {
"pl-favat-payment-means": "6"
}
}
},
"totals": {
"sum": "1750.00",
"total": "1750.00",
"taxes": {
"categories": [
{
"code": "VAT",
"rates": [
{
"key": "standard",
"ext": {
"pl-favat-tax-category": "1"
},
"base": "1000.00",
"percent": "23.0%",
"amount": "230.00"
},
{
"key": "standard",
"ext": {
"pl-favat-tax-category": "2"
},
"base": "750.00",
"percent": "8.0%",
"amount": "60.00"
}
],
"amount": "290.00"
}
],
"sum": "290.00"
},
"tax": "290.00",
"total_with_tax": "2040.00",
"payable": "2040.00"
}
}
```
After creating the invoice in the Console:
1. Click **Build** to validate
2. Click **Save** to store in the silo
3. Click **Select workflow** and choose the **KSeF Send Invoice** workflow
4. Click **Run workflow**
The invoice will be validated, converted to FA(3) XML format, and sent to KSeF. Upon successful clearance, it will receive a unique KSeF ID.
For international transactions, the invoice is created and cleared in KSeF just like domestic invoices. Because the foreign recipient cannot log into KSeF, delivery happens outside the platform (via email, EDI, etc.) with the KSeF QR code included for verification.
### Import received invoices
This section only applies if you configured the **send & receive** setup. If you only need to send invoices, you can skip this section entirely.
Once you've configured the import, sync, and registration (receive) workflows, the [Cron app](/apps/cron) automatically triggers the sync workflow at the interval configured in the registration workflow's **Subscribe to periodic KSeF sync** step. Here is how it works:
1. **Cron scheduling**: The [Cron app](/apps/cron) creates a job for the sync workflow at each configured interval, passing the time window (`from` and `upto`) to process
2. **Sync workflow**: The sync workflow queries KSeF for all invoices received within the time window
3. **Import jobs**: For each invoice found, a job is created using your import workflow
4. **Import workflow**: Each job downloads the FA(3) XML from KSeF, converts it to GOBL format, and stores it in your Invopop silo
5. **Organization**: Imported invoices are automatically placed in the configured folder (typically "Invoices · Expenses") with a `Registered` state
Each party is subscribed to periodic imports during registration when using the **receive** registration workflow. To use a different interval for a specific party, adjust the **Subscribe to periodic KSeF sync** step settings in the registration workflow before running it.
#### Manual import
If you need to import invoices outside of the automatic cron schedule, you can manually trigger imports from the [Console](/guides/workflows#running-from-the-console) or via the API.
**Import a single invoice**
To import a specific invoice from KSeF, you need:
* **KSeF Number**: The unique invoice identifier (e.g., `1234567890-20260120-ABCD1234-EF`)
* **Supplier NIP**: The Polish Tax ID of the invoice issuer
1. Navigate to **Workflows** and find your **KSeF Import Invoice** workflow
2. Click **Run** from the workflow editor or the `...` menu in the workflow list (see [Running from the Console](/guides/workflows#running-from-the-console))
3. Leave the document field empty — the import workflow will create a new silo entry automatically
4. Fill in the **Arguments**:
| Key | Value |
| ------------- | --------------------------------- |
| `ksef-number` | `1234567890-20260120-ABCD1234-EF` |
| `nip` | `1234567890` |
5. Click Run workflow
Use the [Create a Job endpoint](/api-ref/transform/jobs/create-a-job-post):
```bash theme={"system"}
curl -X POST https://api.invopop.com/transform/v1/jobs \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "YOUR_IMPORT_WORKFLOW_ID",
"args": {
"ksef-number": "1234567890-20260120-ABCD1234-EF",
"nip": "1234567890"
}
}'
```
The invoice will be downloaded from KSeF, converted to GOBL, and stored in your silo.
**Import multiple invoices by date range**
To import all invoices received within a specific time period, you need:
* The **party silo entry** for the supplier whose invoices you want to sync
* The **date range** (`from` and `upto`) to process
1. Navigate to **Workflows** and find your **KSeF Sync Received Invoices** workflow
2. Click **Run** from the workflow editor or the `...` menu in the workflow list
3. In the **Select a document** field, search for and select the party (supplier) entry
4. Fill in the **Arguments**:
| Key | Value |
| ------ | ---------------------- |
| `from` | `2026-01-01T00:00:00Z` |
| `upto` | `2026-01-31T23:59:59Z` |
5. Click Run workflow
Use the [Create a Job endpoint](/api-ref/transform/jobs/create-a-job-post) with your sync workflow:
```bash theme={"system"}
curl -X POST https://api.invopop.com/transform/v1/jobs \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "YOUR_SYNC_WORKFLOW_ID",
"silo_entry_id": "YOUR_PARTY_ENTRY_ID",
"args": {
"from": "2026-01-01T00:00:00Z",
"upto": "2026-01-31T23:59:59Z"
}
}'
```
The sync workflow will query KSeF for all invoices received in that date range and create individual import jobs for each invoice found.
Use single invoice import to bring in a specific invoice immediately after receiving notification from a supplier. Use date range sync to backfill invoices or to import historical invoices from before the cron subscription was active.
#### Error handling and notifications
We strongly recommend adding notification steps to your workflows to alert you of import failures:
* **In the import workflow**: Add email or Slack notifications to the error handling section
* **In the sync workflow**: Add notifications for when the sync process encounters issues
This ensures you're immediately aware if invoices fail to import, allowing you to take corrective action.
Common import issues include certificate expired or invalid, KSeF API temporarily unavailable, invoice format not supported by GOBL conversion, and network connectivity issues. Check your workflow error logs in the Console for detailed error messages.
## GOBL addon reference
Detailed information about the FA(3)-specific extensions and validations can be found in:
* [Poland FA(3) VAT v3 Addon Documentation](https://docs.gobl.org/addons/pl-favat-v3)
* [Poland Tax Regime Documentation](https://docs.gobl.org/regimes/pl)
You can also use the [GOBL Builder](https://build.gobl.org) to create custom invoices with the Polish regime and FA(3) addon.
## FAQ
International (cross-border) invoices are handled just like domestic invoices in KSeF:
* The invoice is created in GOBL with the foreign recipient's details
* It's converted to FA(3) XML format and submitted to KSeF
* KSeF validates and clears the invoice, assigning a unique KSeF ID
* The invoice is registered in the KSeF system
However, since foreign recipients cannot access KSeF, you must deliver the invoice through other channels (email, EDI, etc.). Include the KSeF QR code in the delivery for verification purposes.
**Test mode** (sandbox only): Uses self-signed certificates generated automatically by Invopop. Perfect for quick testing without accessing the KSeF portal. Invoices are not sent to real KSeF servers.
**Demo mode** (sandbox only): Connects to the official [KSeF Demo Portal](https://ap-demo.ksef.mf.gov.pl/web/). Requires manual certificate generation, simulating the full production flow in a safe test environment.
**Production mode** (live workspace): Connects to the live [KSeF Portal](https://ap.ksef.mf.gov.pl/). Requires valid company credentials and certificates. All invoices are submitted to the official KSeF system.
Use test mode for initial integration testing, then switch to demo mode when you're ready to simulate the real certificate flow before going live.
Official KSeF applications:
* [KSeF Taxpayer Application](https://ksef.podatki.gov.pl/aplikacja-podatnika-ksef-i-inne-narzedzia/bezplatne-narzedzie-wersja-produkcyjna/) – the main portal with all functionalities
* [KSeF Mobile Application](https://ksef.podatki.gov.pl/aplikacja-podatnika-ksef-i-inne-narzedzia/aplikacja-mobilna-ksef/) – a mobile app for on-the-go access
* [e-mikrofirma](https://login.mf.gov.pl/Account/Select?ReturnUrl=%2Fconnect%2Fauthorize%2Fcallback%3Fclient_id%3D09e2877e-702a-4e27-8818-9472ca964c0a%26redirect_uri%3Dhttps%253A%252F%252Furzadskarbowy.gov.pl%26response_type%3Dcode%26scope%3Dprofile%2520openid%2520DataHub.UserAccess%2520eFormsClientApi.UserAccess%2520ChatApi.UserAccess%2520offline_access%26state%3D8f196c7682654d0da49b42bfc9045e51%26code_challenge%3DSIwxyxXJpAzUgzrMW96UIH9vNc6P0-dkdc7l482AWQA%26code_challenge_method%3DS256) – a simplified portal aimed at micro-entrepreneurs
For testing:
* [KSeF Demo Portal](https://ap-demo.ksef.mf.gov.pl/web/) – demo environment for testing
Install the KSeF Poland app, register your supplier (Test, Demo, or Production environment), and run invoices through the Send Invoice workflow. Each environment requires its own NIP and certificate setup.
This error means the uploaded KSeF certificate does not have the required permissions to issue invoices. This typically happens when the certificate was uploaded by someone who is not the company administrator and only has limited permissions granted by the main company account.
The KSeF certificate uploaded to Invopop must belong to either:
* The **company account** directly logged into KSeF, or
* An entity that has both **InvoiceRead** and **InvoiceWrite** permissions (managed within KSeF)
To resolve this, you have two options:
1. **Grant permissions in KSeF**: The company admin (or whoever has direct access to the KSeF company account) grants `InvoiceRead` and `InvoiceWrite` permissions to the user who uploaded the certificate to Invopop. This can be done from the [KSeF application portal](https://ap.ksef.mf.gov.pl/) and requires no further action in Invopop (no need to unregister/register).
2. **Re-register with a new certificate**: Unregister the supplier in Invopop and register it again using a certificate generated from the main KSeF company account (or another account with the required permissions).
See the [Poland tax regime in GOBL](https://docs.gobl.org/regimes/pl) for tax categories and NIP rules. The [`pl-favat-v3`](https://docs.gobl.org/addons/pl-favat-v3) addon documents the FA(3) schema fields required for KSeF.
Polish invoicing law requires a unit of measure for every line, and KSeF maps it to the `P_8A` field on each `FaWiersz`. Invopop supports two ways to populate it:
1. **Canonical unit code on `Item.Unit`** — preferred when the unit exists in the GOBL unit catalogue or as a UN/ECE Recommendation 20 code. For example, `Item.Unit: "H87"` (piece) or `Item.Unit: "KGM"` (kilogram). The gobl.ksef converter emits the UN/ECE code directly into `P_8A`.
2. **Free-form label on `Item.Meta["unit-label"]`** — use this for Polish abbreviations that do not match a canonical code, such as `"szt."` (sztuka — piece), `"usł."` (usługa — service), `"kpl."` (komplet — set) or `"opak."` (opakowanie — package). The value is passed through to `P_8A` unchanged, so the supplier's exact wording is preserved on the KSeF XML.
Example line item using a free-form label:
```json theme={"system"}
{
"item": {
"name": "Konsultacja prawna",
"price": "200.00",
"meta": {
"unit-label": "usł."
}
},
"quantity": "1"
}
```
When an inbound KSeF invoice contains a `P_8A` value that is not a recognised GOBL or UN/ECE code, gobl.ksef preserves the original string under `Item.Meta["unit-label"]` so round-trips do not lose the supplier's wording. `Item.Unit` is only populated when the value validates as a canonical code.
More available in our [Poland FAQ](/faq/poland) section
***
| | |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Compliance | [Invoicing compliance in Poland](/compliance/poland)
[Compliance timeline](/timelines/poland) |
| Apps | [Poland](/apps/poland) |
| Guides | [Poland Guide](/guides/pl-ksef) |
| FAQ | [Poland FAQ](/faq/poland) |
| GOBL | [Poland Tax Regime](https://docs.gobl.org/regimes/pl)
[Polish KSeF FA(3) Addon](https://docs.gobl.org/addons/pl-favat-v3) |
Ask and answer questions about invoicing in Poland →