Processo di integrazione passo per passo

Questa guida ti accompagna attraverso l’intero processo di integrazione di fiskaly SIGN ES, dalla registrazione dell’account all’emissione della prima fattura firmata. Al termine, avrai configurato un contribuente, un firmatario e un client pronti per creare fatture fiscalmente conformi per la Spagna.

📘Già integrato con SIGN DE?

Se sei già integrato con fiskaly SIGN DE, il flusso del processo è stato progettato per essere coerente tra entrambe le API. Consulta la guida per clienti SIGN DE per un confronto dettagliato delle differenze e somiglianze tra le due API.

Panoramica

Prima di iniziare la configurazione, ecco cosa ti servirà:

🏢

Organizzazione

La tua entità di livello superiore in fiskaly. Le organizzazioni gestite rappresentano singoli commercianti.

🔑

Chiave API e segreto

Credenziali generate in HUB, utilizzate per autenticare tutte le successive richieste API.

🧾

Contribuente

L'entità soggetta alle normative TicketBAI o Verifactu, con numero fiscale e territorio.

🔏

Firmatario

Responsabile della firma elettronica delle fatture. I certificati sono gestiti automaticamente.

💻

Client

Rappresenta un terminale POS o un dispositivo di fatturazione che crea fatture tramite un firmatario.

📄

Fattura

Un registro fiscale firmato. Una volta completata la configurazione, potrai creare fatture conformi.

Prerequisiti

📘Prima di iniziare

È necessario un account fiskaly e l’accesso al fiskaly HUB. Se non hai ancora un account, registrati qui.

Per utilizzare SIGN ES, avrai bisogno delle seguenti informazioni:

• Per il contribuente soggetto alle normative TicketBAI o Verifactu:
  • Ragione sociale
  • Numero fiscale spagnolo (NIF)
  • Territorio
  • Email e indirizzo
  • Inoltre, informazioni sul rappresentante per le aziende
• Il contenuto del documento di fattura, inclusi:
  • Il dettaglio delle voci per tutte le transazioni, incluse aliquote IVA, quantità e prezzo
  • Le informazioni sul destinatario (ragione sociale, numero di identificazione spagnolo o internazionale e indirizzo) per transazioni B2B o B2C arricchite

Avrai anche bisogno di uno strumento per effettuare richieste HTTP, come cURL (riga di comando), Postman o il tuo codice applicativo.

Flusso di lavoro di integrazione

Il diagramma seguente illustra il flusso di lavoro e mette in evidenza i passaggi essenziali necessari per completare con successo l’integrazione. Ogni riquadro si collega direttamente al corrispondente passaggio di configurazione riportato di seguito.

Configurazione passo per passo

1. Registrarsi su HUB

   Inizia registrandoti su fiskaly HUB. La creazione di un account è il primo passaggio, dopodiché puoi procedere con la configurazione della struttura organizzativa della tua azienda nel nostro sistema.

   💡Non ancora pronto per la produzione?

   Puoi iniziare con l’ambiente TEST per esplorare l’API senza influire su dati reali. Le chiavi API generate nell’ambiente TEST creeranno risorse TEST, mentre quelle dell’ambiente LIVE creeranno risorse LIVE.

   📘Note

   Per impostazione predefinita, il tuo account inizia nell’ambiente TEST. Per passare alla produzione, contatta il nostro team di vendita per abilitare l’ambiente LIVE per la tua prima organizzazione. Le risorse create nell’ambiente TEST non vengono trasferite all’ambiente LIVE. Una volta che hai almeno un’organizzazione LIVE, puoi passare ulteriori organizzazioni a LIVE senza contattare le vendite. L’ambiente TEST rimane sempre disponibile.

2. Creare la prima organizzazione

   Continua creando la tua prima organizzazione tramite HUB. Questa organizzazione rappresenterà il fornitore POS o il commerciante con il proprio sistema POS. In questa fase dovrai includere un indirizzo di fatturazione. Questo indirizzo viene utilizzato solo per i fini di fatturazione di fiskaly. In HUB, questa organizzazione è denominata Group.

   Un’organizzazione principale rappresenta un fornitore POS o un commerciante con il proprio sistema POS. Un’organizzazione gestita rappresenta un commerciante. Ad esempio, se l’organizzazione principale è un fornitore POS, ogni organizzazione gestita rappresenta un singolo commerciante (contribuente) con il proprio NIF e territorio fiscale.

   📘Note

   Il territorio fiscale rilevante è determinato dall’indirizzo legale in cui è registrata l’azienda, non dalla posizione fisica di un negozio.

1. Creare organizzazione/i gestita/e

   Dopo aver stabilito la tua prima organizzazione, crea le organizzazioni gestite. Ogni organizzazione gestita rappresenta un commerciante, consentendoti di gestirli separatamente. In HUB, un’organizzazione gestita è denominata Organization UNIT.

   💡Automatizzare con la Management API

   Se prevedi di integrare molti commercianti, utilizza l’endpoint createOrganization della Management API e passa l’ID dell’organizzazione principale nel campo managed_by_organization_id per automatizzare il processo.

