Skip to content

Overview

Version
fiskaly Logo
API docs by Redocly

fiskaly SIGN AT (Unified API) (2026-06-01)

Download OpenAPI specification:

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

Imprint: fiskaly.com/impressum
Privacy Policy: fiskaly.com/privacy-policy
Service Details: workspace.fiskaly.com/pm-hub/service-descriptions/sign-at/
Developer Guide: workspace.fiskaly.com/sign-at/integration-guide/

Introduction

The fiskaly API is a RESTful, cross-country solution designed to support compliance with the relevant legislation.

The fiskaly API is a platform-independent and software-only solution. Since this is a cloud-based API, the only requirement to integrate and use this fiskaly API is a stable Internet connection. The API ...

  • has resource-oriented URLs,

  • accepts JSON-encoded request bodies,

  • returns JSON-encoded responses,

  • uses standard HTTP status codes and verbs, and

  • is designed to be easily integrated into any system.

Austria specifications

This API documentation specifically covers the Austrian module, SIGN AT (Unified API), which ensures compliance with Austrian fiscalisation legislation for the signing and registration of cash register transactions.

SIGN AT (Unified API) is a cloud-based fiscalisation API compliant with the Austrian Registrierkassensicherheitsverordnung (RKSV). It enables PoS, ERP, and cash register systems to meet Austrian fiscal requirements through a single integration. The service handles the full compliance flow:

  • Registration of cash registers with FinanzOnline (the Austrian tax authority portal)
  • Digital signing of receipts via a cloud-based security module (Signaturerstellungseinheit, SEE)
  • Support for DEFECTIVE and OUT_OF_ORDER system states as required by RKSV
  • Test and live environments for development and production use

SIGN AT (Unified API) provides a test environment for integration and testing purposes, as well as a dedicated live environment for the signing and registration of fiscally relevant transactions. Transactions created in the test environment are not legally valid and are not communicated to FinanzOnline production systems. To access the live environment, please contact our sales team.

Background

SIGN AT (Unified API) implements the legal requirements and technical specifications for fiscalisation compliance of PoS, ERP, and cash register software in Austria.

SIGN AT (Unified API) is based on the following Austrian regulation:

  • Registrierkassensicherheitsverordnung (RKSV), which defines the technical security requirements for electronic cash registers in Austria, including the obligation to use a security module (Signaturerstellungseinheit) for digital signing of each receipt and the chaining of receipts via cryptographic signatures.
  • Bundesabgabenordnung (BAO) § 131b, which establishes the cash register obligation (Registrierkassenpflicht) for businesses exceeding the relevant turnover thresholds, requiring the use of an electronic cash register with a security module.
  • Erlass des BMF zur Einzelaufzeichnungs-, Registrierkassen- und Belegerteilungspflicht, which provides detailed guidance from the Austrian Federal Ministry of Finance on the obligations for individual transaction recording, cash register usage, and receipt issuance.

Service

Our fiskaly API service offers a compliance-as-a-service solution implementation that records business transaction, technical events, and taxpayer interactions in an inalterable and cryptographically secure way.

Austria specifications

The fiskaly SIGN AT (Unified API) service provides a fully compliant implementation for the signing and registration of cash register transactions in Austria. Each receipt issued through SIGN AT (Unified API) is digitally signed using a cloud-based security module (Signaturerstellungseinheit), cryptographically chained to the previous receipt, and registered with FinanzOnline. The service supports all required system states including DEFECTIVE and OUT_OF_ORDER as mandated by the RKSV.

Guides

To ensure a smooth implementation of our fiskaly API, we highly recommend that you first have a look at our integration guide where you will find an explanation of how to create your organizational structure and API keys, as well as a first overview of our fiskaly API endpoints.

Changes

The up-to-date information below is organized in a change log format.

2026-06-01 Multi-Country Update

  • Portuguese fiscalization enabled for productive use
  • initial Austrian fiscalization support via Unified API (integration ready)
  • initial Swedish fiscalization support — integration-ready implementation (pending activation)
  • initial e-invoicing support for Italy (integration ready)

Versioning

Our fiskaly API follows Calendar (Date-based) Versioning. The version number has a pattern of YYYY-MM-DD whereas the YYYY stands for the year, MM stands for the month, and DD stands for the day.

The latest version is: X-Api-Version: 2026-06-01.

