Skip to content

Overview

fiskaly Logo
API docs by Redocly

fiskaly eReceipt API (1.12.3)

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 consumers instead of traditional paper based receipts.

Versioning

The fiskaly eReceipt API 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.

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 API associates a unique identifier with each request. You will find this request identifier in the response headers, under X-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.

Changelog

  • 1.12.3 (2024-06-10)

    • Extended VAT rate percentage up to 4 decimals.

  • 1.12.2 (2024-03-05)

    • Extended enum options for type field in transaction_details.

  • 1.12.1 (2023-09-21)

    • Extended CustomMediaContent schema with media_link property.

  • 1.12.0 (2023-08-30)

    • Extended receipt schema payment_types with transaction_details property.

  • 1.11.1 (2023-07-27)

    • Extended support for custom section position property by adding ISSUING_INFORMATION, HOSPITALITY, FOOTER.

  • 1.11.0 (2023-07-18)

    • Extended support for a subset of HTML entities within TEXT type Custom Sections

  • 1.10.0 (2023-06-28)

    • Added new endpoint for dictionary.
    • Updated RetrieveReceiptResponse and ListReceiptsResponse with dictionary

  • 1.9.0 (2023-06-13)

    • Extended support specific encoding for custom_elements with barcode. Newly supported are these encoding formats:
      • CODE93
      • INTERLEAVED2OF5
    • Extended seller information by adding phone
    • Extended head information by adding store_number, cashier_name and cash_register_number

  • 1.8.0 (2023-05-19)

    • Introduced Add Configuration Custom Section route to configuration endpoint.

  • 1.7.5 (2023-04-25)

    • Introduced Custom Section endpoints.

  • 1.7.4 (2023-04-24)

    • Introduced UploadMedia endpoint.

  • 1.7.3 (2023-04-05)

    • Allowed additional properties in receipt schema.

  • 1.7.2 (2023-03-23)

    • Removal of default values for Numeric properties. AdditionalProperties are now only allowed in security related properties.

  • 1.7.1 (2023-02-16)

    • Introduced CustomMediaContent object in CustomElement.

  • 1.7.0 (2023-02-15)

    • Update to TseSecurity legal_text property, it is now an array of strings instead of an array with a single possible enum value.

  • 1.6.2 (2023-01-30)

    • Introduced change property on receipt for cash transactions.

  • 1.6.1 (2023-01-09)

    • Introduced full_amount_incl_vat_before_discount and total_discount_value properties on receipt.

  • 1.6.0 (2022-12-15)

    • Introduced createOrUpdateHospitalityReceiptPublic and retrieveHospitalityReceiptPublic endpoints for updating hospitality information of a public receipt.

  • 1.5.2

    • Add support for spanish, es, in receipt schema and configuration.

  • 1.5.1 (2022-12-01)

    • Support specific encoding for custom_elements with barcode Currently supported are these encoding formats:
      • CODE128
      • EAN13
      • UPC
      • EAN8
      • EAN5
      • EAN2
      • CODE39
      • ITF14
      • MSI
      • PHARMACODE
      • CODEBAR

  • 1.5.0 (2022-11-10)

    • Introduced optional full_amount for line items

  • 1.4.0 (2022-10-20)

    • Introduced addLanguageConfiguration endpoints to add or update the receipt default language

  • 1.3.0 (2022-10-10)

    • Introduced createStaticLink static link creation method

  • 1.2.0 (2022-09-29)

    • Introduced discount property on line items
    • Introduced discount property on receipt
    • Introduced sort_order property for line items and discounts
    • Introduced display_name, remaining_balance and payment_identifier for payment_types
    • Introduced sort_order property to payment_types for display ordering

  • 1.1.0 (2022-09-14)

    • Introduced language property in schema.ekabs_v0 to support different language options
    • Introduced misc.conformity_text for compliance in France
    • masked_card_number can now be a string of up to 19 characters containing digits and the * symbol
    • Fixed a bug that incorrectly complaint about a schema violation when providing multiple payment types along with a masked_card_number
    • Improved error messages for receipt creation and PDF retrieval

