Skip to content

Update an organization

fiskaly Logo
API docs by Redocly

fiskaly SIGN PT — Preview (2026-05-04) (2026-05-04)

Download OpenAPI specification:

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

Imprint: fiskaly.com/impressum
Privacy Policy: fiskaly.com/privacy-policy
Service Details: workspace.fiskaly.com/pm-hub/service-descriptions/sign-pt/
Developer Guide: workspace.fiskaly.com/sign-pt/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.

Portugal specifications

This API documentation specifically covers the Portuguese module, SIGN PT, which ensures compliance with Portuguese fiscalisation legislation for the issuance, signing, and reporting of fiscally relevant documents.

SIGN PT is a cloud-based fiscalisation API that enables PoS, ERP, and invoicing systems to issue Portuguese-compliant invoices, receipts, and corrective documents through a single integration. The service handles the full compliance flow:

  • Registration and management of document series with the Autoridade Tributária e Aduaneira (AT)
  • Digital signing and hash-chaining of documents
  • Generation of the unique document code (ATCUD) and QR code
  • Reporting of invoicing data to the AT — either in real time via Web Services or through monthly SAF-T (PT) XML exports
  • Optional long-term archiving through the fiskaly SAFE service

SIGN PT provides a test environment for integration and testing purposes, as well as a dedicated live environment for the issuance and real-time transmission of fiscally relevant documents to the AT. Documents created in the test environment are not legally valid and are not communicated to AT production systems. To access the live environment, please contact our sales team.

Background

SIGN PT implements the legal requirements and technical specifications for fiscalisation compliance of PoS, ERP, and invoicing software in Portugal.

SIGN PT is based on the following Portuguese regulation:

  • Decree-Law No. 28/2019 of 15 February, which consolidated and modernised the rules on the issuance, archiving, and processing of invoices and other tax-relevant documents, including the obligation to use AT-certified invoicing software and to include the unique document code (ATCUD) and QR code on every fiscally relevant document.
  • Ordinance (Portaria) No. 363/2010 of 23 June, which establishes the certification regime for invoicing software, including the requirements for digital signing, hash chaining, and the printed certification mention on issued documents.
  • Order (Despacho) No. 8632/2014 of 3 July, which sets the technical requirements for documents issued by certified invoicing software, including the format of the printed hash excerpt and the certification statement.
  • Ordinance (Portaria) No. 195/2020 of 13 August, which defines the format and content of the unique document code (ATCUD) and the technical specifications for the two-dimensional barcode (QR code) that must appear on fiscally relevant documents. ATCUD has been mandatory on all fiscally relevant documents since 1 January 2023, and the QR code since 1 January 2022.
  • Ordinance (Portaria) No. 302/2016 of 2 December, which establishes the data structure of the SAF-T (PT) file (current version 1.04_01) used for the standardised electronic submission of invoicing and accounting data to the AT.
  • Decree-Law No. 198/2012 of 24 August, which establishes the obligation to communicate invoicing data to the AT, either in real time via Web Services or through periodic SAF-T (PT) submission, and sets the corresponding deadlines.
  • Article 80(3) of the 2026 State Budget Law, which from 1 January 2027 requires PDF invoices used as electronic invoices to carry a qualified electronic signature (QES) under the eIDAS regulation.

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.

Portugal specifications

The fiskaly SIGN PT service provides a fully compliant implementation for the issuance, signing, and reporting of fiscally relevant documents in Portugal. Each document issued through SIGN PT is digitally signed and hash-chained, assigned a strictly sequential number within a registered and validated series, and enriched with the mandatory ATCUD and QR code data required for printing or PDF rendering. Depending on the taxpayer's reporting configuration, transaction data is then transmitted to the AT in real time via Web Services or included in the monthly SAF-T (PT) export.

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-05-04 Portugal Fiscalization

  • enabled initial fiscalization schema for PT taxpayers in test environment
  • added new field reason for transactions of type CORRECTION and CANCELLATION

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-05-04.

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

Idempotency

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

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

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

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

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

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

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

If the API service returns:

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

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

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

FAQs

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

Tokens

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

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

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

Not supported in Portugal - 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?