Version SIGN E-INVOICE
2026-06-01 IT 🇮🇹, FR 🇫🇷, PT 🇵🇹, AT 🇦🇹, SE 🇸🇪 IT 🇮🇹, BE 🇧🇪, DE 🇩🇪
2026-05-04 IT 🇮🇹, FR 🇫🇷, PT 🇵🇹 BE 🇧🇪, DE 🇩🇪
2026-02-03 IT 🇮🇹, FR 🇫🇷 BE 🇧🇪, DE 🇩🇪
2025-08-12 IT 🇮🇹, FR 🇫🇷 —
2024-10-31 IT 🇮🇹 —

Idempotency

Idempotency ensures that repeated identical requests produce the same result, even if they are retried due to network issues, timeouts, or other transient problems. This idempotency behavior prevents duplicate resource creation or unintended side effects in APIs that accept POST (creation) or PATCH (alteration) requests.

The X-Idempotency-Key HTTP header in this API follows the principles of the Internet Engineering Task Force (IETF) idempotency specification and plays a vital role in implementing idempotent requests. API clients use this header to uniquely identify requests, enabling the API to track and manage their outcomes across retries.

The value of the HTTP header is a Universally Unique Identifier (UUID) -- version 3 or version 4 -- key provided by the client for each idempotent request. This key ensures that retries of the same request are recognized by the server.

This key is required for all POST and PATCH requests. This key is ignored for all other HTTP request methods like GET, PUT, DELETE etc. since these are inherently idempotent by HTTP standards.

Exception: The POST /tokens endpoint currently does not react on the provided X-Idempotency-Key HTTP header. This exception will be resolved by upcoming improvements to the API.

The HTTP header format is defined as: X-Idempotency-Key: <key>. The <key> value shall be a valid and randomized UUIDv4 string. Furthermore, this key shall be unique for each logically distinct request.

The API service keeps track of the X-Idempotency-Key (key) and the associated request status, payload, and response (value) in a persistence cache. By default the stored idempotency key-value pairs expire after 24 hours (1 day) after their creation timestamp. If another request reaches the API service and there is already the same X-Idempotency-Key available, where the request method and payload are also equal to the cached value, the API service returns the cached response.

If the API service returns:

  • 422 Unprocessable Entity: Verify that the request headers and payload match exactly between retries. Ensure the idempotency key is not reused for unrelated operations.
  • 409 Conflict: The request is already being processed. Wait before retrying and ensure there are no concurrent retries with the same idempotency key.

With the latest API update on March 18, 2026, a new response header, X-Idempotency-Replayed, has been introduced for all POST and PATCH requests. This header allows integrators to clearly distinguish between retried requests ("true") and newly processed requests ("false"), improving transparency and simplifying debugging.

For more details, please refer to our blog article: Unified API Update: Enhanced Idempotency Handling.

FAQs

For each country and service, a dedicated FAQ page is available, covering the usage and integration of the fiskaly API:

Tokens

In order to access the fiskaly API, a valid JSON Web Token (JWT) is required. The information carried inside the JWT is used for authentication and authorization of every request towards the fiskaly API. API requests without a JWT present will fail with an unauthorized access HTTP error 401.

A Token resource can be created by using the key and secret credentials information of an already existing Subject::API_KEY. The API key secret will be generated from the fiskaly API and provided only in the response of the POST /tokens request.

Each Token resource has its own unique id in form of a UUIDv4, the JWT bearer string, an issued_at timestamp, and an expires_at timestamp. Additionally, the token resource provides the information to which Asset and which Subject the token belongs to.

The JWT bearer string must be sent with every following request in the HTTP Authorization header field using the Bearer authentication scheme.

The fiskaly API processes only https based requests. Plain http based requests are redirected to https by the fiskaly service.

Create a token

This endpoint is used to create a Token resource. Currently, the fiskaly API supports an Subject::API_KEY based Token creation which returns the JWT bearer HTTP authentication string that is valid until a given expires_at timestamp.

Recreations of the new Token resource is required only then if the received JWT bearer string has expired.

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

required
UniversallyUniqueIdentifierV4 (string) or UniversallyUniqueIdentifierV3 (string) (IdempotencyKey)

The idempotency key, see idempotency.

Request Body schema: application/json
required
required
any (TokenCreateContent)

Defines the structure required to create the token.

object (Metadata) <= 20 properties

Attach custom key value data to a resource. Useful for storing additional, structured information. If metadata appears in a response, it reflects the current metadata of the object. You can update metadata via the resource's update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.

Note: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Organizations