Processes

Overall Flow

Issuing an electronic receipt

To issue a receipt, simply use the create receipt operation to get a public link for the consumer to access. This public link can be provided as either a QR code or whatever other mechanism is available to transfer it to the consumer 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 consumer
  • 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 consumer.

Configuration

The configuration resource keeps the history of updates to the visual state of the receipt. It is a revision-safe resource. Every time, something is changed in the configuration, a new configuration revision is created. For example, when you upload a new logo, the configuration is updated and the revision counter is incremented.

Errors and Status Codes

The fiskaly eReceipt API 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_REQUEST_INVALID

    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.

  • E_INVALID_FILTER_VALUES

    Your request has invalid values in the query params. Expected values are ASC, DESC for the order param and 0 - 100 for limit.

  • E_RECEIPT_ID_INVALID

    The receipt_id from the request params is not a valid UUID. Retry the request with a receipt_id that complies to the uuidv4 (https://datatracker.ietf.org/doc/html/rfc4122).

  • E_MASKED_CARD_NUMBER_NON_CARD_PAYMENT

    You cannot provide masked_card_number when payment type is not CARD. Provide a different payment type or repeat the request without the masked_card_number.

  • E_REVISION_ID_MISSING

    The request is missing the revision.

  • E_INVALID_LIMIT_FILTER

    The request contains a invalid definition of the limit filter. Possibly out of value range.

401 Unauthorized
  • E_AUTHENTICATION

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

  • E_TOKEN_MISSING

    The JWT token is not present in the request. Retry the request with a valid JWT token.

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_NOT_FOUND

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

  • E_CONFIGURATION_NOT_FOUND

    No Configuration has been found for the receipt_id you used in the request. Run the Retrieve Current Configuration endpoint and check a Configuration exists for your receipts. If it doesn't exist, run the Add Logo endpoint with your Logo image. This will create a new Configuration resource, and the provided Logo will be used to render new receipts.

  • E_LOGO_NOT_FOUND

    No Logo has been found for the provided receipt_id you used in the request. Run the Retrieve Current Configuration endpoint and check a Configuration.Logo exists for your receipts. If it doesn't exist, run the Add Logo endpoint with your Logo image. This will create a new Configuration resource, and the provided Logo will be used to render new receipts.

  • E_PUBLIC_ACCESS_EXPIRED

    The public access of the receipt has expired.

  • E_ROUTE_NOT_FOUND

    The resource requested is not defined. Check your request if the path is correct.

413 Request Entity to large
  • E_LOGO_BODY_LIMIT_EXCEEDED The size of the uploaded logo has exceeded the allowed size of 2 Mb.

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

Quick Start

For a quick first demo, you may use Postman. We prepared a Postman collection that allows you to step through the most important functions of this API.

  1. Download the Postman application.

  2. Create an API key and secret via the fiskaly dashboard: api key and secret

  3. Insert your API key and secret to get your personalized Postman environment:

  1. Download the Postman collection.

  2. Start Postman and select Upload Files from the Import dialog:

    File > Import (Ctrl+O)

    postman upload files

  3. Select the collection and environment files that you downloaded:

    postman select files

  4. The Postman screen should now look like this:

    postman screen

  5. Select the fiskaly receipt environment:

    postman select environment

  6. Download the test logo

  7. Select the downloaded test logo in the Add Logo route:

postman select environment

  1. Run the demo:

postman run demo

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_at": 1577833200,
  • "access_token_expires_in": 0,
  • "refresh_token": "string",
  • "refresh_token_expires_at": 1577833200,
  • "refresh_token_expires_in": 0
}

Receipts

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.

Authorizations:
JWT
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
{
  • "_env": "TEST",
  • "_type": "RECEIPT_LIST",
  • "_version": "1.0.0",
  • "count": 9007199254740991,
  • "data": [
    ]
}

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.

Authorizations:
JWT
path Parameters
receipt_id
required
string
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Identifies a Receipt.

Responses

Response samples

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

Create a receipt

