Skip to content

List subjects

Version
fiskaly Logo
API docs by Redocly

fiskaly SIGN FR (2026-02-03)

Download OpenAPI specification:

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

Imprint: fiskaly.com/impressum
Privacy Policy: fiskaly.com/privacy-policy
Service Details: fiskaly.com/signfr
Developer Guide: workspace.fiskaly.com/sign-fr/2026-02-03/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.

Background

fiskaly SIGN FR is designed to help POS providers comply with French fiscalization rules, particularly Article 286 of the General Tax Code (CGI). According to this regulation, POS systems must guarantee inalterability, security, conservation, and archiving.

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.

Guides

To ensure a smooth implementation of our fiskaly API, we highly recommend that you first have a look at our integration guides 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-03-18 Sequence Support

  • added sequence support for FR configured INFOCERT fiscalization taxpayers
  • added query filtering support for listLocations, listSystems, and listRecords API operations
  • added X-Idempotency-Replayed header for all POST and PATCH requests to indicate if the idempotent request has already been replayed

2026-02-23 Record Transmission

  • improved and made more consistent error handling for IT
  • improved TRANSACTION::CORRECTION of RECEIPTS for IT configuration
  • improved log handling for INTENTION::UPLOAD record of type PEPPOL_PROOF_OF_OWNERSHIP
  • improved error handling for TRANSACTION::INVOICE record type
  • added updated_at timestamp property for Taxpayer, Location, and System resource responses

2026-02-17 E-Invoice Receiving Support

  • improved the reliability of IT based document transmission for the POST /records endpoint
  • provided BE based receiving functionality for E_INVOICE_SERVICE system resources
  • updated BE based sending functionality for E_INVOICE_SERVICE system resources

2026-02-03 E-Invoice Support

  • provided BE based fiscalization entity support for POST /taxpayer creation functionality
  • provided E_INVOICE_SERVICE system resource type
  • provided PAYMENT_DEVICE system resource type
  • refined formerly known /entities route to /taxpayers and /locations to provide clearer terminology of taxpayer information and connection location information of legal entities
  • refined formerly known /assets route to /organizations to provide clearer terminology of management organization resources

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-02-03.

Version SIGN E-INVOICE
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.

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 API Secret via fiskaly HUB.

  3. Download your fiskaly SIGN FR Postman environment JSON-based configuration file: Download Postman Environment

  4. Download the fiskaly SIGN FR Postman collection JSON-based configuration file: Download Postman Collection

  5. Start Postman and import the downloaded Postman environment and collection files.

  6. Update the API Key and API Secret values in the Postman environment to match your credentials.

  7. Select the fiskaly SIGN FR Postman environment and run the collection.

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.xf

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.

Recreation 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": {}
}

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 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": {}
}

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 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": {}
}

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": {}
}

Organizations

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

  • ACCOUNT represents the PoS provider or a retailer that operates its own PoS system. It is the top-level organization in the structure. This type represents the first created organization via the fiskaly Dashboard and cannot be created via the API.
  • GROUP an optional intermediate layer used to group multiple Organization resources of type UNIT.
  • UNIT represents a merchant.

List organizations

This endpoint is used to create 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 an 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 an 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": {}
}

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

oas_components_parameters_location_identifier_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.

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

The idempotency key, see idempotency.

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

oas_components_schemas_location_update_content_description

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

oas_components_parameters_location_identifier_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": {
    },
  • "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

oas_components_parameters_location_identifier_query_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
{
  • "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

oas_components_parameters_location_identifier_query_description

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::CLOSING" "TRANSACTION::ABORT" "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"

oas_components_parameters_record_type_query_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
{
  • "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

Current number of records left (only relevant for offline scenario in 🇫🇷 France)

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

The hash stored during offline phase in base64 format (only relevant for offline scenario in 🇫🇷 France)

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: ""

Defines the operation.

file-artifact
string
Value: ""

oas_components_parameters_record_file_artifact_query_description

file-integrity
string
Value: ""

oas_components_parameters_record_file_integrity_query_description

compliance-artifact
string
Value: ""

oas_components_parameters_record_compliance_artifact_query_description

data-artifact
string
Value: ""

oas_components_parameters_record_data_artifact_query_description

data-integrity
string
Value: ""

oas_components_parameters_record_data_integrity_query_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": {
    },
  • "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

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": {
    }
}

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?