Organization resources are used to represent a management structure (organizational hierarchy):

  • ACCOUNT represents your top-level entity. Created when you register on the HUB. Represents the POS provider or a retailer that operates its own PoS system.
  • GROUP an intermediate layer within an Account, used to cluster multiple Organization resources of type UNIT into logical clusters (e.g. one Group per country).
  • UNIT represents an individual legal entity. Each unit corresponds to a specific merchant and has its own taxpayer data and fiscal resources.

List organizations

This endpoint is used to list Organization resources to represent and manage organizational structures.

Authorizations:
JWT
query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

X-Scope-Identifier
string <uuid> (ScopeIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?4[0-9a-f]{3}-?[89a...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

The X-Scope-Identifier header specifies the organization scope in which the request is executed. This ensures that the operation is linked to the correct organization within the organization hierarchy.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Create an organization

This endpoint is used to create Organization resources to represent and manage organizational structures.

Authorizations:
JWT
header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

required
UniversallyUniqueIdentifierV4 (string) or UniversallyUniqueIdentifierV3 (string) (IdempotencyKey)

The idempotency key, see idempotency.

X-Scope-Identifier
string <uuid> (ScopeIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?4[0-9a-f]{3}-?[89a...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

The X-Scope-Identifier header specifies the organization scope in which the request is executed. This ensures that the operation is linked to the correct organization within the organization hierarchy.

Request Body schema: application/json
required
required
any (OrganizationCreateContent)

Defines the structure required to create an Organization.

object (Metadata) <= 20 properties

Attach custom key value data to a resource. Useful for storing additional, structured information. If metadata appears in a response, it reflects the current metadata of the object. You can update metadata via the resource's update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.

Note: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Update an organization

This endpoint is used to update a Organization resource.

Authorizations:
JWT
path Parameters
organization_id
required
string <uuid> (OrganizationIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?4[0-9a-f]{3}-?[89a...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Organization identifier

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

required
UniversallyUniqueIdentifierV4 (string) or UniversallyUniqueIdentifierV3 (string) (IdempotencyKey)

The idempotency key, see idempotency.

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

Defines the structure required to update an Organization.

object (Metadata) <= 20 properties

Attach custom key value data to a resource. Useful for storing additional, structured information. If metadata appears in a response, it reflects the current metadata of the object. You can update metadata via the resource's update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.

Note: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Retrieve an organization

This endpoint is used to retrieve a Organization resource.

Authorizations:
JWT
path Parameters
organization_id
required
string <uuid> (OrganizationIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?4[0-9a-f]{3}-?[89a...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Organization identifier

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

Responses

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Subjects

A Subject represents an authenticated identity with defined access rights.

Currently, the fiskaly API supports Subject resources of type API_KEY (Subject::API_KEY). The support for handling Subject resources of type USER (Subject::USER) is available soon.

The X-Scope-Identifier HTTP header establishes the link between the Subject and the corresponding Asset resource.

List subjects

A Subject represents an authenticated identity with defined access rights.

Currently, the fiskaly API supports Subject resources of type API_KEY (Subject::API_KEY). The support for handling Subject resources of type USER (Subject::USER) is available soon.

The X-Scope-Identifier HTTP header establishes the link between the Subject and the corresponding Asset resource.

Authorizations:
JWT
query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

X-Scope-Identifier
string <uuid> (ScopeIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?4[0-9a-f]{3}-?[89a...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

The X-Scope-Identifier header specifies the organization scope in which the request is executed. This ensures that the operation is linked to the correct organization within the organization hierarchy.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Create a subject

A Subject represents an authenticated identity with defined access rights.

Currently, the fiskaly API supports Subject resources of type API_KEY (Subject::API_KEY). The support for handling Subject resources of type USER (Subject::USER) is available soon.

The X-Scope-Identifier HTTP header establishes the link between the Subject and the corresponding Asset resource.

Authorizations:
JWT
header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

required
UniversallyUniqueIdentifierV4 (string) or UniversallyUniqueIdentifierV3 (string) (IdempotencyKey)

The idempotency key, see idempotency.

X-Scope-Identifier
string <uuid> (ScopeIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?4[0-9a-f]{3}-?[89a...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

The X-Scope-Identifier header specifies the organization scope in which the request is executed. This ensures that the operation is linked to the correct organization within the organization hierarchy.

Request Body schema: application/json
required
required
any (SubjectCreateContent)

Defines the structure required to create the subject.

object (Metadata) <= 20 properties

Attach custom key value data to a resource. Useful for storing additional, structured information. If metadata appears in a response, it reflects the current metadata of the object. You can update metadata via the resource's update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.

Note: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Update a subject

This endpoint is used to update a Subject resource.

Authorizations:
JWT
path Parameters
subject_id
required
string <uuid> (SubjectIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?4[0-9a-f]{3}-?[89a...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Subject identifier

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

required
UniversallyUniqueIdentifierV4 (string) or UniversallyUniqueIdentifierV3 (string) (IdempotencyKey)

The idempotency key, see idempotency.

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

Defines the structure required to update the subject.

object (Metadata) <= 20 properties

Attach custom key value data to a resource. Useful for storing additional, structured information. If metadata appears in a response, it reflects the current metadata of the object. You can update metadata via the resource's update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.

Note: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Retrieve a subject

This endpoint is used to retrieve a Subject resource.

Authorizations:
JWT
path Parameters
subject_id
required
string <uuid> (SubjectIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?4[0-9a-f]{3}-?[89a...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Subject identifier

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

Responses

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Taxpayers

A Taxpayer resource represents a particular Organization::UNIT with the relevant legal taxpayer (taxpayer) data. A legal taxpayer consists of two main parts: taxpayer information and country-specific fiscalization details.

The lifecycle of a Taxpayer resource is depicted in the following state and mode transitions:

List taxpayers

This endpoint is used to list Taxpayer resources.

Authorizations:
JWT
query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Create a taxpayer

This endpoint is used create Taxpayer resources. Currently the fiskaly API supports the creation of legal taxpayers as a COMPANY (for business taxpayers) or as an INDIVIDUAL (for self-employed) which require the details of the taxpayer legal name, legal address, and fiscalization-related data such as the VAT number, tax identification number, and credentials for accessing the Revenue Agency portal.

When a Taxpayer is created, its initial state is automatically set to ACQUIRED. In order to make it fully operational, the state must be updated to COMMISSIONED using the updateTaxpayer endpoint.

Authorizations:
JWT
header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

required
UniversallyUniqueIdentifierV4 (string) or UniversallyUniqueIdentifierV3 (string) (IdempotencyKey)

The idempotency key, see idempotency.

Request Body schema: application/json
required
required
any (TaxpayerCreateContent)

Defines the structure required to create a Taxpayer.

object (Metadata) <= 20 properties

Attach custom key value data to a resource. Useful for storing additional, structured information. If metadata appears in a response, it reflects the current metadata of the object. You can update metadata via the resource's update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.

Note: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.

Responses

Request samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Update a taxpayer

This endpoint is used to update a Taxpayer resource.

Please note that, for certain use cases, particular state and mode transitions are required. Please refer to our Guide for examples.

Authorizations:
JWT
path Parameters
taxpayer_id
required
string <uuid> (TaxpayerIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: 0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

Taxpayer identifier

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

required
UniversallyUniqueIdentifierV4 (string) or UniversallyUniqueIdentifierV3 (string) (IdempotencyKey)

The idempotency key, see idempotency.

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

Defines the structure required to update a Taxpayer.

object (Metadata) <= 20 properties

Attach custom key value data to a resource. Useful for storing additional, structured information. If metadata appears in a response, it reflects the current metadata of the object. You can update metadata via the resource's update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.

Note: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.

Responses

Request samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Retrieve a taxpayer

This endpoint is used to retrieve a Taxpayer resource.

Authorizations:
JWT
path Parameters
taxpayer_id
required
string <uuid> (TaxpayerIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: 0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

Taxpayer identifier

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

Responses

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Locations

A Location resource represents the taxpayers location data.

The lifecycle of a Location resource is depicted in the following state and mode transitions:

List locations

This endpoint is used to list Location resources.

Authorizations:
JWT
query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

taxpayer_id
string <uuid> (TaxpayerIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: taxpayer_id=0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

Taxpayer identifier

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Create a location

This endpoint is used to create Location resources. Currently the fiskaly API supports the creation of BRANCH locations that represent the physical address of the business premises or establishment.

When a Location is created, its initial state is automatically set to ACQUIRED. In order to make it fully operational, the state must be updated to COMMISSIONED using the updateLocation endpoint.

Authorizations:
JWT
header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

required
UniversallyUniqueIdentifierV4 (string) or UniversallyUniqueIdentifierV3 (string) (IdempotencyKey)

The idempotency key, see idempotency.

Request Body schema: application/json
required
required
any (LocationCreateContent)

Defines the structure required to create a location.

object (Metadata) <= 20 properties

Attach custom key value data to a resource. Useful for storing additional, structured information. If metadata appears in a response, it reflects the current metadata of the object. You can update metadata via the resource's update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.

Note: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.

Responses

Request samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Update a location

This endpoint is used to update a Location resource.

Please note that, for certain use cases, particular state and mode transitions are required. Please refer to our Guide for examples.

Authorizations:
JWT
path Parameters
location_id
required
string <uuid> (LocationIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: 0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

Location identifier

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

required
UniversallyUniqueIdentifierV4 (string) or UniversallyUniqueIdentifierV3 (string) (IdempotencyKey)

The idempotency key, see idempotency.

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

Defines the structure required to update a Location

object (Metadata) <= 20 properties

Attach custom key value data to a resource. Useful for storing additional, structured information. If metadata appears in a response, it reflects the current metadata of the object. You can update metadata via the resource's update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.

Note: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.

Responses

Request samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Retrieve a location

This endpoint is used to retrieve a Location resource.

Authorizations:
JWT
path Parameters
location_id
required
string <uuid> (LocationIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: 0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

Location identifier

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

Responses

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Systems

A System represents an Electronic Recording System (ERS), such as a Point of Sale (PoS) or any other system capable of performing business operations.

The lifecycle of a System resource is depicted in the following state and mode transitions:

List systems

This endpoint is used to list System resources.

Authorizations:
JWT
query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

taxpayer_id
string <uuid> (TaxpayerIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: taxpayer_id=0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

Taxpayer identifier

location_id
string <uuid> (LocationIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: location_id=0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

Location identifier

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Create a system

This endpoint is used to create System resources.

Authorizations:
JWT
header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

required
UniversallyUniqueIdentifierV4 (string) or UniversallyUniqueIdentifierV3 (string) (IdempotencyKey)

The idempotency key, see idempotency.

Request Body schema: application/json
required
required
any (SystemCreateContent)

Defines the structure required to create a System.

object (Metadata) <= 20 properties

Attach custom key value data to a resource. Useful for storing additional, structured information. If metadata appears in a response, it reflects the current metadata of the object. You can update metadata via the resource's update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.

Note: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.

Responses

Request samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Update a system

This endpoint is used to update System resources.

Please note that, for certain use cases, particular state and mode transitions are required. Please refer to our Guide for examples.

Authorizations:
JWT
path Parameters
system_id
required
string <uuid> (SystemIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: 0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

System identifier

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

required
UniversallyUniqueIdentifierV4 (string) or UniversallyUniqueIdentifierV3 (string) (IdempotencyKey)

The idempotency key, see idempotency.

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

Defines the structure required to update a System.

object (Metadata) <= 20 properties

Attach custom key value data to a resource. Useful for storing additional, structured information. If metadata appears in a response, it reflects the current metadata of the object. You can update metadata via the resource's update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.

Note: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.

Responses

Request samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Retrieve a system

This endpoint is used to retrieve System resources.

Authorizations:
JWT
path Parameters
system_id
required
string <uuid> (SystemIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: 0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

System identifier

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

Responses

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Records

A Record represents a persisted and signed artifact of any kind interaction with a given System resource that is carried out through the fiskaly API.

List records

This endpoint is used to list Record resources.

Authorizations:
JWT
query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

taxpayer_id
string <uuid> (TaxpayerIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: taxpayer_id=0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

Taxpayer identifier

location_id
string <uuid> (LocationIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: location_id=0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

Location identifier

system_id
string <uuid> (SystemIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: system_id=0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

System identifier

type
Array of strings (SystemRecordType) [ 1 .. 10 ] items unique
Items Enum: "INTENTION::TRANSACTION" "INTENTION::EVENT" "INTENTION::EXPORT" "INTENTION::DUPLICATE" "INTENTION::OPENING" "INTENTION::CLOSING" "INTENTION::UPLOAD" "TRANSACTION::RECEIPT" "TRANSACTION::ABORT" "TRANSACTION::CANCELLATION" "TRANSACTION::CORRECTION" "TRANSACTION::DRAFT_RECEIPT" "TRANSACTION::ENRICHMENT" "TRANSACTION::INVOICE" "TRANSACTION::PROOF_OF_PAYMENT" "TRANSACTION::PRO_FORMA_INVOICE" "CLOSING::DAILY" "CLOSING::MONTHLY" "CLOSING::YEARLY" "EXPORT::RECORDS" "E_INVOICE::TRANSMISSION" "E_INVOICE::RECEPTION" "UPLOAD::PEPPOL_PROOF_OF_OWNERSHIP"

Record type

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Create a record

This endpoint is used to create Record resources.

Every interaction with a System resource requires an initial Record creation of type INTENTION (Record::INTENTION).

Currently the fiskaly API supports only an INTENTION of a TRANSACTION which reflects the interaction with a System resource right at the beginning of a purchase process.

Directly after the payment process, the transaction can be concluded with a subsequent Record creation call providing the TRANSACTION information, containing details of a given business activity which links to the previous Record::INTENTION::TRANSACTION.

Authorizations:
JWT
header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

required
UniversallyUniqueIdentifierV4 (string) or UniversallyUniqueIdentifierV3 (string) (IdempotencyKey)

The idempotency key, see idempotency.

X-Replay-Remaining
string (ReplayRemaining) ^(\d{1,4})$
Example: 1234

Not supported in Austria - Current number of records left (only relevant for offline scenario)

X-Replay-Hash
string (ReplayHash) [ 1 .. 64 ] characters
Example: text example...

Not supported in Austria - The hash stored during offline phase in base64 format (only relevant for offline scenario)

Request Body schema: application/json
required
required
any (RecordCreateContent)

Defines the structure required to create a Record.

object (Metadata) <= 20 properties

Attach custom key value data to a resource. Useful for storing additional, structured information. If metadata appears in a response, it reflects the current metadata of the object. You can update metadata via the resource's update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.

Note: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.

Responses

Request samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Update a record

This endpoint is used to update Record resources.

Please note that currently all state and mode transitions are carried out by the fiskaly API service itself internally for Record resources. Please refer to our Guide.

Authorizations:
JWT
path Parameters
record_id
required
string <uuid> (RecordIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: 0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

Record identifier

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

required
UniversallyUniqueIdentifierV4 (string) or UniversallyUniqueIdentifierV3 (string) (IdempotencyKey)

The idempotency key, see idempotency.

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

Defines the structure required to update a Record.

object (Metadata) <= 20 properties

Attach custom key value data to a resource. Useful for storing additional, structured information. If metadata appears in a response, it reflects the current metadata of the object. You can update metadata via the resource's update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.

Note: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Retrieve a record

This endpoint is used to retrieve Record resources.

Authorizations:
JWT
path Parameters
record_id
required
string <uuid> (RecordIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: 0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

Record identifier

query Parameters
operation
string
Value: ""

Provides the captured raw payload of the original request for the "operation" property of the record.

file-artifact
string
Value: ""

Provides the complete signed XML artifact.

file-integrity
string
Value: ""

Provides a JOSE file ensuring blob data integrity, JWS-signed with the system certificate.

compliance-artifact
string
Value: ""

Provides the compliance-related document/artifact.

data-artifact
string
Value: ""

Provides the location of the export blob data.

data-integrity
string
Value: ""

Provides the location of the JOSE integrity file, JWS-signed with the system certificate.

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

Responses

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Files

A File represents a save file resource.

List files

This endpoint is used to list File resources.

Authorizations:
JWT
query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

system_id
string <uuid> (SystemIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: system_id=0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

System identifier

taxpayer_id
string <uuid> (TaxpayerIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: taxpayer_id=0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f

Taxpayer identifier

type
string (FileTypes)
Enum: "EXPORT" "AUDIT"

Filter listed files by type.

start
string <date-time> (FileCreationTimestamp) = 25 characters
Example: start=2006-01-02T15:04:05+00:00

Defines the start date and time

end
string <date-time> (FileCreationTimestamp) = 25 characters
Example: end=2006-01-02T15:04:05+00:00

Defines the end date and time

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Create a file

This endpoint is used to create a new File resource (e.g., SAF-T audit export) for a specified date range.

Authorizations:
JWT
header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

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

Content of a file creation request — defines the file type, date range, and optional scoping to a specific system or taxpayer.

Responses

Request samples

Content type
application/json
{
  • "content": {
    }
}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Stream a file

This endpoint is used to stream a File content.

Authorizations:
JWT
path Parameters
path
required
string (Path) [ 1 .. 44 ] characters ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: 0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f.zip

oas_components_parameters_file_path_description

header Parameters
X-Api-Version
required
string (ApiVersion) = 10 characters ^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3...
Example: 2006-01-02

The API version, see versioning.

Responses

Response samples

Content type
application/json
{
  • "content": {
    }
}

Was this page helpful?