This endpoint creates a receipt.

Authorizations:
JWT
path Parameters
receipt_id
required
string
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
{
  • "_env": "TEST",
  • "_id": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
  • "_type": "RECEIPT",
  • "_version": "1.0.0",
  • "assets": {},
  • "public_link": {
    },
  • "schema": {
    },
  • "user_association": {
    }
}

Configuration

Retrieve current Configuration

This endpoint retrieves the current Configuration.

Authorizations:
JWT

Responses

Response samples

Content type
application/json
{
  • "_env": "TEST",
  • "_id": {
    },
  • "_type": "CONFIGURATION",
  • "_version": "1.0.0",
  • "custom_sections": [
    ],
  • "dictionary": [
    ],
  • "language": "de",
  • "logo": {},
  • "revision": 1,
  • "valid_from": 1577833200
}

Set Configuration custom sections

This endpoint sets the default Custom Sections for a configuration.

Authorizations:
JWT
Request Body schema: application/json
Array
custom_section_id
required
string <uuid> [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...

Identifies the custom section.

orientation
required
string
Enum: "BEFORE" "AFTER"

Defines if the custom element will be rendered before or after the given position. If more than one element is defined on this position and orientation, the sort order will be used (if provided).

position
required
string (Position)
Enum: "LINES" "VAT_AMOUNTS" "PAYMENT_TYPES" "HEAD" "MISC" "SECURITY" "ISSUING_INFORMATION" "HOSPITALITY" "FOOTER"

Defines where the custom element will be rendered. For more information, visit Which sections exist on a digital receipt by fiskaly?

sort_order
integer

Optionally, defines the sort order of elements.

valid_from
integer (Timestamp) [ 0 .. 9007199254740991 ]

A timestamp / point in time measured in seconds since the Unix epoch.

valid_until
integer (Timestamp) [ 0 .. 9007199254740991 ]

A timestamp / point in time measured in seconds since the Unix epoch.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "_env": "TEST",
  • "_id": {
    },
  • "_type": "CONFIGURATION",
  • "_version": "1.0.0",
  • "custom_sections": [
    ],
  • "dictionary": [
    ],
  • "language": "de",
  • "logo": {},
  • "revision": 1,
  • "valid_from": 1577833200
}

GetDefaultDictionary

Endpoint will return default dictionary object for all supported languages

Authorizations:
JWT

Responses

Response samples

Content type
application/json
{
  • "dictionary": [
    ]
}

Update labels on the receipt

This endpoint is used to update labels on the receipt.

Authorizations:
JWT
Request Body schema: application/json

Request body will accept language and labels defined by the schema.

language
required
string (Language)
Enum: "de" "fr" "en" "es" "it"

Language defines model for Language

required
object (ReceiptObject)

Responses

Request samples

Content type
application/json
{
  • "language": "de",
  • "receipt": {
    }
}

Response samples

Content type
application/json
{
  • "_env": "TEST",
  • "_id": {
    },
  • "_type": "CONFIGURATION",
  • "_version": "1.0.0",
  • "custom_sections": [
    ],
  • "dictionary": [
    ],
  • "language": "de",
  • "logo": {},
  • "revision": 1,
  • "valid_from": 1577833200
}

Add or Update language configuration

This endpoint creates a new revision of the Configuration with the provided Language.

Authorizations:
JWT
Request Body schema: application/json

Selected language

language
required
string (Language)
Enum: "de" "fr" "en" "es" "it"

Language defines model for Language

Responses

Request samples

Content type
application/json
{
  • "language": "de"
}

Response samples

Content type
application/json
{
  • "_env": "TEST",
  • "_id": {
    },
  • "_type": "CONFIGURATION",
  • "_version": "1.0.0",
  • "custom_sections": [
    ],
  • "dictionary": [
    ],
  • "language": "de",
  • "logo": {},
  • "revision": 1,
  • "valid_from": 1577833200
}

Retrieve all revisions of the Configuration

This endpoint retrieves all revisions of the Configuration.