2. Creare la chiave API

   Genera una chiave API all’interno di ogni organizzazione gestita. Questo può essere fatto tramite HUB (Impostazioni → Chiavi API → CREA CHIAVE API) o tramite l’endpoint createApiKey della Management API.

   ⚠️Conserva le tue credenziali in modo sicuro

   Il segreto API viene mostrato solo una volta. Assicurati di copiarlo e salvarlo in un luogo sicuro prima di chiudere la finestra di dialogo.

   Questo paio di chiave API e segreto è necessario per generare un token di accesso, utilizzato per tutte le successive chiamate all’API SIGN ES. Utilizza le credenziali per ottenere un token di accesso prima di continuare. Tieni presente che tutti i corpi delle richieste SIGN ES utilizzano un wrapper content.

   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();

   La risposta contiene un access_token che devi includere come token Bearer nell’intestazione Authorization di tutte le richieste successive.

1. Aggiungere le informazioni del contribuente

   Dopo l’autenticazione, aggiungi le informazioni del contribuente al sistema. Il contribuente rappresenta l’entità soggetta alle normative TicketBAI o Verifactu.

   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",
           },
         },
       }),
     }
   );

   ⚠️Il territorio determina la normativa

   Assicurati che il campo territory corrisponda all’indirizzo legale del contribuente. SIGN ES applica automaticamente la legislazione corrispondente in base a questo valore.

   Verifactu: SPAIN_OTHER (Spagna continentale), CANARY_ISLANDS, CEUTA, MELILLA

   TicketBAI: ARABA, BIZKAIA, GIPUZKOA

   Attualmente nessuna normativa fiscale si applica a NAVARRE.

   Questo è un passaggio di conformità per garantire che tutte le fatture generate siano in linea con le normative fiscali e contengano tutti i dati necessari del contribuente.

2. Creare il firmatario

   Crea un firmatario per ogni organizzazione gestita. Il firmatario è responsabile della firma elettronica delle fatture.

   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: {},
       }),
     }
   );

   Ogni firmatario richiede un certificato. La gestione del certificato dipende dalla normativa.

   Verifactu: Un certificato elettronico gestito da fiskaly viene assegnato automaticamente durante la creazione del firmatario. fiskaly è registrata come collaboratore sociale presso l’AEAT per Verifactu, per cui il contribuente deve firmare un accordo di collaborazione sociale con fiskaly. Consulta Collaborazione sociale per i dettagli.

   TicketBAI: Un certificato dispositivo viene assegnato automaticamente durante la creazione del firmatario, a meno che non si fornisca il proprio certificato dispositivo esterno. Il certificato può essere recuperato dalla risposta API. Se i tuoi clienti si trovano nei Paesi Baschi, assicurati di inviare loro la guida alla registrazione di fiskaly in modo che possano registrare correttamente i certificati dispositivo presso l’autorità fiscale competente.

3. Creare i client

   Crea un client per ogni dispositivo POS o dispositivo di fatturazione utilizzato all’interno della tua organizzazione. Il client deve essere collegato a un firmatario.

   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. Creare le fatture

   Con tutti i passaggi precedenti completati, sei ora pronto per creare fatture. Questo è il passaggio finale in cui le fatture vengono generate e firmate. SIGN ES garantisce che tutte le fatture siano conformi a TicketBAI nei Paesi Baschi e a Verifactu nel resto del territorio spagnolo.

   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",
               },
             },
           ],
         },
       }),
     }
   );

   La risposta include i dati della fattura firmata con tutte le informazioni conformi richieste dalla normativa fiscale applicabile.

   📘Importante

   Per la conformità con Verifactu, assicurati che un accordo di collaborazione sociale valido sia firmato dal contribuente prima di iniziare a emettere fatture. Maggiori informazioni nella sezione Collaborazione sociale.

   Consulta le normative di fatturazione in Spagna per ulteriori informazioni sulla creazione di fatture.

Ricevuta digitale

Dopo aver creato una fattura, puoi generare una ricevuta digitale utilizzando l’endpoint per le ricevute digitali. L’URL restituito può essere mostrato come codice QR al consumatore al momento del pagamento, senza bisogno di stampare una ricevuta fisica. Questo riduce i costi, supporta l’ambiente e aggiunge un nuovo punto di contatto con il cliente per il commerciante.

Per saperne di più sulle ricevute digitali e su come migliorare la fidelizzazione dei clienti attraverso l’ecosistema di partner fiskaly, contattaci all’indirizzo sales@fiskaly.com. Consulta la guida alle ricevute digitali per i dettagli completi.

💡Automatizzare la configurazione

Questa intera sequenza di richieste può essere integrata in una soluzione di provisioning che non richiede alcuna interazione manuale da parte dell’utente. I dettagli di implementazione dipendono da te.

Prossimi passi

Riferimento API SIGN ES

Documentazione API completa per l'endpoint SIGN ES v1: tutte le risorse, i parametri e le risposte.

Conformità delle fatture

Scopri i requisiti di conformità per le fatture TicketBAI e Verifactu.

Certificati elettronici

Comprendi la gestione dei certificati, gli accordi di collaborazione sociale e i certificati dispositivo.

Glossario

Riferimento dei termini e concetti chiave utilizzati nella documentazione SIGN ES.