KSeF supplier registration guide

Introduction

KSeF (Krajowy System e-Faktur) 2.0 is Poland’s mandatory national e-invoicing system operated by the Ministry of Finance. Before you can issue invoices through KSeF on behalf of a party (supplier), the party must be registered with the KSeF system. In this guide you’ll learn how to register a party using the Poland app. Once a party is registered, continue with the companion guide: Poland: Issuing 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 register a party with 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

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.

Configure the party registration workflow

This workflow registers a party in KSeF so you can issue invoices on their behalf. There are two variants, depending on the use case described in the issuing invoices guide:

Send only — registers the party with KSeF for sending invoices.
Send & receive — additionally subscribes the party to periodic invoice imports via the Cron app.

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 more accurately simulates 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.

Send only

Template
Code
Build from scratch

KSeF party registration workflow (send)

Registers a party (supplier) with the KSeF system for sending invoices.

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 supplier with KSeF step. In Invopop production, the workflow automatically targets the KSeF production environment.

Example KSeF register supplier (send) workflow

{
    "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 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 (Send)”.The new workflow will need to perform these steps:

Set state - To Processing
Register supplier with KSeF - 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)
Set state - To Registered

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

Send & receive

This variant requires the Cron app to be connected and the import and sync workflows to be configured first — both are covered in the issuing invoices guide setup.

Template
Code
Build from scratch

KSeF party registration workflow (receive)

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

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

Example KSeF register supplier (receive) workflow

{
    "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 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 (Receive)”.The new workflow will need to perform these steps:

Set state - To Processing
Register supplier with KSeF - 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 KSeF sync - 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.

Configure the cron step to start syncing invoices to Invopop

After adding the send & receive 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 which workflow to run and how often.

Workflow — select the KSeF Sync Received Invoices workflow you created during the issuing invoices guide setup. The Cron app will trigger this workflow on each tick.
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) in the test, demo, and production environments.

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.

At this point, you’re ready to start sending invoices on behalf of the party. Head over to the KSeF issuing invoices guide to continue.

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/org/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)
Add a webhook after the Register supplier with 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://gov-pl.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.

At this point, you’re ready to start sending invoices on behalf of the party. Head over to the KSeF issuing invoices guide to continue.

FAQ

Why did my supplier registration fail?

Common reasons for registration failures:

Certificate and private key mismatch: Ensure you uploaded both files from the same certificate generation
Incorrect password: Verify the password matches what you set during certificate generation
Future start date: Certificate start date must be today or in the past
Wrong portal environment: Demo certificates won’t work with production, and vice versa
File encoding issues: For API uploads, ensure files are properly base64-encoded
Expired certificate: Check that the certificate is still valid
Invalid NIP: Verify the Polish Tax ID is correct and has access to KSeF

Check the workflow error logs in the Invopop Console for detailed error messages that can help diagnose the specific issue.

I don't have a Polish NIP for testing. How can I get one?

For sandbox testing:

Test mode: Generate fake NIPs at http://generatory.it/. These work immediately with self-signed certificates.
Demo mode: You need a real NIP with access to the KSeF Demo Portal.

How do I onboard a new supplier in Poland?

Choose an environment (Test, Demo, or Production). Generate a KSeF certificate from the relevant portal (or use a self-signed cert in Test mode), upload it to Invopop with the matching password, and register the supplier through the KSeF Register Supplier workflow.

What certificates does KSeF require to authenticate a supplier?

A KSeF certificate exported as PKCS#12 (.p12) with password, generated through the KSeF Application Portal (or auto-generated by Invopop in Test mode). The certificate must have InvoiceRead + InvoiceWrite permissions.

How are supplier credentials stored in Invopop for Poland?

The KSeF certificate (PKCS#12 .p12 with password) is stored encrypted at rest. Invopop uses it to authenticate session creation with KSeF on the supplier’s behalf; the password is never returned in API responses.

More available in our Poland FAQ section

🇵🇱 Invopop resources for Poland


Compliance	Invoicing compliance in Poland Compliance timeline
Apps	Poland
Guides	Supplier registration Issuing invoices
FAQ	Poland FAQ
GOBL	Poland Tax Regime Polish KSeF FA(3) Addon

Participate in our community

Ask and answer questions about invoicing in Poland →

Networks

Countries

Set-up

GOBL

Apps

API

Features

KSeF supplier registration guide

Introduction

Prerequisites

Setup

Send only

KSeF party registration workflow (send)

Send & receive

KSeF party registration workflow (receive)

Configure the cron step to start syncing invoices to Invopop

Running

Register a party for test environment

Register a party for demo/production environment

FAQ

Participate in our community

​Introduction

​Prerequisites

​Setup

​Send only

KSeF party registration workflow (send)

​Send & receive

KSeF party registration workflow (receive)

​Configure the cron step to start syncing invoices to Invopop

​Running

​Register a party for test environment

​Register a party for demo/production environment

​FAQ

Participate in our community

Introduction

Prerequisites

Setup

Send only

Send & receive

Configure the cron step to start syncing invoices to Invopop

Running

Register a party for test environment

Register a party for demo/production environment

FAQ