Skip to content

Retrieve a subject

Version
fiskaly Logo
API docs by Redocly

fiskaly SIGN IT (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/signit
Developer Guide: workspace.fiskaly.com/sign-it/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.

Italy specifications

This API documentation specifically covers the Italian module, SIGN IT, that ensures compliance with Italian legislation for the telematic transmission of daily transactions. Compliance can be achieved through two different options: SIGN IT in its lite version or in its full version:

  • SIGN IT in its lite version connects your PoS with the Revenue Agencys web portal for the issuance of Online Commercial Documents, a legally valid alternative to the telematic registers to issue compliant receipts.
  • SIGN IT in its full version will comply with the new generation of software fiscalization as described in article 24 of D lgs 1 - 2024.

SIGN IT provides a test environment for integration and testing purposes as well as a dedicated live environment for performing the real-time sending of official transactions (commercial documents) to the Italian "Documento Commerciale Online" web procedure, present in the "Invoices and Fees" portal of the Revenue Agency. In order to access the live environment, please contact our sales team.

Background

SIGN IT implements legal requirements and technical guidelines for fiscalization compliance of PoS softwares in Italy.

SIGN IT in its lite version is based on the following Italian regulation:

  • Legislative Decree no. 127/2015 for the "Telematic transmission of VAT operations and control of sales of goods carried out through automatic dispensers" for the technological tools that guarantee the inalterability and security of the data, mandatory since 2021 for all taxpayers issuing commercial documents.

SIGN IT in its full version is based on the following Italian regulation:

  • Article 24 of the Legislative Decree published on January 8, 2024. The electronic storage of the total amount and telematic transmission of daily fees may be performed by means of software solutions that guarantee the security and inalterability of the data. These solutions must be able to enable the full integration and interaction with electronic payment processes, in order to simplify and reduce the administrative operations for taxpayers.

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.

Italy specifications

The fiskaly SIGN IT service provides a 100% legally compliant implementation in order to transmit the information from each transaction to the Revenue Agency in real time.

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-04-20 Validation and Reliability Improvements

  • added validation of the seller legal name (denominazione)
  • decoupled the CARD>TICKET number from the AdE voucher count
  • improved error response for malformed JSON request bodies
  • improved reliability for transient database errors
  • improved webhook request handling

2026-04-08 System Stability Improvement

  • added a new error mapping when an account must perform a password reset
  • improved cancellation and correction reliability
  • improved auth latencies

2026-04-03 System Stability Improvement

  • improved system stabability
  • improved error mapping and handling

2026-03-18 Sequence Support

  • 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
  • improved IT document transmission functionality

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.

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.

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 IT Postman environment JSON-based configuration file: Download Postman Environment

  4. Download the fiskaly SIGN IT 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 IT 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.

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

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

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

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.
🇮🇹 In Italy, the supported System type is: FISCAL_DEVICE. System types PAYMENT_DEVICE and E_INVOICE_SERVICE are not yet supported.

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

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 🇮🇹 Italy - Current number of records left (only relevant for offline scenario)

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

Not supported in 🇮🇹 Italy - 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: ""

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?