Skip to content

Authenticate API

fiskaly Logo
API docs by Redocly

fiskaly eReceipt backend (1.0.0)

Download OpenAPI specification:

fiskaly GmbH: info@fiskaly.com URL: https://fiskaly.com

Imprint: fiskaly.com/impressum | Privacy Policy: fiskaly.com/datenschutz

Introduction

The eReceipt API allows merchants to issue electronic receipts for end users instead of traditional paper based receipts.

Versioning

The fiskaly eReceipt backend follows Semantic Versioning.

The version number has a pattern of MAJOR.MINOR.PATCH. We increment the

  • MAJOR version when we make incompatible API changes,
  • MINOR version when we add functionality in a backwards-compatible manner, and
  • PATCH version when we make backwards-compatible bug fixes.

The current MAJOR version 1 is reflected in the API's base URL: /api/v1.

Idempotent Requests

The fiskaly eReceipt backend is idempotent. Idempotence means you can send the same request several times safely. The result will be the same as if you have sent it only once.

For example, if you request to sign a Receipt but don't receive a response, you can send the request again with the same request body. The receipt is guaranteed to be signed only once.

UUIDv4

This API uses UUIDv4. Some requests create new resources. To run such requests, generate a random UUIDv4. Then pass the UUIDv4 in the request body. This UUIDv4 will be assigned to the newly created resource.

A good way to generate a UUIDv4 is to use a library in your programming language of choice (like this) or an online generator (like this). A UUIDv4 created this way will be random and unique throughout the system.

Request IDs

The fiskaly eReceipt backend associates a unique identifier with each request. You will find this request identifier in the response headers, under request-id. If you need help with a request you have issued, please provide the request identifier. We will find your request and help you faster.

Metadata

Most resources in the API (e.g. Cash Registers) have a metadata property. You can store any additional information in the metadata.

You can specify up to 20 key-value pairs in the metadata object. A key can be up to 40 characters long. A value can be up to 500 characters long.

Changes

MINOR and PATCH changes

Processes

Issuing an electronic receipt

To issue a receipt, simply use the create receipt operation to get a public link for the end user to access. This public link can be provided as either a QR code or whatever other mechanism is available to transfer it to the end user at the Point of Sale.

Resources

Receipt

The receipt is the core resource of the eReceipt API. It is represented in a schema closely resembling the DFKA EKaBS standard schema.

The receipt resource consists of the following data:

  • schema: the receipt data modelled as one of the supported schemas (currently only EKaBS)
  • public_link: link that can be provided to the end user
  • assets: references to static assets (e.g. PDF). Note that those are generated asynchronously and therefore might not be instantly accessible in some cases.
  • user_association: a set of properties that can be used to associate a receipt with an end user.

Errors and Status Codes

The fiskaly eReceipt backend uses standard HTTP status codes to indicate the success or failure of requests:

Status 2xx

Status codes in the 200-299 range indicate success.

Status 4xx

Status codes in the 400-499 range indicate errors that have been caused by the requesting application (e.g., a malformed request body has been sent).
Retrying such requests with the same request body is pointless and will result in the same status code again. Some 4xx errors can be handled programmatically. The error response is in JSON format and is structured like this:

{
"status_code": 400,
"error": "Bad Request",
"code": "E_SOME_ERROR",
"message": "Something bad happened"
}

The response will contain an error code or other information that reveals the reason of the error. Change the request accordingly before retrying. Below you can find the most frequent errors and how to fix them.

How to handle 4xx errors

400 Bad Request
  • E_FAILED_SCHEMA_VALIDATION Your request doesn't comply with the defined schema. Fix you request body and parameters according to the error message and run the endpoint again.
401 Unauthorized
  • E_AUTHENTICATION

    The JWT token authentication failed for your request. The error message explains what went wrong. Run the Authenticate API enpoint to get a new token and retry your original request.

  • E_PUBLIC_ACCESS_EXPIRED

    The public access to this Receipt has expired. After the public link to the Receipt has expired, it is no longer possible to access it with the Retrieve receipt (public) endpoint.

404 Not Found
  • E_RECEIPT_NOT_FOUND

    No Receipt has been found for the receipt_id you used in the request. Run the List all receipts endpoint and check that your Receipt exists in the returned list.

  • E_PDF_LINK_MISSING

    The PDF for the Receipt you are trying to access hasn't been created yet. Repeat the request later.

Status 5xx

Status codes in the 500-599 range indicate errors on the server side. These errors are temporary. You can safely retry (see Idempotent Requests) the same request after a delay. We recommend an exponential backoff for your retry logic. Otherwise you might run into a 429 (Too Many Requests) error.

Known issues

Authentication

Authenticate API

To access our API, you need to have a valid JWT token. This endpoint creates the token with your api_key and api_secret. If you don't have an api_key, you can create one via the fiskaly dashboard. The api_secret will be generated for you after you create the api_key. The token must be sent with every following request in the Authorization header field using the Bearer authentication scheme. See details here.

Request Body schema: application/json
One of
api_key
required
string (ApiKeyKey)

Key of the API Key and Secret.

api_secret
required
string (ApiKeySecret)

Secret of the API Key and Secret.

Responses

Request samples

Content type
application/json
Example
{
  • "api_key": "string",
  • "api_secret": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "access_token_claims": {
    },
  • "access_token_expires_in": 0,
  • "access_token_expires_at": 1577833200,
  • "refresh_token": "string",
  • "refresh_token_expires_in": 0,
  • "refresh_token_expires_at": 1577833200
}

Receipts

Create a receipt

This endpoint creates a receipt.

Authorizations:
JWT
path Parameters
receipt_id
required
string <uuid> [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Identifies a Receipt.

Request Body schema: application/json
required
object (SchemaObject)
object (UserAssociation)

Responses

Request samples

Content type
application/json
{
  • "schema": {
    },
  • "user_association": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
  • "_type": "RECEIPT",
  • "_env": "TEST",
  • "_version": "1.0.0",
  • "schema": {
    },
  • "user_association": {
    },
  • "public_link": {
    },
  • "assets": {
    }
}

Retrieve a receipt

This endpoint retrieves a receipt for the Merchant. It will return the receipt even after the public access to the receipt has expired.

path Parameters
receipt_id
required
string <uuid> [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Identifies a Receipt.

Responses

Response samples

Content type
application/json
{
  • "_id": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
  • "_type": "RECEIPT",
  • "_version": "1.0.0",
  • "_env": "TEST",
  • "user_association": {
    },
  • "public_link": {
    },
  • "schema": {
    },
  • "assets": {
    }
}

Retrieve a receipt (public)

This endpoint retrieves the publicly available receipt resource. It can be called by the point of sale to display the receipt to the end user.

path Parameters
receipt_id
required
string <uuid> [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Identifies a Receipt.

Responses

Response samples

Content type
application/json
{
  • "_id": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
  • "_type": "RECEIPT",
  • "_version": "1.0.0",
  • "schema": {
    },
  • "assets": {
    }
}

List all receipts

This endpoint retrieves a list of receipts for the Merchant. It will include a receipt into the result even after its public access has expired.

query Parameters
order
string
Default: "ASC"
Enum: "ASC" "DESC"

Determines the sorting order.

limit
integer <= 100
Default: 100

Limits the number of returned results.

offset
integer
Default: 0

Skips the specified number of results from the result set.

Responses

Response samples

Content type
application/json
{
  • "_type": "RECEIPT_LIST",
  • "_env": "TEST",
  • "_version": "1.0.0",
  • "count": 9007199254740991,
  • "data": [
    ]
}

Was this page helpful?