Step-by-step Integration

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 IT API.

Step 1: Registration

Begin by registering on the Dashboard. Creating a fiskaly account is the first step, after which you can proceed with setting up the first organizational structure for your business and API Key.

video tutorial

Take a look at our video for a step-by-step explanation on how to set up your account and first organization.

Step 2: Creating your first organization

Continue with creating your first organization using the Dashboard. This organization will represent the POS provider or retailer with its own POS system.

Step 3: API Key generation

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

Note that API Keys generated in TEST environment will create TEST resources, while those from the LIVE environment will create LIVE resources. For further details, refer to our article on TEST and LIVE environment.

Starting from the next step, you will be utilizing our SIGN IT API.

Step 4: MANAGEMENT - Creating a Token

Begin using the SIGN IT API through the createToken endpoint. You will need to create a token to authenticate for the next steps.

Step 5: MANAGEMENT - Creating an Asset (Organizational Structure)

Continue with creating an Asset of type UNIT through the createAsset endpoint. You will need to create one Entity Asset for each of your taxpayer representations.

Step 6: MANAGEMENT - Creating a Subject

Create a Subject of type API_KEY through the createSubject endpoint. The connection between the Asset Unit and the API Key is established via the Scope-Identifier(using the id of the newly created Asset).

Step 7: MANAGEMENT - Creating a new Token

Next, create a token which will be used to create resources within the corresponding Asset Unit.

Step 8: OPERATION - Creating an Entity (Taxpayer representation)

Now you’re ready to start creating the operational parts required for fiscalization in Italy. In order to do so, use the CreateEntity endpoint to create the representation of a Taxpayer as follows:

• You will need to set the Taxpayer as an Entity of type Company (business) or Individual (self-employed). In any case, the name and the address must be provided.
• Within the Italian fiscalization information, the following taxpayer data must be provided:
  • tax_id_number represents the Italian Fiscal Code (Codice fiscale),
  • vat_id_number represents the Italian VAT Number (Partita IVA),
  • credentials: pin and password required to access Ade’s services. For more information, please refer to our Credentials section.

note

Only Fisconline or Entratel credentials are valid for using SIGN IT Lite. Your credentials must be updated every 60 days.

Step 9: OPERATION - Creating a Location Entity

For each operating business location, you need to add the Entity type Location via the CreateEntity endpoint.

Step 10: OPERATION - Creating a System (POS representation)

The createSystem endpoint allows you to create an abstraction of every device you use to issue receipts. This means, every cash register or point of sale needs to be provided as a new System in the SIGN IT API. For this, the System type FISCAL_DEVICE must be selected.

• A System will be connected to an already created Entity of type Location.
• For each device, you will need to provide information of the Product such as MPN, Brand and date of start of usage, as well as software name and version installed on the device. This information allows for a proper tracking of which device is carrying out fiscal transactions.

Step 11: OPERATION - Creating a Record

tip

Creating a record in the SIGN IT API will always require two subsequent calls:

• Part A) Intention - right at the beginning of a purchase process
• Part B) Transaction - directly after the payment process

PART A) Intention

For each business operation carried out in the cash register or POS, the use of the createRecord endpoint of SIGN IT API will be used in two calls: a first call to record the intention of starting a transaction, and secondly a call where you provide the Transaction data.

A record type Intention will contain the following information:

• Association to a System that will carry out a transactional operation.
• Operation type Transaction: meaning the operation that the system is intending to carry out is recording a transaction.
• The detailed information, if applicable, if this is a training record (for testing purposes) and possibility to indicate information of the person performing the operation.

Part B) Transaction

The last step in order to issue a compliant receipt in Italy, is to perform a call once again to the createRecord endpoint, indicating a Record type Transaction.

Any Transaction document will be associated to the internal identifier of an already created Record type Intention, and can contain details for training purposes (documents issued in training or test mode).

The Transaction can be used to carry out one of the following operations in Italy:

• RECEIPT: This operation contains all the required information for the creation of a sales commercial document in Italy:
  • Document information such as number, activity code (if applicable), transaction date and total amounts of the document (including and excluding VAT)
  • Information of each entry or line item sold in the operation:
    • Identification of a Sale
    • Description
    • Indication if it’s a good or service
• CORRECTION: This operation type is used to represent any return process carried out. It contains the same data as a RECEIPT type, and additionally:
  • Reference id to an already created receipt (original transaction document)
  • Indication that this return receipt is being issued as a DIFFERENCES method, where the quantity is a negative amount of items being returned
• CANCELLATION: This operation is used to cancel an entire transaction. For this, the id of a previously created record needs to be provided.

In all cases, once the transaction is properly recorded and the commercial document information is transmitted to AdE’s web portal, the compliant response of the record creation will indicate the progressive number assigned by AdE to the Commercial Document, as well as the PDF of the document as created by the Web Portal, and the consumer’s Lottery Code (if provided in the transmitted payload).