Step-by-Step Integration Process

This guide walks you through the complete integration process for fiskaly SIGN ES, from account registration to issuing your first signed invoice. By the end, you will have a taxpayer, signer, and client configured and ready to create fiscally compliant invoices for Spain.

📘Already using SIGN DE?

If you are already integrated with fiskaly SIGN DE, the process flow was designed to be consistent across both APIs. See the SIGN DE customer guide for a detailed comparison of differences and similarities between the two APIs.

Overview

Before diving into the setup, here is what you will need:

🏢

Organization

Your top-level entity in fiskaly. Managed organizations represent individual merchants.

🔑

API Key & Secret

Credentials generated in HUB, used to authenticate all subsequent API requests.

🧾

Taxpayer

The entity obliged to TicketBAI or Verifactu regulations, with tax number and territory.

🔏

Signer

Responsible for the electronic signature of invoices. Certificates are managed automatically.

💻

Client

Represents a POS terminal or invoicing device that creates invoices against a Signer.

📄

Invoice

A signed fiscal record. Once your setup is complete, you can create compliant invoices.

Prerequisites

📘Before you begin

You need a fiskaly account and access to the fiskaly HUB. If you do not have an account yet, sign up here.

To use SIGN ES, you will need the following information:

• For the taxpayer obliged to TicketBAI or Verifactu regulations:
  • Legal name
  • Spanish tax number (NIF)
  • Territory
  • Email and address
  • Additionally, representative information for companies
• The content of the invoice document, including:
  • The detail of line items for all transactions, including VAT rates, quantity, and price
  • The recipient information (legal name, Spanish or international identification number, and address) for B2B or enriched B2C transactions

You will also need a tool to make HTTP requests — for example cURL (command line), Postman, or your own application code.

Integration Workflow

The diagram below illustrates the workflow and highlights the essential steps necessary to successfully complete your integration. Each tile links directly to the matching setup step below.

Step-by-Step Setup

1. Register on HUB

   Begin by registering on fiskaly HUB. Creating an account is the first step, after which you can proceed with setting up the organizational structure for your business within our system.

   💡Not ready for production?

   You can start with the TEST environment to explore the API without affecting any live data. API keys generated in the TEST environment will create TEST resources, while those from the LIVE environment will create LIVE resources.

   📘Note

   By default, your account starts in the TEST environment. To go live, contact our Sales Team to enable the LIVE environment for your first organization. Resources created in the TEST environment are not transferred to the LIVE environment. Once you have at least one LIVE organization, you can switch additional organizations to LIVE without contacting Sales. The TEST environment remains available at all times.

2. Create first organization

   Continue by creating your first organization using HUB. This organization will represent the POS provider or retailer with its own POS system. You will need to include a billing address at this stage. This address is only used for fiskaly’s billing purposes. In HUB, this organization is referred to as a Group.

   A main organization represents a POS provider or retailer with its own POS system. A managed organization represents a merchant. For example, if the main organization is a POS provider, each managed organization represents an individual merchant (taxpayer) with their own NIF and fiscal territory.

   📘Note

   The relevant fiscal territory is determined by the legal address the company is registered at — not the physical location of a store.

1. Create managed organization(s)

   After establishing your first organization, create managed organizations. Each managed organization represents a merchant, enabling you to manage them separately. In HUB, a managed organization is referred to as an Organization UNIT.

   💡Automate with the Management API

   If you plan to onboard many merchants, use the createOrganization endpoint of the Management API and pass the main organization’s ID in the managed_by_organization_id field to automate the process.

2. Create API key

   Generate an API key within each managed organization. This can be done via the HUB (Settings → API Keys → CREATE API KEY) or the createApiKey endpoint of the Management API.

   ⚠️Store your credentials safely

   The API Secret is only shown once. Make sure to copy and store it in a secure location before closing the dialog.

   This API key and secret pair is required for generating an access token, which is used for all subsequent SIGN ES API calls. Use the credentials to obtain an access token before continuing. Note that all SIGN ES request bodies use a content envelope wrapper.

   cURLJavaScript

   curl -X POST https://test.es.sign.fiskaly.com/api/v1/auth \
     -H "Content-Type: application/json" \
     -d '{
       "content": {
         "api_key": "your_api_key",
         "api_secret": "your_api_secret"
       }
     }'

   const response = await fetch(
     "https://test.es.sign.fiskaly.com/api/v1/auth",
     {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         content: {
           api_key: "your_api_key",
           api_secret: "your_api_secret",
         },
       }),
     }
   );
   
   const { access_token } = await response.json();

   The response contains an access_token that you must include as a Bearer token in the Authorization header of all following requests.

