Passa al contenuto principale

API V2 notes

This page contains some notes and clarifications not included in the API documentation.

V1 -> V2​

If you are a customer with a V1 account, your organizations and API keys are still valid for V2. You do not need to change anything!

Essential URLs​

fiskaly management API: https://dashboard.fiskaly.com

fiskaly SIGN DE API V2:

https://kassensichv-middleware.fiskaly.com (Middleware)

https://kassensichv.fiskaly.com (Backend)

fiskaly DSFinV-K API: https://dsfinvk.fiskaly.com

Client access​

The API version 2 introduces smaller changes in the way clients communicate to the service. Communication is no longer directly to the backend, but to the fiskaly Middleware service: https://kassensichv-middleware.fiskaly.com/.

Integrators are recommended to use any HTTP client of their choice.

The fiskaly Backend https://kassensichv.fiskaly.com/ can still be used for retrieve and list endpoints, for the creation of a TSS, and for exports. In detail, the following operations are still accessible via the fiskaly Backend:

  • Authenticate API without base_url (Note that it is not possible to use a session created via the fiskaly Backend in the fiskaly Middleware, it is however possible to use a session created via the fiskaly Middleware in the fiskaly Backend.)
  • Create TSS
  • Retrieve TSS
  • List TSS
  • Retrieve metadata of a TSS
  • Update metadata of a TSS
  • Retrieve a client
  • List all clients
  • List clients of a TSS
  • List transactions of a client
  • Retrieve metadata of a client
  • Update metadata of a client
  • List all transactions
  • List transactions of a TSS
  • Retrieve a transaction
  • Retrieve a signed transaction log
  • Retrieve metadata of a transaction
  • Update metadata of a transaction
  • All export operations

Latest authentication changes​

There are two possible authentication methods:

  • ApiKeyAuthentication
  • RefreshTokenAuthentication

Each accepts an optional base_url. If not set, a default value is used.

PUK and PIN codes​

When a TSS is created, the response should be a 200 status code and a PUK.

The PUK is presented only once, when creating a TSS. The client must store it securely in case it is needed in future.

Note the difference between a PIN and PUK: a PIN is used for Admin Authentication. It is blocked after a after five unsuccessful authentication attempts. The PUK is used for unblocking the PIN.

Disabling the TSS​

Setting the state of a TSS to DISABLED results in taking its SMAERS component out of operation permanently. This action is irreversible. No new transactions data can be processed in this state, but the retrieve, list, and export operations remain fully functional.