KSeF 2.0 Poland Guide

Introduction

KSeF (Krajowy System e-Faktur) 2.0 is Poland’s mandatory national e-invoicing system operated by the Ministry of Finance. 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 two key processes:

Party Registration: Registering suppliers in the KSeF system
Invoice Issuance: Creating and sending FA(3) invoices through KSeF
Invoice Import: Importing received invoices from KSeF

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/. 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 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 You will need to generate a certificate through the KSeF portal. Registration will automatically target the KSeF production environment.

Setup

There are six key processes to prepare:

Connect the Poland app
Connect the Cron app
Configure an invoice sending workflow
Configure an invoice import workflow
Configure an invoice sync workflow
Configure a party registration workflow

All of the following steps must be carried out from the Invopop Console.

Connect the Poland app

Navigate to Configuration → Apps
Find Poland in the app discovery list
Click Connect to activate

The initial connection requires no configuration.

Connect the Cron app

Navigate to Configuration → Apps
Find Cron in the app discovery list
Click Connect to activate

No additional configuration is needed. The Cron app handles scheduling periodic workflow execution for importing received invoices.

Configure invoice sending workflow

Template
Code
Build from scratch

KSeF send invoice workflow

Signs and converts the GOBL document into the FA(3) XML format and sends it to KSeF.

Copy and paste into a new Empty Invoice workflow code view.

Example Send KSeF invoice workflow with states

{
    "name": "Send KSeF invoice",
    "description": "Generate FAVAT (3) XML and send it to 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 FA_VAT v3 XML 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 to understand the general setup process.In Console, create a new workflow and choose Empty Invoice workflow as the base. Then add the following steps:

Set state - To Processing
Add sequential code - Add the desired sequence for your invoices
Sign envelope - Signs the GOBL document preventing further modifications
Generate FA(3) XML - Generates the FA(3) XML
Send FA(3) XML to KSeF - Sends the FA(3) XML to KSeF
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.

Configure invoice import workflow

This workflow imports individual invoices from KSeF when they are received. It is automatically triggered by the sync workflow for each invoice found.

Template
Code
Build from scratch

KSeF import invoice workflow

Imports a received invoice from KSeF and converts it to GOBL format.

Copy and paste into a new Empty Invoice workflow 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.

Example Import KSeF invoice workflow with states

{
    "name": "Import KSeF invoice",
    "description": "Import a received invoice from 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 to understand the general setup process.In Console, create a new workflow and choose Empty Invoice workflow 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:

Import invoice from KSeF - Downloads the invoice from KSeF and converts it to GOBL format
Set folder - To Invoices · Expenses (or your preferred folder)
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.

Configure invoice sync workflow

This workflow syncs all received invoices for a party within a specific time range. It creates import jobs for each invoice found.Configure the Sync received invoices from KSeF step to reference the import workflow you created in the previous step. The sync workflow will create a job for each invoice and send it to the import workflow.

Configure the workflow that all invoices will be sent to

Template
Code
Build from scratch

KSeF sync received invoices workflow

Creates import jobs for each received invoice of a party in KSeF.

Copy and paste into a new Empty Party workflow code view.

Example Sync Received invoices from KSeF workflow with states

{
    "name": "Sync Received invoices from KSeF",
    "description": "Create import jobs for each received invoice of a party in KSeF",
    "schema": "org/party",
    "steps": [
        {
            "id": "5bddfd40-0220-11f1-bd80-c7df39ccdf0b",
            "name": "Sync received invoices from KSeF",
            "provider": "gov-pl.sync"
        }
    ],
    "rescue": []
}

Configure party registration workflow

In Sandbox the Register Party in 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.

Template
Code
Build from scratch

KSeF party registration workflow

Registers a party (supplier) with the KSeF system and subscribes them to periodic invoice imports.

After adding the template, open the Subscribe to periodic import step and set the Workflow field to the sync workflow created in the previous step and the Interval to your preferred frequency.

Copy and paste into a new Empty Party workflow code view.

The template uses test mode by default (for sandbox). To use demo mode in sandbox, add "config": {"environment": "demo"} to the Register for KSeF step. In Invopop production, the workflow automatically targets the KSeF production environment.

Example Register supplier for KSeF workflow with states

{
    "name": "Register for KSeF",
    "description": "Register a party in KSeF",
    "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 for 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 KSeF sync",
            "provider": "cron.subscribe"
        },
        {
            "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"
            }
        }
    ]
}

After pasting the code, switch to the form view, open the Subscribe to periodic import step and set the Workflow field to the sync workflow and the Interval to your preferred frequency.

Before starting, review the workflows guide to understand the general setup process.In Console, create a new workflow and choose Empty Party workflow as the base. Then name the workflow with a descriptive label such as “KSeF Register Party”.The new workflow will need to perform these steps:

Set state - To Processing
Register party in KSeF (Poland) - Registers the party with KSeF and generates a registration link. Configure with your chosen environment (test, demo, or production).
Wait for KSeF certificate upload - Waits for the supplier to generate and upload their KSeF certificate (automatically skipped in test mode)
Subscribe to periodic import - Uses the Cron app to schedule periodic execution of the sync workflow. Configure with the sync workflow and your preferred interval.
Set state - To Registered

