Skip to main content
Download OpenAPI

Polish Invoicing API

This is a set of APIs meant for managing electronic invoicing in Poland.

A-Cube API PL helps you handle the interaction with KSeF (Krajowy System e-Faktur) through simple REST APIs.

When you get onboard the A-CUBE API Platform, you will receive:

  • username and password for the authentication

You will also need to register a Legal Entity in A-Cube API PL and get KSeF Authorization Token.

This is the process to create and send a new invoice explained in a few steps:

  1. Login into the platform to obtain a JWT token
  2. Create an invoice payload in JSON or XML format
  3. The invoice payload is sent to POST /invoices
  4. The invoice payload is validated, translated into FA(3) XML format and sent to the KSeF
  5. Every notification from the KSeF will be dispatched in real time to the configured endpoints.

Environments​

  • sandbox is the environment where you can test the entire platform without paying at any time; the communication with KSeF is simulated. The base URL is https://pl-sandbox.api.acubeapi.com
  • production is the environment where the communication with KSeF is real; you can't send an invoice to test. The base URL is https://pl.api.acubeapi.com

We support the following TLS protocols: TLSv1_2016, TLSv1.1_2016, TLSv1.2_2018

Authentication​

To obtain a JWT token, send a POST https://common.api.acubeapi.com/login (or POST https://common-sandbox.api.acubeapi.com/login in case your working on the sandbox environment) specifying the HTTP header Content-Type: application/json with the following payload

{
    "email":    "your@email.com",
    "password": "your password"
}

If the login went fine, you will receive a response with

{
    "token": "a very long encrypted token"
}

The token you receive is a JWT token that lasts 24 hours. The token is composed by three parts, each part is delimited by a dot (.) char. Exploding the token by . and doing a base64 decoded of the second part you will collect some useful information. Example

{
  "iat":"<issue timestamp>",
  "exp":"<expire timestamp>",
  "roles":{"<project name>": ["ROLE_WRITER"]},
  "username":"<your email>",
  "uid":"<your identifier>"
}

You can ask for a token once in 24 hours.

The token must be set as Bearer into the Authorization header. Example:

curl -X GET
https://pl-sandbox.api.acubeapi.com/legal-entities
-H 'Accept: application/json'
-H 'Authorization: Bearer <here the received token>'

Invoice UUID​

Every invoice in the platform is identified by a UUID. This key is received for both created and received invoices.

Webhooks​

All the messages sent to your endpoint are sent with a POST request. We manage to send the messages to your endpoints with a queue: if your endpoint fails (we don't get a 200 response) then we will retry every 15 minutes for 8 hours. Find out more here

Last updated on