For SIGN DE customers
SIGN ES Integration Guide for SIGN DE Customers
This guide helps you to successfully integrate the fiskaly SIGN ES API and describes all the necessary steps you and your merchants need to take.
Setup - Creating organizations
The creation and organization setup works the same way as in SIGN DE.
Note: deviating from SIGN DE, in SIGN ES it is absolutely crucial to create a separate managed organization for each location (store/shop).
Creating (managed-)organizations is done via the fiskaly Management API. Adding users and creating API Keys is also done via the Management API. Our Guide for new customers further describes these initial steps.
SIGN ES
As you are already familiar with our SIGN DE API, implementing SIGN ES should be fairly easy. The process flow was designed to be the same for both APIs. In order to facilitate the process even more, differences and similarities to SIGN DE are outlined in the individual endpoints.
SIGN ES vs. SIGN DE
Once the organization structure has been created, you can continue step by step using the following SIGN ES API endpoints:
PUT: Create taxpayer information
Use this endpoint to create the taxpayer. The step must be performed only once.
Taxpayer: In SIGN ES, a managed organization represents a taxpayer and its fiscal territory (the legal address of the company). Within each managed organization, a taxpayer must be created. Important: in case of any amendment to the taxpayer data, a new managed organization must be created since the taxpayer's data cannot be changed afterwards.
As of now, there is no equivalent endpoint in SIGN DE.
PUT: Create a signer
Use this endpoint to create at least one signer.
Regarding the fields private_key and public_key: this certificate information will be provided by fiskaly.
Signers: In SIGN ES, a signer represents the signing device. At least one signer must be created, but in scenarios with a specifically high volume of invoices, multiple signers may be created. The signer contains a certificate which has to be associated with the taxpayer within the tax authority’s servers.
Note: this Device Certificate is provided by fiskaly or, if available, you can also use an existing one.
The signer corresponds to the TSS in SIGN DE. In contrast to SIGN DE, a signer can immediately be used as it does not have any different states. Therefore, the implementation process is even easier.
PUT: Create a client
Use this endpoint to create a client. The client uniquely identifies a terminal, POS device, application or other devices used to issue invoices.
Clients: In SIGN ES, a client represents the POS device. In order to issue invoices you need one client per POS device and at least one signing device.
The client corresponds to the client entity in SIGN DE. Each client is connected to a signer - the same way as each client is connected to a TSS in SIGN DE with the only difference that the connection between client and signer in SIGN ES is made in the Request Body and not in the Path Parameters.
- In SIGN ES, clients can have two states:
ENABLEDandDISABLED. - In SIGN DE, the corresponding states are
REGISTEREDandDEREGISTERED.
Note: in contrast to SIGN DE, setting a client’s state to DISABLED is irreversible in SIGN ES.
PUT: Create an invoice
Use this endpoint to create an invoice.
client_id and invoice_id in the path parameters must be defined by you.
Invoices: In SIGN ES, there are three types of invoices: simplified invoice, complete invoice and correcting invoice:
- The simplified invoice only contains information about the issuer, but no information about the recipient of the invoice. This invoice can only be issued up to an amount of € 400 and in some specific cases up to an amount of € 3.000 (retail sales, restaurants, parking services...),
- the complete invoice includes information about both the issuer and the recipient of the invoice, this is the most commonly used type for services provided by professionals or companies,
- the correcting invoice must be issued whenever an error has occurred, such as in case of an incorrect amount. Within this invoice, merchants must choose that it is either a correction by substitution, or a correction by differences.
Invoices in SIGN ES correspond to transactions in SIGN DE. In contrast to SIGN DE, invoices are being directly submitted to the relevant tax authority. The response returns the signed invoice and also includes its state of synchronization and transmission to the relevant tax authority.
Since there is no regulation requiring transactions to be started, updated and finished in Spain, this part of SIGN ES is much simpler than SIGN DE. In contrast to SIGN DE, invoices handed over to the consumer must include an identifier code and a QR code, which have to be placed according to specific guidelines.
Details can be found here: Invoice Compliance.
PATCH: Update an invoice
Use this endpoint to update an invoice This endpoint should only be used in order to cancel an already created invoice.
In SIGN DE, there is no specific endpoint to cancel receipts. Handling cancellations in Spain is thus much easier.
How to create a digital receipt
After creating an invoice you can create a digital receipt for your invoice using our digital receipt endpoint.The returned URL can easily be shown as a QR code to the consumer at the checkout process and the receipt must no longer be printed. This saves costs, supports the environment, increases customer satisfaction, and adds a new customer touch point for the merchant.
To learn more about the digital receipt beyond its basic functionality, how to improve customer’s loyalty, and take advantage of the fiskaly partner ecosystem, get in touch with us via sales@fiskaly.com. For the visualization of such a digital receipt, take a look at our digital receipt guide and feel free to use our openly available receipt API.
Ready to deep dive?
Have a look at our SIGN ES Quick Start - we created a Postman Collection that allows you to go through the most important functions of this API.