Authorizations:
JWT
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
{
  • "_env": "TEST",
  • "_type": "CONFIGURATION_LIST",
  • "_version": "1.0.0",
  • "count": 9007199254740991,
  • "data": [
    ]
}

Retrieve Configuration by revision

This endpoint retrieves a Configuration with the provided revision number.

Authorizations:
JWT
path Parameters
revision
required
string

Revision number

Responses

Response samples

Content type
application/json
{
  • "_env": "TEST",
  • "_id": {
    },
  • "_type": "CONFIGURATION",
  • "_version": "1.0.0",
  • "custom_sections": [
    ],
  • "dictionary": [
    ],
  • "language": "de",
  • "logo": {},
  • "revision": 1,
  • "valid_from": 1577833200
}

PDF

Retrieve a PDF

This endpoint retrieves a PDF.

Authorizations:
JWT
path Parameters
receipt_id
required
string
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Identifies a Receipt.

Responses

Retrieve Logo from Configuration

This endpoint retrieves a Logo from the given Configuration.

Authorizations:
JWT
path Parameters
revision
required
string

Revision number

Responses

Retrieve a Logo from Receipt

This endpoint retrieves a Logo from the given Receipt.

Authorizations:
JWT
path Parameters
receipt_id
required
string
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Identifies a Receipt.

Responses

Hospitality

Retrieve hospitality receipt information (public)

Retrieve the hospitality information for a given receipt.

path Parameters
env
required
string
Enum: "test" "live"

Environment of the API.

receipt_id
required
string
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Identifies a Receipt.

Responses

Response samples

Content type
application/json
{
  • "created_at": 1577833200,
  • "finalized_at": 1577833200,
  • "modified_at": 1577833200,
  • "schema": {
    }
}

Create or update hospitality receipt information (public)

Update or create the hospitality information for a given receipt.

path Parameters
env
required
string
Enum: "test" "live"

Environment of the API.

receipt_id
required
string
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Identifies a Receipt.

Request Body schema: application/json
finalized_at
integer (Timestamp) [ 0 .. 9007199254740991 ]

A timestamp / point in time measured in seconds since the Unix epoch.

required
object (HospitalitySchema)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "created_at": 1577833200,
  • "finalized_at": 1577833200,
  • "modified_at": 1577833200,
  • "schema": {
    }
}

Media

Upload media.

This endpoint creates a new media of the given type. To add a media, multipart/form-data request is done to upload the raw image data using POST. The raw image is part of the request body. The MIME type of the request body should correspond to the format of your media data.

Authorizations:
JWT
Request Body schema: multipart/form-data

Media type data

alt_text
string

The alt text will be used if image cannot be displayed.

data
required
string <binary>

Media type data blob in binary format. Maximum size is 2mb.

media_type
required
string
Value: "image"

Responses

Response samples

Content type
application/json
{
  • "alt_text": "string",
  • "id": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
  • "mediaType": "image",
  • "media_location": "string"
}

CustomSection

List all custom section

This endpoint retrieves a list of custom sections for the owner.

Authorizations:
JWT

Responses

Response samples

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

Retrieve a customSection

This endpoint retrieves a custom section for the Merchant.

Authorizations:
JWT
path Parameters
custom_section_id
required
string
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Identifies a Custom Section.

Responses

Response samples

Content type
application/json
{
  • "custom_content": {
    },
  • "custom_type": "IMAGE",
  • "id": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
  • "label": "string"
}

Create or update custom section.

This endpoint creates or update a new custom section of the given content type.

Authorizations:
JWT
path Parameters
custom_section_id
required
string
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Identifies a custom section.

Request Body schema: application/json
required
object (BaseCustomElement)

Defines a basic custom element with its content and content alignment.

custom_type
required
string
Enum: "IMAGE" "BAR_CODE" "QR_CODE" "TEXT"
label
string

Responses

Request samples

Content type
application/json
{
  • "custom_content": {
    },
  • "custom_type": "IMAGE",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "custom_content": {
    },
  • "custom_type": "IMAGE",
  • "id": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
  • "label": "string"
}

Was this page helpful?