Polish Invoicing API

OpenAPI Definition:
Download

Getting started

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

A-Cube API PL helps you handling the interaction with KSeF (Krajowy System eFaktur) 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 obtain KSeF Authorization Token.

This is the process to create and send a new invoice explained in 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(2) XML format and sent to the KSeF
  5. Every notification from 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
Copy
Copied
{
    "email":    "your@email.com",
    "password": "your password"
}

If the login went fine you will receive a response with

Copy
Copied
{
    "token": "a very long encrypted token"
}
The token you receive is a JWT token that lasts 24 hours. The token is composed by 3 parts, each part is delimited by a dot (.) char. Exploding the token by . and doing a base64 decode of the second part you will obtain some useful information. Example
Copy
Copied
{"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:

Copy
Copied
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. Additionally, for an invoice there is special reference number that is assigned when Invoice is sent to KSeF.

Webhooks

All the messages sent to your endpoint are sent with a POST request. We manage sending 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