E-Invoicing for Poland: API References

Introduction

Poland has introduced the Krajowy System e-Faktur (KSeF) to streamline invoicing, improve tax compliance, and reduce fraud. Businesses can voluntarily use KSeF since January 2022, and it will soon become mandatory for all B2B transactions. E-invoicing ensures faster processing, automatic VAT compliance, reduced tax fraud, and secure storage. Invoices must be issued in a structured XML format and submitted to the government portal for validation. Flick Network simplifies this process by integrating with KSeF and Peppol, enabling businesses to send, receive, and track invoices seamlessly while ensuring full compliance with Polish regulations.

Key Points:

Standard Format: Poland’s KSeF system requires e-invoices to follow a structured XML format for validation and compliance.
Mandatory Compliance: KSeF will become mandatory for B2B transactions, requiring businesses to adopt the system for tax reporting and invoicing.
Tax Reporting: E-invoices are automatically reported to tax authorities, reducing fraud risks and improving VAT compliance.
Secure and Efficient: E-invoicing in Poland ensures faster processing, digital archiving, and secure access to invoice data.

POST/pl/einvoice/generate/invoice

Submit an Invoice

To generate a new E-Invoice document & share it through Peppol, use this endpoint along with the Supplier UUID. Specify transport_mode for proper delivery.

Request Body

Name
ID
Type
string: mandatory (limit: 50 chars)
Description
Unique Invoice Reference Number, made in sequence.
Name
DocumentType
Type
string: mandatory (limit: 50 chars)
Description
Type of document, e.g., Invoice or CorrectionInvoice.
Name
IssueDate
Type
date: mandatory, schema: YYYY-MM-DD
Description
Date when the invoice was issued.
Name
DocumentCurrencyCode
Type
string: mandatory (3 chars)
Description
Invoice currency. Default: PLN.
Name
CustomerParty
Type
object: mandatory
Description
Customer information.
Name
RegisteredName
Type
string: mandatory (limit: 300 chars)
Description
Customer/Receiving company name.
Name
address
Type
object: mandatory
Description
Address details.
Name
Street
Type
string: mandatory (limit: 150 chars)
Description
Street name, or NA if unavailable.
Name
ZipCode
Type
string: mandatory (limit: 10 chars)
Description
ZIP code.
Name
City
Type
string: mandatory (limit: 50 chars)
Description
City name.
Name
Country
Type
string: ISO 3166-1 alpha-2
Description
Country (e.g., PL for Poland).
Name
Identifiers
Type
array: mandatory
Description
List of public identifiers.
Name
Scheme
Type
string: mandatory
Description
Identifier scheme, e.g., PL:NIP.
Name
ID
Type
string: mandatory (limit: 50 chars)
Description
Identifier value.
Name
InvoiceLines
Type
array: mandatory
Description
Line items.
Name
Description
Type
string: mandatory (limit: 300 chars)
Description
Description of goods/services.
Name
PriceAmount
Type
number: mandatory
Description
Amount excluding VAT.
Name
TaxType
Type
object: mandatory
Description
Tax details.
Name
TaxRate
Type
number: mandatory
Description
VAT percentage.
Name
TaxType
Type
enum: mandatory
Description
Tax category, e.g., standard, reduced.
Name
TaxCountry
Type
string: ISO 3166-1 alpha-2
Description
Tax country (PL for Poland).
Name
TotalIncludingVat
Type
number: mandatory
Description
Total invoice amount, including VAT.

Sample Request

POST

/pl/einvoice/generate/invoice

curl --url https://sandbox-api.flick.network/pl/einvoice/generate/invoice \
  --header 'x-flick-auth-key: {token}' \
  --header 'supplier_uuid: {supplier_uuid}' \
  --header 'transport_mode: peppol' \
  --header 'Content-Type: application/json' \
  --data '{
    "ID": "INV-11",
    "DocumentType": "Invoice",
    "IssueDate": "2024-12-01",
    "DocumentCurrencyCode": "PLN",
    "CustomerParty": {
      "RegisteredName": "Test Inc.",
      "address": {
        "Street": "Street Name 987",
        "ZipCode": "9999AA",
        "City": "City Test",
        "Country": "PL"
      },
      "Identifiers": [
        {
          "Scheme": "PL:NIP",
          "ID": "1234563218"
        }
      ]
    },
    "InvoiceLines": [
      {
        "Description": "Test Item",
        "InvoicedQuantity": 2,
        "PriceAmount": 100,
        "TaxType": {
          "TaxRate": 19,
          "TaxType": "standard",
          "TaxCountry": "PL"
        }
      }
    ],
    "TotalIncludingVat": 238.00
  }'

Sample Response

200

Success

{
  "status": "success",
  "data": {
    "DocumentID": "52d08f40-a2a0-450b-857f-2e1dd865064c",
    "Status": "Submitted"
  }
}

GET/pl/einvoice/status/{document_id}

Get Invoice Status

Retrieve the current status of an invoice using the document_id returned when the invoice was generated.

Request Parameters

Name
document_id
Type
string: mandatory
Description
Unique identifier of the invoice document.

Sample Request

GET

/pl/einvoice/status/{document_id}

curl --url https://sandbox-api.flick.network/pl/einvoice/status/{document_id} \
  --header 'x-flick-auth-key: {token}'

Sample Response

200

Success

{
  "status": "success",
  "data": {
    "DocumentID": "52d08f40-a2a0-450b-857f-2e1dd865064c",
    "Status": "Submitted"
  }
}

GET/pl/einvoice/retrieve/{document_id}

Retrieve an Invoice

Fetch the full details of a previously submitted invoice using its document_id.

Request Parameters

Name
document_id
Type
string: mandatory
Description
Unique identifier of the invoice document.

Sample Request

GET

/pl/einvoice/retrieve/{document_id}

curl --url https://sandbox-api.flick.network/pl/einvoice/retrieve/{document_id} \
  --header 'x-flick-auth-key: {token}'

Sample Response

200

Success

{
  "status": "success",
  "data": {
    "ID": "INV-11",
    "IssueDate": "2024-12-01",
    "TotalIncludingVat": 238.00,
    "CustomerParty": {
      "RegisteredName": "Test Inc.",
      "address": {
        "Street": "Street Name 987",
        "City": "City Test",
        "Country": "PL"
      }
    }
  }
}

POST/pl/einvoice/access-code/send

Send Access Code to Recipient Email

This endpoint sends an access code to the recipient's email to allow them to retrieve the invoice securely.

Request Body

Name
document_id
Type
string: mandatory
Description
Unique identifier of the invoice document.
Name
recipient_email
Type
string: mandatory
Description
Email address of the recipient.

Sample Request

POST

/pl/einvoice/access-code/send

curl --url https://sandbox-api.flick.network/pl/einvoice/access-code/send \
  --header 'x-flick-auth-key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document_id": "52d08f40-a2a0-450b-857f-2e1dd865064c",
    "recipient_email": "recipient@example.com"
  }'

Sample Response

200

Success

{
  "status": "success",
  "message": "Access code sent successfully."
}