Retrieve invoices

Configure and troubleshoot inbound invoice polling from the tax authority system.

The tax authority system stores invoices centrally but does not push them to buyers. Buyers must poll the tax authority at regular intervals to retrieve invoices issued to them. Sovos offers a polling service that authenticates to the tax authority on behalf of buyers and makes invoices accessible through the Sovos API.

Prerequisites

Before configuring polling, make sure you have Krajowy System e-Faktur (KSeF) credentials and Sovos API credentials.

For credential setup details, see Set up credentials.

How polling works

Sovos polls KSeF on your behalf on a regular schedule and runs a daily reconciliation pass to catch any missed invoices. You can also request retrieval for a specific historical date range.

Important:

KSeF only lets buyers retrieve invoices when the buyer's tax ID is in the Podmiot2/NIP field. If a supplier puts the buyer's tax ID in the NrVatUe field instead, those invoices cannot be retrieved. In that case, KSeF does not recognize the customer as an authorized buyer and returns a 403 Forbidden error.

Polling cycles and pagination

Each polling operation retrieves documents in cycles. When the tax authority returns more documents than the configured page size for a date range, the system uses pagination to retrieve all documents.

Document processing after polling

After polling retrieves documents from the tax authority, the system automatically processes them through the following stages:

Mapping: Transforms the KSeF invoice format to Sovos Canonical Invoice format.
Rendering: Generates a PDF representation of the invoice.
Distribution: Delivers the invoice and attachments to configured recipients via email.

This workflow runs automatically for all polled documents.

Configure inbound polling

Set up inbound polling to retrieve invoices from the tax authority system.

Before you begin

Before configuring polling, make sure you have completed credential setup. See Set up credentials.

Enable polling for a buyer NIP

To start polling for invoices, enable the polling workflow for your buyer NIP.

API request:

JSON

PUT /api/v1/configurations
{
  "category": "PL_INV",
  "productId": "pl_Faktura_Polling_2.0",
  "scope": {
    "orgId": "[YOUR_ORG_ID]",
    "taxId": "[YOUR_TAX_ID]"
  },
  "contexts": [
    {
      "name": "polling",
      "configurations": [
        {
          "name": "polling_process_configuration",
          "value": {
            "pollingWorkflowState": "enable"
          }
        }
      ]
    }
  ]
}

PUT /api/v1/configurations
{
  "category": "PL_INV",
  "productId": "pl_Faktura_Polling_2.0",
  "scope": {
    "orgId": "[YOUR_ORG_ID]",
    "taxId": "[YOUR_TAX_ID]"
  },
  "contexts": [
    {
      "name": "polling",
      "configurations": [
        {
          "name": "polling_process_configuration",
          "value": {
            "pollingWorkflowState": "enable"
          }
        }
      ]
    }
  ]
}

Sovos polls KSeF on your behalf on a regular schedule and runs a daily reconciliation pass to catch any missed invoices. You can also request retrieval for a specific historical date range

Disable polling

To stop polling for a buyer NIP, disable the polling workflow:

JSON

curl --location --request PUT 'https://api-test.sovos.com/v2/configurations/organizations/{orgId}/settings/{settingId}' \
--header Content-Type: application/json \
--header Authorization: Bearer {accessToken} \
--header x-correlationId: {uniqueValue} \
--data-raw '{
    "value": {
         "pollingWorkflowState": "disable"
    }
}'

curl --location --request PUT 'https://api-test.sovos.com/v2/configurations/organizations/{orgId}/settings/{settingId}' \
--header Content-Type: application/json \
--header Authorization: Bearer {accessToken} \
--header x-correlationId: {uniqueValue} \
--data-raw '{
    "value": {
         "pollingWorkflowState": "disable"
    }
}'

Important: Disabling polling does not delete your configuration or credentials. You can re-enable at any time without reconfiguring.

Access retrieved invoices notifications

Retrieve and interpret notifications for invoices polled from the tax authority.

After polling retrieves invoices from the tax authority, you can access notifications to monitor status updates, attachments, KSeF reference number, and other legal information.

When an event occurs on a document, like transmission or approval, Indirect Tax API creates a Notification object. Learn how to Check notifications and About Sovos application responses.

e-invoicing