Step-by-Step Integration

⚠️Preview

The SIGN ES (Unified API) is currently available in the test environment for initial development and testing, though only a limited set of options can be tested at this stage. Production is not yet activated. For production use, please use the Specialized SIGN ES API.

To begin the integration process, please refer to the detailed step-by-step instructions provided here.

The accompanying diagram illustrates the workflow and highlights the essential steps necessary to successfully complete your integration, for which you will need to utilize our SIGN ES (Unified API).

1. Register on HUB

   Begin by registering on the fiskaly HUB. For more guidance on getting started, head to our HUB - First steps section.

2. Create Account & Organization GROUP

   Creating a fiskaly Account is the first step, after which you can proceed with setting up the first organizational structure for your business and generating your API Key.

   The Account represents the PoS provider or a retailer that operates its own PoS system. It is the top-level organization in the structure.

   After creating your fiskaly Account, you will be taken to the Organization Selector where you can create your Group.

   A Group is an intermediate level within an Account that helps you organize multiple Units into logical clusters.

3. Create API Key

   The next step is to generate an API Key for your organization via the HUB. This API Key and Secret pair is required to create your first Organization of type UNIT (Step 5).

   💡TEST vs. LIVE environments

   API Keys generated in the TEST environment (https://test.api.fiskaly.com) will create TEST resources, while those from the LIVE environment (https://live.api.fiskaly.com) will create LIVE resources.

1. Create Token

   Starting from this step, you will be using the SIGN ES (Unified API).

   Call the createToken endpoint with the API Key and Secret from step 3 to obtain a bearer token. Include this token in the Authorization header of steps 5 and 6.

2. Create Organization UNIT

   Create an Organization of type UNIT via the createOrganization endpoint. A UNIT represents a single legal entity (merchant). You will need to create one Organization UNIT for each taxpayer representation you manage.

   Using the bearer token generated in Step 4 with the API Key and Secret created for your Group ensures the UNIT is correctly nested under that Group in the hierarchy.

3. Create Subject (API Key)

   Create a Subject of type API_KEY for the Organization UNIT via the createSubject endpoint.

   To associate the Subject (API Key) with your UNIT, include the X-Scope-Identifier header set to the id of the Organization UNIT in your request.

4. Create new Token

   Create a token using the Subject API Key and Secret you just generated. This bearer token will be used for all subsequent steps to create resources within the corresponding Organization UNIT.

1. Create Taxpayer

   Now you’re ready to start creating the operational parts required for fiscalisation in Spain.

   Use the createTaxpayer endpoint to create the representation of a taxpayer as follows:

   • Set the taxpayer as type Company (legal entity) or Individual (natural person).
   • Provide the taxpayer’s Spanish NIF (Número de Identificación Fiscal).
   • The taxpayer’s fiscal territory determines whether Verifactu, SII, or TicketBAI applies — see the SIGN ES introduction for how these regulations map to Spanish territories.

   Once you create a Taxpayer, its state is set to ACQUIRED by default. To make it fully functional, update the state to COMMISSIONED using the updateTaxpayer endpoint.

2. Create Location

   📘Note

   A HEAD_OFFICE location is automatically created upon Taxpayer creation and shares the same UUID as the Taxpayer. However, for fiscalisation purposes, we recommend creating a separate location of type BRANCH (it may have the same address). If there are multiple locations, a corresponding branch should be created for each one.

   For each operating business location, create a Location of type BRANCH via the createLocation endpoint.

   Once a Location is created, its state is set to ACQUIRED by default. Update the state to COMMISSIONED using the updateLocation endpoint before proceeding.

3. Create System

   The createSystem endpoint allows you to create an abstraction of every Electronic Recording System used for fiscal operations. Every cash register or point of sale needs to be provided as a new System of type FISCAL_DEVICE.

   • A System will be connected to a specific, previously created Location of type BRANCH.

   Once a System is created, its state is set to ACQUIRED by default. To create Records, its state must be updated to COMMISSIONED using the updateSystem endpoint.

   📘Billing note

   For most contracts, Systems are the units used for billing with fiskaly. A System becomes relevant for billing once you change its state from ACQUIRED to COMMISSIONED in the LIVE environment. Resources in the TEST environment are not billed. For the exact billing conditions, please refer to your contract with fiskaly.

4. Create Record

   For each business operation carried out in the System, the createRecord endpoint must be called twice in sequence: first to record the intention to start a transaction, and then to provide the transaction data.

   Part A) Intention

   A Record of type INTENTION contains the association with the System that will carry out the transaction and an Operation of type TRANSACTION, representing the System’s intent to record a transaction.

   Part B) Transaction

   A Record of type TRANSACTION is associated with the previously created INTENTION and carries the transaction data, which is then signed and transmitted according to the taxpayer’s applicable regulation (Verifactu, SII, or TicketBAI).

   📘Note

   All Records created in the LIVE environment represent tax-relevant documents and must always reflect actual transactions. Use the designated TEST environment for integration testing.