Finally, in the Error handling area, add the Set state action and select Error.

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.

Create the party

In the Invopop Console, navigate to Parties → Suppliers and click + New Supplier.Use fake Polish Tax IDs (NIP) generated from http://generatory.it/:

{
  "$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.

Run the workflow

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.

Create the party

Use real Polish Tax IDs (NIP) with access to the KSeF Demo Portal or KSeF Portal:

{
  "$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.

Run the workflow

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.

Access the registration link

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.

Supplier entry meta with KSeF registration link

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 Party in KSeF step to receive the siloEntryId.Use the Fetch an Entry endpoint to get the registration link from the meta object:

{
  "data": {
    "meta": [
      {
        "src": "gov-pl",
        "key": "link",
        "link_url": "https://ksef.invopop.com/reg/AbC123XyZ"
      }
    ]
  }
}

Send the link_url to your customer.

Generate a certificate in KSeF portal

The registration wizard will guide you through these steps:

Visit the KSeF portal
- Demo: KSeF Demo Portal
- Production: KSeF Portal
Log in with Trusted Profile (Profil Zaufany)
- Video tutorial: Setting up Trusted Profile
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

Save the certificate and private key files, as well as the password. You’ll need them in the next step.

Upload certificate to Invopop

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.

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? 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 documents you can copy and paste directly into the Invopop Console 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.

B2B Standard Invoice

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 addon ensures the document will be validated using the KSeF rules built into the GOBL 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.

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

B2B Reverse Charge Invoice

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.

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

B2B Credit Note

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.

{
  "$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"
          }
        }
      ]
    }
  ]
}

B2B Prepayment Invoice (Faktura Zaliczkowa)

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.

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

B2B Settlement Invoice (Faktura Rozliczeniowa)

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.

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

B2C Invoice (voluntary)

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.

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

Click Build to validate
Click Save to store in the silo
Click Select workflow and choose the KSeF Send Invoice workflow
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

Once you’ve configured the import, sync, and registration workflows, the Cron app automatically triggers the sync workflow at the interval configured in the registration workflow’s Subscribe to periodic import step. Here is how it works:

Cron scheduling: The Cron app creates a job for the sync workflow at each configured interval, passing the time window (from and upto) to process
Sync workflow: The sync workflow queries KSeF for all invoices received within the time window
Import jobs: For each invoice found, a job is created using your import workflow
Import workflow: Each job downloads the FA(3) XML from KSeF, converts it to GOBL format, and stores it in your Invopop silo
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. To use a different interval for a specific party, adjust the Subscribe to periodic import step settings in the registration workflow before running it. To skip automatic imports for a party, remove the cron subscription step before running it.

Manual import

If you need to import invoices outside of the automatic cron schedule, you can manually trigger imports using the Invopop API.

Manual import with workflow arguments is only available via API. The Console UI does not currently support passing custom arguments to workflow jobs.

Import a single invoice To import a specific invoice from KSeF:

Get invoice details from the KSeF portal

KSeF Number: The unique invoice identifier (e.g., 1234567890-20260120-ABCD1234-EF)
Supplier NIP: The Polish Tax ID of the invoice issuer

Create a job via API

Use the Create a Job endpoint:

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:

Determine the date range

Decide the date range you want to sync (from and upto dates).

Create a job via API

Use the Create a Job endpoint with your sync workflow:

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:

You can also use the GOBL Builder to create custom invoices with the Polish regime and FA(3) addon.

🇵🇱 Invopop resources for Poland


Compliance	Invoicing compliance in Poland Compliance timeline
Apps	Poland
Guides	Poland Guide
FAQ	Poland FAQ
GOBL	Poland Tax Regime Polish KSeF FA(3) Addon

Poland FAQ

Find answers to frequently asked questions about invoicing in Poland →

Participate in our community

Ask and answer questions about invoicing in Poland →

Networks

Countries

Set-up

GOBL

Apps

API

Features

KSeF 2.0 Poland Guide

Introduction

Prerequisites

Setup

KSeF send invoice workflow

KSeF import invoice workflow

KSeF sync received invoices workflow

KSeF party registration workflow

Running

Register a party for test environment

Register a party for demo/production environment

Send an invoice

Import received invoices

Manual import

Error handling and notifications

GOBL addon reference

Poland FAQ

Participate in our community

Networks

Countries

Set-up

GOBL

Apps

API

Features

​Introduction

​Prerequisites

​Setup

KSeF send invoice workflow

KSeF import invoice workflow

KSeF sync received invoices workflow

KSeF party registration workflow

​Running

​Register a party for test environment

​Register a party for demo/production environment

​Send an invoice

​Import received invoices

​Manual import

​Error handling and notifications

​GOBL addon reference

Poland FAQ

Participate in our community

Introduction

Prerequisites

Setup

Running

Register a party for test environment

Register a party for demo/production environment

Send an invoice

Import received invoices

Manual import

Error handling and notifications

GOBL addon reference