1. Add taxpayer information

   After authenticating, add the taxpayer’s information to the system. The taxpayer represents the entity obliged to TicketBAI or Verifactu regulations.

   cURLJavaScript

   curl -X PUT https://test.es.sign.fiskaly.com/api/v1/taxpayer \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "content": {
         "issuer": {
           "tax_number": "B12345678",
           "legal_name": "My Company S.L."
         },
         "territory": "SPAIN_OTHER",
         "sii": {
           "state": "ENABLED"
         }
       }
     }'

   const response = await fetch(
     "https://test.es.sign.fiskaly.com/api/v1/taxpayer",
     {
       method: "PUT",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         content: {
           issuer: {
             tax_number: "B12345678",
             legal_name: "My Company S.L.",
           },
           territory: "SPAIN_OTHER",
           sii: {
             state: "ENABLED",
           },
         },
       }),
     }
   );

   ⚠️Territory determines the regulation

   Make sure the territory field matches the legal address of the taxpayer. SIGN ES applies the corresponding legislation automatically based on this value.

   Verifactu: SPAIN_OTHER (mainland Spain), CANARY_ISLANDS, CEUTA, MELILLA

   TicketBAI: ARABA, BIZKAIA, GIPUZKOA

   No fiscal regulation currently applies to NAVARRE.

   This is a compliance step to ensure that all invoices generated are in line with tax regulations and contain all the necessary taxpayer details.

2. Create signer

   Create a Signer for each managed organization. The signer is responsible for the electronic signature of invoices.

   cURLJavaScript

   SIGNER_ID=$(uuidgen)
   
   curl -X PUT "https://test.es.sign.fiskaly.com/api/v1/signers/${SIGNER_ID}" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "content": {}
     }'

   const signerId = crypto.randomUUID();
   
   const response = await fetch(
     `https://test.es.sign.fiskaly.com/api/v1/signers/${signerId}`,
     {
       method: "PUT",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         content: {},
       }),
     }
   );

   Each signer requires a certificate. The certificate handling depends on the regulation.

   Verifactu: A fiskaly-managed electronic certificate is automatically allocated during Signer creation. fiskaly is registered as a social collaborator with the AEAT for Verifactu, for which the taxpayer needs to sign a social collaboration agreement with fiskaly. See Social Collaboration for details.

   TicketBAI: A device certificate is automatically allocated during Signer creation, unless you provide your own external device certificate. The certificate can be retrieved from the API response. If your customers are located in the Basque Country, ensure you send them the registration guide from fiskaly so they can correctly register the device certificates with the corresponding tax authority.

3. Create clients

   Create a Client for each POS device or invoicing device used within your organization. The Client must be linked to a Signer.

   cURLJavaScript

   CLIENT_ID=$(uuidgen)
   
   curl -X PUT "https://test.es.sign.fiskaly.com/api/v1/clients/${CLIENT_ID}" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "content": {
         "signer_id": "your-signer-id"
       }
     }'

   const clientId = crypto.randomUUID();
   
   const response = await fetch(
     `https://test.es.sign.fiskaly.com/api/v1/clients/${clientId}`,
     {
       method: "PUT",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         content: {
           signer_id: signerId,
         },
       }),
     }
   );

4. Create invoices

   With all the previous steps completed, you are now ready to create invoices. This is the final step where invoices are generated and signed. SIGN ES ensures that all invoices are compliant with TicketBAI in the Basque Country and with Verifactu in the rest of the Spanish territory.

   cURLJavaScript

   INVOICE_ID=$(uuidgen)
   
   curl -X PUT "https://test.es.sign.fiskaly.com/api/v1/clients/${CLIENT_ID}/invoices/${INVOICE_ID}" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "content": {
         "type": "SIMPLIFIED",
         "number": "INV-001",
         "text": "Sales receipt",
         "full_amount": "12.10",
         "items": [
           {
             "text": "Product A",
             "quantity": "1",
             "unit_amount": "10.00",
             "full_amount": "12.10",
             "system": {
               "type": "REGULAR",
               "rate": "21.00"
             }
           }
         ]
       }
     }'

   const invoiceId = crypto.randomUUID();
   
   const response = await fetch(
     `https://test.es.sign.fiskaly.com/api/v1/clients/${clientId}/invoices/${invoiceId}`,
     {
       method: "PUT",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         content: {
           type: "SIMPLIFIED",
           number: "INV-001",
           text: "Sales receipt",
           full_amount: "12.10",
           items: [
             {
               text: "Product A",
               quantity: "1",
               unit_amount: "10.00",
               full_amount: "12.10",
               system: {
                 type: "REGULAR",
                 rate: "21.00",
               },
             },
           ],
         },
       }),
     }
   );

   The response includes the signed invoice data with all the compliant information required by the applicable fiscal regulation.

   📘Important

   For compliance with Verifactu, please make sure that a valid social collaboration agreement is signed by the taxpayer before starting to issue invoices. Find more information in the section Social Collaboration.

   Please refer to the invoicing regulations in Spain for additional information about invoice creation.

Digital Receipt

After creating an invoice you can generate a digital receipt using the digital receipt endpoint. The returned URL can be displayed as a QR code to the consumer at checkout — no need to print a physical receipt. This reduces costs, supports the environment, and adds a new customer touch point for the merchant.

To learn more about digital receipts and how to improve customer loyalty through the fiskaly partner ecosystem, get in touch at sales@fiskaly.com. See the digital receipt guide for full details.

💡Automate the setup

This entire sequence of requests can be integrated into a provisioning solution that requires no manual user interaction. The implementation details are up to you.

Next Steps

SIGN ES API Reference

Full API documentation for the SIGN ES v1 endpoint — all resources, parameters, and responses.

Invoice Compliance

Learn about the compliance requirements for TicketBAI and Verifactu invoices.

Electronic Certificates

Understand certificate management, social collaboration agreements, and device certificates.

Glossary

Reference of key terms and concepts used throughout the SIGN ES documentation.