Skip to content

List entities

Version
fiskaly Logo
API docs by Redocly

fiskaly SIGN IT (2025-08-12)

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/2025-08-12/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 "Online commercial document" 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-01-26 Record transmission

  • More explicit error returned when submitting entries with mixed or wrong number for a TRANSACTION::RECEIPT
  • Improved description of fiscalization.tax_id_number and fiscalization.credentials.tax_id_number
  • Allow correction of receipt belonging to a different system
  • Record submission general latency and reliability improvements
  • Improved error message reported under the record logs property
  • Support authentication for more tax_id types ending with -000 suffix
  • Reject receipts with negative amounts in test environment

2025-12-30 Improved Resource Checks

  • provided improved resource constraint checks for all update and retrieve endpoint operations
  • provided new X-Trace-Identifier in the OAS schema

2025-12-23 Entity, System, and Records

  • provided new X-Trace-Identifier for all HTTP service responses to support customer success communication
  • provided entity property to updateSystem to alter the entity connection of System::FISCAL_DEVICE resources in mode SUSPENDED
  • refined ComplianceData string length to maximum 128 characters
  • provided a new TRANSACTION::ABORT record schema to the createRecord endpoint to gracefully abort started sale (INTENTION::TRANSACTION records) operations

2025-12-15 File Streaming

  • refined GET /files/<path> (streamFile) functionality to download an arbitrary path
  • enabled downloading of signed integrity check JWS file from a dedicated automatic exported and archived ZIP file

2025-12-12 Archiving and Files

  • enabled automatic archiving support for French System::FISCAL_DEVICE resources based on CLOSING::DAILY computations
  • enabled GET /files (listFiles) endpoint to search for automatic exported and archived ZIP files
  • added pagination query parameters to listFiles endpoint
  • enabled GET /files/<id>.zip (streamFile) endpoint to download a dedicated automatic exported and archived ZIP file
  • improved createToken endpoint rate limit behavior

2025-12-08 Offline Record Replay

  • enabled INTENTION::REPLAY record functionality for offline-based recording support for France
  • updated createToken endpoint rate limit behavior
  • added support for new role selection flows in the AdE portal for Italian FISCONLINE credentials

2025-12-01 Record Export and Files

  • enabled INTENTION::EXPORT record creation support to generate dedicated system-based exports of records produced in a given time range with optional filter mechanism
  • added INTENTION::REPLAY record OAS schema design for offline-based recording support
  • added streamFile endpoint to download ZIP archive files from generated exports
  • added listFiles endpoint OAS design for listing and searching of file resources
  • added data-artifact query to fetch on demand data artifact information of a record
  • added data-integrity query to fetch on demand data integrity information of a record
  • provided data property for all RecordResource to provide data artifact and data integrity information of given record export ZIP archive and its current location SERVICE or ARCHIVE

2025-11-27 Record Integrity and Closing

  • enabled lower case characters for Italian tax identification number (codice fiscale)
  • enabled record file signed integrity check based on JSON Web Signature (JWS) information
  • enabled automatic closing functionality for French System::FISCAL_DEVICE resources
  • refined RecordFileIntegrity schema to provide dedicated application/jose MIME type
  • added INTENTION::CLOSING, CLOSING::DAILY, CLOSING::MONTHLY, and CLOSING::YEARLY system types
  • added INFOCERT as new French fiscalization.credentials.provider
  • added 429 error response for too many requests to all endpoints
  • added used_in connection on intention record to retrieve outcome records

2025-09-29 Entities and Records

  • added fiscalization.fiscal_year_date property in POST /entities and PATCH /entities for FR entities
  • provided journaling support for record creation of INTENTION type EVENT and DUPLICATE
  • provided journaling support for record creation of TRANSACTION type DOWN_PAYMENT, PROOF_OF_PAYMENT, DRAFT_RECEIPT, PRO_FORMA_INVOICE, INVOICE, and ENRICHMENT

2025-09-08 Entity Fiscalization

  • enabled configuration of fiscalization.credentials.tax_id_number in POST /entities and PATCH /entities

2025-09-01 Record Compliance Artifact

  • added record query compliance-artifact to obtain an existing compliance artifact
  • enabled production LIVE endpoint

2025-08-12 Entities & Records

  • enabled FR-based entity fiscalization configuration support
  • added record TRANSACTION type DRAFT_RECEIPT API schema
  • added record TRANSACTION type INVOICE API schema
  • added record TRANSACTION type PRO_FORMA_INVOICE API schema
  • added record TRANSACTION type ENRICHMENT API schema
  • added record TRANSACTION type PROOF_OF_PAYMENT API schema
  • added record TRANSACTION type DOWN_PAYMENT API schema
  • added record INTENTION type EVENT API schema
  • added record INTENTION type EXPORT API schema
  • added record INTENTION type DUPLICATE API schema
  • added record query file-artifact to obtain the signed record of the journal
  • added record query operation to obtain the raw record operation information

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: 2025-08-12.

Version Supported Country
X-Api-Version: 2025-08-12 SIGN IT 🇮🇹 SIGN FR 🇫🇷
X-Api-Version: 2024-10-31 SIGN 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 the fiskaly dashboard.

  3. Insert your API Key and API Secret to download your personalized fiskaly SIGN IT Postman Environment JSON based configuration file:

    API Key
    API Secret

  4. Download the fiskaly SIGN IT Postman Collection JSON based configuration file:


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

  6. Select the fiskaly SIGN IT Postman environment and run the collection.

FAQs

We have a dedicated FAQ page for each country the fiskaly API service solution can be used and integrated: SIGN IT 🇮🇹 and SIGN FR 🇫🇷

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

This endpoint is used to list Subject 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.

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

Assets

Asset resources are used to represent the management structure (organizational hierarchy):

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

List assets

This endpoint is used to list Asset 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.

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 asset

This endpoint is used to create Asset 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.

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 asset

This endpoint is used to update an Asset resource.

Authorizations:
JWT
path Parameters
asset_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 asset

This endpoint is used to retrieve an Asset resource.

Authorizations:
JWT
path Parameters
asset_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": {}
}

Entities

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

The lifecycle of an Entity resource is depicted in the following state and mode transitions:

List entities

This endpoint is used to list Entity 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 an entity

This endpoint is used to create Entity resources. Currently the fiskaly API supports the following creation use cases:

  • legal entities (taxpayer) as a COMPANY (for business entities) or as an INDIVIDUAL (for self-employed) which require the details of the entity legal name, legal address, and fiscalization-related data such as the VAT number, tax identification number, and credentials for accessing the Revenue Agency portal.
  • LOCATION entities represent the physical address of the business premises or establishment of a given legal entity -- COMPANY or INDIVIDUAL

When an Entity 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 updateEntity 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 an entity

This endpoint is used to update an Entity 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
entity_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 an entity

This endpoint is used to retrieve an Entity resource.

Authorizations:
JWT
path Parameters
entity_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": {}
}

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.

entity_id
string <uuid> (TaxpayerIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: entity_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.

entity_id
string <uuid> (TaxpayerIdentifier) ^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9...
Example: entity_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

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?