> ## 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 supplier registration guide

> Register parties (suppliers) with Poland's KSeF 2.0 system so you can issue invoices on their behalf.

## 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). 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](/apps/poland). Once a party is registered, continue with the companion guide: [Poland: Issuing invoices](/guides/pl-ksef).

| -            | 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                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Badge color="green">Invopop Sandbox</Badge><br />Test mode | **Test Polish Tax ID (NIP)** <br /> 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. <br /> |
| <Badge color="green">Invopop Sandbox</Badge><br />Demo mode | **Real Polish Tax ID (NIP) and credentials to access the [KSeF Demo Portal](https://ap-demo.ksef.mf.gov.pl/web/)** <br /> Demo mode follows the same registration process as production but operates in the demo environment.                                 |
| <Badge color="green">Invopop Live</Badge>                   | **Valid company NIP and credentials to access the [KSeF Portal](https://ap.ksef.mf.gov.pl/)** <br /> 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).

<Steps>
  <Step title="Connect the Poland app">
    1. Navigate to **Configuration** → **Apps**
    2. Find **Poland** in the app discovery list
    3. Click **Connect** to activate

    <Frame>
      <img width="354" src="https://mintcdn.com/invopop/eZRYdDQqMJhhshgw/assets/guides/gov-pl-connect.png?fit=max&auto=format&n=eZRYdDQqMJhhshgw&q=85&s=2d26db0ad734f1da82b08b10244fc6d0" alt="Connect KSeF app" data-path="assets/guides/gov-pl-connect.png" />
    </Frame>

    The initial connection requires no configuration.
  </Step>

  <Step title="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](/guides/pl-ksef):

    * **Send only** — registers the party with KSeF for sending invoices.
    * **Send & receive** — additionally subscribes the party to periodic invoice imports via the [Cron app](/apps/cron).

    <Frame>
      <img width="400" src="https://mintcdn.com/invopop/m7w0i5JCm3gcCeuk/assets/guides/pl-register-config.png?fit=max&auto=format&n=m7w0i5JCm3gcCeuk&q=85&s=d4552763900a81f45280fffcfb15a242" alt="Choose KSeF environment (Test or Demo)" data-path="assets/guides/pl-register-config.png" />
    </Frame>

    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.

    <Info>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.</Info>

    In **live workspaces** no configuration is available, all suppliers are registered in the KSeF production environment.

    #### Send only

    <Tabs>
      <Tab title="Template">
        <Card iconType="duotone" title="KSeF party registration workflow (send)" icon="code-branch" href="https://console.invopop.com/redirect/workflows/new?template=pl-register" cta="Add to my workspace">
          Registers a party (supplier) with the KSeF system for sending invoices.
        </Card>
      </Tab>

      <Tab title="Code">
        Copy and paste into a new [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) code view.

        <Note>
          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.
        </Note>

        ```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"
                    }
                }
            ]
        }
        ```
      </Tab>

      <Tab title="Build from scratch">
        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`.
      </Tab>
    </Tabs>

    #### Send & receive

    <Info>
      This variant requires the [Cron app](/apps/cron) to be connected and the import and sync workflows to be configured first — both are covered in the [issuing invoices guide setup](/guides/pl-ksef#setup).
    </Info>

    <Tabs>
      <Tab title="Template">
        <Card iconType="duotone" title="KSeF party registration workflow (receive)" icon="code-branch" href="https://console.invopop.com/redirect/workflows/new?template=pl-register-receive" cta="Add to my workspace">
          Registers a party (supplier) with the KSeF system and subscribes them to periodic invoice imports.
        </Card>
      </Tab>

      <Tab title="Code">
        Copy and paste into a new [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) code view.

        <Note>
          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.
        </Note>

        ```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"
                    }
                }
            ]
        }
        ```
      </Tab>

      <Tab title="Build from scratch">
        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`.
      </Tab>
    </Tabs>

    #### 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](/apps/cron) which workflow to run and how often.

    1. **Workflow** — select the **KSeF Sync Received Invoices** workflow you created during the [issuing invoices guide setup](/guides/pl-ksef#setup). 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:

    <Frame>
      <img width="500" src="https://mintcdn.com/invopop/pOmQD8W3zKXkCwsD/assets/guides/pl-config-cron.png?fit=max&auto=format&n=pOmQD8W3zKXkCwsD&q=85&s=a7522555034af5f2ef884625c7a092b3" alt="Configured Subscribe to periodic KSeF sync step showing the selected sync workflow and interval" data-path="assets/guides/pl-config-cron.png" />
    </Frame>
  </Step>
</Steps>

## 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

<Note>
  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.
</Note>

<Steps>
  <Step title="Create the party">
    In the [Invopop Console](https://console.invopop.com), navigate to **Parties** → **Suppliers** and click <kbd>+ New Supplier</kbd>.

    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 <kbd>Build</kbd>, ensure there are no errors, and click <kbd>Save</kbd>.
  </Step>

  <Step title="Run the workflow">
    In the party entry, click on <kbd>Select Workflow</kbd>, choose your **KSeF Register Party (Test)** workflow, and click <kbd>Run Workflow</kbd>.

    **That's it!** ✓ Registration completes automatically. The party is now in <Badge color="purple">Registered</Badge> state and ready to issue invoices.
  </Step>
</Steps>

At this point, you're ready to start sending invoices on behalf of the party. Head over to the [KSeF issuing invoices guide](/guides/pl-ksef) to continue.

***

### Register a party for demo/production environment

<Note>
  In sandbox workspaces, choose Demo mode when you want to simulate the real production flow with KSeF authentication in a safe demo environment.
</Note>

<Steps>
  <Step title="Create the party">
    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/org/party",
      "name": "Real Company Sp. z o.o.",
      "tax_id": {
        "country": "PL",
        "code": "1234567890"
      }
    }
    ```

    Click <kbd>Build</kbd>, ensure there are no errors, and click <kbd>Save</kbd>.
  </Step>

  <Step title="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 <kbd>Run Workflow</kbd>. The party will be in <Badge color="yellow">Processing</Badge> state until certificate upload is complete.
  </Step>

  <Step title="Access the registration link">
    Get the registration link to begin certificate generation:

    <Badge color="green">Your own company</Badge><br />
    In Console, go to the supplier entry → **Meta** tab → click the **gov-pl.invopop.com** link to launch the registration wizard.

    <Frame>
      <img width="398" src="https://mintcdn.com/invopop/N5Kgn5kuF0KDuWiM/assets/guides/pl-meta-link.png?fit=max&auto=format&n=N5Kgn5kuF0KDuWiM&q=85&s=aaf8cc93be5f8548a632d24d5555cca5" alt="Supplier entry meta with KSeF registration link" data-path="assets/guides/pl-meta-link.png" />
    </Frame>

    <Badge color="green">Third-party companies</Badge> (white label)<br />
    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://gov-pl.invopop.com/reg/AbC123XyZ"
          }
        ]
      }
    }
    ```

    Send the `link_url` to your customer.
  </Step>

  <Step title="Generate a certificate in KSeF portal">
    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)

    <Warning>
      Save the certificate and private key files, as well as the password. You'll need them in the next step.
    </Warning>
  </Step>

  <Step title="Upload certificate to Invopop">
    There are two ways to upload the certificate:

    <Badge color="green">Web Upload</Badge> (Wizard)<br />
    Return to the registration wizard and upload:

    * Certificate file
    * Private key file
    * Password

    <Frame>
      <img width="600" src="https://mintcdn.com/invopop/N5Kgn5kuF0KDuWiM/assets/guides/pl-upload-certificate.png?fit=max&auto=format&n=N5Kgn5kuF0KDuWiM&q=85&s=372e0f53d21ba7d58948fb18a5dd5f60" alt="KSeF certificate upload form" data-path="assets/guides/pl-upload-certificate.png" />
    </Frame>

    Click <kbd>Upload and verify certificate</kbd>. The system validates and securely stores your credentials.

    <Badge color="green">API Upload</Badge><br />
    Upload the certificate programmatically using the [Upload KSeF certificate endpoint](/api-ref/apps/gov-pl/certificate-upload).

    <Note>
      This approach is ideal for automated integrations where you want to handle certificate generation and upload programmatically without user interaction with the web wizard.
    </Note>

    ✓ **Success**: The supplier transitions to <Badge color="purple">Registered</Badge> 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.
  </Step>
