Step-by-Step Integration

📘Note

If you have already integrated SIGN IT or SIGN FR, the initial setup steps in this guide will likely be familiar and may already be completed. In that case, you can jump straight to Step 10 to review the additional steps required.

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

   Tokens are short-lived JWTs that authenticate every subsequent SIGN PT call. They are obtained per Account or Organization scope.

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

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

   • Set the taxpayer as type Company (legal entity) or Individual (natural person). In both cases, the name and the address must be provided.
   • Within the Portuguese fiscalisation information, at least the following taxpayer data must be provided:
     • tax_id_number: the taxpayer’s Portuguese NIF (Número de Identificação Fiscal). 9 digits, no spaces or separators (e.g. 501234567).
     • credentials: the AT subuser credentials that SIGN PT will use to call AT web services on this taxpayer’s behalf:
       • Username: the subuser identifier in <NIF>/<subuser-id> format (e.g. 501234567/5), as issued by the Portal das Finanças.
       • Password: the password set for that subuser.

   These are not the merchant’s main Portal das Finanças login credentials. They must be a dedicated subuser created specifically for web service access — see the Important note below.

   ⚠️Important

   AT Web Service usage via SIGN PT requires prior setup on the Portal das Finanças by the taxpayer or its legal representative: a dedicated Web Service subuser should be created, granted the required permissions (e.g. WSE, WFA, WDT), and the applicable AT terms and conditions accepted.

   For step-by-step instructions on creating the subuser, see Creating the subuser on the Portal das Finanças.

   Once you create a Taxpayer, either of type Company or Individual, 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 together with 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 (ERS) 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.

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 can carry out one of the following operations:

   • INVOICE/RECEIPT: Represents the sale of a good or service, including document details (document number, activity code, transaction date, total amounts including and excluding VAT) and line items (each line has an entries[].type such as SALE, description, whether it is a GOOD or SERVICE, etc.).
   • CORRECTION: Issues a corrective document (NC for credit / ND for debit) referencing a previously created INVOICE/RECEIPT. Contains the corrected line items and a reference_id to the original document.
   • CANCELLATION: Used to invalidate an entire transaction. Requires the id of a previously created record.

   After the TRANSACTION Record is submitted, SIGN PT performs the compliant issuance steps for the selected operation: it assigns the next sequential number in the series (numbers are not pre-assigned), signs and hash-chains the document, and generates the data required for the final customer-facing representation.

   Depending on the reporting configuration of the Taxpayer, the same transaction data is then either:

   • included in SAF-T (PT) reporting/export (for monthly submission), and/or
   • reported to AT via web services (e.g., invoices via WFA; transport documents via WDT, if applicable and permissions were granted).

   Once processing is finished, SIGN PT returns (via the Record response and/or retrievable Record artifacts):

   • the compliance payload required for printing (e.g., ATCUD, QR code content, the hash excerpt, and the software certificate number)
   • the signed/chained document data needed to build the final receipt/invoice representation, and
   • processing status information for the Record (success/failure and relevant error details).

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