Skip to main content

โ€‹
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:

โ€‹
Prerequisites

To issue invoices through KSeF, you will need:
EnvironmentRequirements
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 LiveValid 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 five key processes to prepare:
  • Connect the Poland app
  • Configure a party registration workflow
  • Configure an invoice sending workflow
  • Configure an invoice import workflow
  • Configure an invoice sync workflow
All of the following steps must be carried out from the Invopop Console.
1

Connect the Poland app

  1. Navigate to Configuration โ†’ Apps
  2. Find Poland in the app discovery list
  3. Click Connect to activate
Connect KSeF app
The initial connection requires no configuration.
2

Configure party registration workflow

Choose KSeF environment (Test or Demo)
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.In both live and sandbox Polling Interval can configure how often Invopop checks KSeF for new received invoices (hourly, daily, weekly, monthly, or disabled). This determines how often invoices are imported into Invopop.

KSeF party registration workflow

Registers a party (supplier) with the KSeF system.
3

Configure invoice sending workflow

KSeF send invoice workflow

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

Configure invoice import workflow

This workflow imports individual invoices from KSeF when they are received. It will be automatically triggered by the polling service when new invoices are detected.

KSeF import invoice workflow

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

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

KSeF sync received invoices workflow

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

Configure app for automatic polling

To enable automatic import of received invoices, configure the Poland app with your sync workflow:
  1. Navigate to Configuration โ†’ Apps
  2. Find the Poland app and click Configure
  3. In the Sync Workflow field, select the sync workflow you created in the previous step
  4. Click Save
Configure app for automatic polling
The polling service will now automatically check KSeF for new invoices based on the interval you configured during party registration. When new invoices are found, they will be imported using your configured workflows.

โ€‹
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.
1

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/party",
  "name": "Test Supplier Sp. z o.o.",
  "tax_id": {
    "country": "PL",
    "code": "9876543210"
  }
}
Click Build, ensure there are no errors, and click Save.
2

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.
1

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.
2

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.
3

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.
4

Generate a Certificate in KSeF Portal

The registration wizard will guide you through these steps:
  1. Visit the KSeF portal
  2. Log in with Trusted Profile (Profil Zaufany)
  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
Save the certificate and private key files, as well as the password. Youโ€™ll need them in the next step.
5

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
KSeF certificate upload form
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
{
  "$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": "[email protected]"
      }
    ]
  },
  "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"
        }
      ]
    },
    {
      "quantity": "5",
      "item": {
        "name": "Consulting Services",
        "price": "150.00",
        "unit": "h"
      },
      "taxes": [
        {
          "cat": "VAT",
          "rate": "reduced"
        }
      ]
    }
  ],
  "payment": {
    "instructions": {
      "key": "credit-transfer",
      "detail": "Transfer payment to our bank account",
      "credit_transfer": [
        {
          "iban": "PL61109010140000071219812874",
          "name": "Testowa Firma Sp. z o.o."
        }
      ]
    }
  }
}
For reverse charge invoices, the process is the same but the customer will have a EU VAT ID:
{
  "$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."
    }
  ]
}

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

Once youโ€™ve configured the import and sync workflows, Invopop will automatically poll KSeF for new received invoices based on the polling interval you set during party registration.

โ€‹
How Automatic Import Works

  1. Polling Service: Invopop checks KSeF at your configured interval (1 hour, 1 day, 1 week, or 1 month)
  2. Sync Workflow: When new invoices are detected, the sync workflow queries KSeF for all invoices received since the last poll
  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
Polling Intervals: You can set different polling intervals for each party during registration. If you donโ€™t want to automatically receive invoices for a specific party, set the polling interval to โ€œno pollingโ€ during registration.

โ€‹
Manual Import

If you need to import invoices outside of the automatic polling 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:
  1. 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
  2. Create a job via API using the Create a Job endpoint: 
curl -X POST https://api.invopop.com/silo/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:
  1. Determine the date range you want to sync (from and to dates)
  2. Create a job via API using the Create a Job endpoint with your sync workflow: 
curl -X POST https://api.invopop.com/silo/jobs \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "YOUR_SYNC_WORKFLOW_ID",
    "entry_id": "YOUR_PARTY_ENTRY_ID",
    "args": {
      "from": "2026-01-01T00:00:00Z",
      "to": "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 Cases:
  • Single invoice: Import a specific invoice immediately after receiving notification from a supplier
  • Date range sync: Backfill invoices after a polling outage or to import historical invoices before automatic polling was enabled

โ€‹
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:
  • Certificate expired or invalid
  • KSeF API temporarily unavailable
  • Invoice format not supported by GOBL conversion
  • 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.

Poland FAQ

Find answers to frequently asked questions about invoicing in Poland โ†’

Participate in our community

Ask and answer questions about invoicing in Poland โ†’