</Steps>

At this point, you're ready to start sending invoices on behalf of the party. Head over to the [KSeF issuing invoices guide](/guides/pl-ksef) to continue.

## FAQ

<AccordionGroup>
  <Accordion title="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

    <Note>
      Check the workflow error logs in the Invopop Console for detailed error messages that can help diagnose the specific issue.
    </Note>
  </Accordion>

  <Accordion title="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/](http://generatory.it/). These work immediately with self-signed certificates.
    * **Demo mode**: You need a real NIP with access to the KSeF Demo Portal.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

More available in our [Poland FAQ](/faq/poland) section

***

<AccordionGroup>
  <Accordion title="🇵🇱 Invopop resources for Poland">
    |            |                                                                                                                                                                                                                                                      |
    | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Compliance | <Icon icon="https://assets.invopop.com/flags/pl.svg" /> [Invoicing compliance in Poland](/compliance/poland)<br /> <Icon icon="timeline" /> [Compliance timeline](/timelines/poland)                                                                 |
    | Apps       | <Icon icon="https://assets.invopop.com/flags/pl.svg" /> [Poland](/apps/poland)                                                                                                                                                                       |
    | Guides     | <Icon icon="book" /> [Supplier registration](/guides/pl-ksef-supplier)<br /> <Icon icon="book" /> [Issuing invoices](/guides/pl-ksef)                                                                                                                |
    | FAQ        | <Icon icon="square-question" /> [Poland FAQ](/faq/poland)                                                                                                                                                                                            |
    | GOBL       | <Icon icon="https://assets.invopop.com/icons/gobl.svg" />  [Poland Tax Regime](https://docs.gobl.org/regimes/pl)<br /> <Icon icon="https://assets.invopop.com/icons/gobl.svg" /> [Polish KSeF FA(3) Addon](https://docs.gobl.org/addons/pl-favat-v3) |
  </Accordion>
</AccordionGroup>

<Card title="Participate in our community" icon="forumbee" href="https://community.invopop.com" arrow="true" horizontal>
  Ask and answer questions about invoicing in Poland →
</Card>