Avvio rapido Spagna

Questo avvio rapido ti guida nella firma della tua prima fattura conforme con fiskaly SIGN ES, coprendo sia TicketBAI (Paesi Baschi) che Verifactu (resto della Spagna).

Prima di iniziare

SIGN ES è l’API di fiskaly solo software, indipendente dalla piattaforma per la conformità fiscale spagnola. Copre Verifactu e SII nella maggior parte della Spagna, TicketBAI nei Paesi Baschi e NaTicket in Navarra (in arrivo) — il tutto attraverso un’unica API REST.

VF

Verifactu

Normativa nazionale per la maggior parte della Spagna ai sensi della Legge antifrode, Decreto Reale 1007/2023 e Ordine HAC/1177/2024.

TB

TicketBAI

Framework di fiscalizzazione dei Paesi Baschi per Álava, Bizkaia e Gipuzkoa.

SII

SII

Dichiarazione elettronica IVA all'AEAT per i grandi contribuenti in Spagna continentale. Incompatibile con Verifactu.

NT

NaTicket

Il sistema di controllo fatture della Navarra, annunciato a settembre 2025. Previsto per il 2026–2027.

API

Flusso API in tempo reale

SIGN ES genera l'XML della fattura, lo firma, lo concatena e lo trasmette all'autorità fiscale competente.

Normativa	Si applica a	Output principale
Verifactu	Maggior parte della Spagna, esclusi Paesi Baschi e attualmente Navarra	XML firmato, trasmissione AEAT in tempo reale, dicitura Verifactu e codice QR
TicketBAI	Álava, Bizkaia, Gipuzkoa	XML firmato, trasmissione all’autorità fiscale regionale, ID TicketBAI e codice QR
SII	Spagna continentale (grandi contribuenti IVA)	Registrazioni IVA elettroniche trasmesse all’AEAT entro 4 giorni; nessun codice QR
NaTicket	Navarra (in arrivo, ~2026–2027)	Previsto: XML firmato trasmesso alla Hacienda Foral de Navarra

💡Hai bisogno prima della panoramica legale e di processo?

Consulta l’Introduzione per il contesto completo su Verifactu, TicketBAI, BATUZ e LROE prima di iniziare i passi di integrazione.

Prerequisiti

• Un account fiskaly con un’organizzazione spagnola (registrati su hub.fiskaly.com)
• Una chiave API e un segreto generati nell’ambiente TEST
• Informazioni sul contribuente: nome legale, NIF (codice fiscale) e territorio

⚠️Conserva le credenziali in modo sicuro

Il tuo segreto API viene mostrato una sola volta. Salvalo immediatamente in un luogo sicuro.

Passi

1. Autenticarsi

   cURLJavaScriptPythonJavaC#

   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 BASE = "https://test.es.sign.fiskaly.com/api/v1";
   
   const response = await fetch(`${BASE}/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();
   const headers = { "Authorization": `Bearer ${access_token}`, "Content-Type": "application/json" };

   import requests, uuid
   BASE = "https://test.es.sign.fiskaly.com/api/v1"
   resp = requests.post(f"{BASE}/auth", json={"content": {"api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET"}})
   access_token = resp.json()["access_token"]
   hdrs = {"Authorization": f"Bearer {access_token}"}

   // POST https://test.es.sign.fiskaly.com/api/v1/auth
   // Body: {"content":{"api_key":"...","api_secret":"..."}}
   // Response: { "access_token": "..." }

   using var client = new HttpClient();
   var authResp = await client.PostAsJsonAsync("https://test.es.sign.fiskaly.com/api/v1/auth", new { content = new { api_key = "YOUR_API_KEY", api_secret = "YOUR_API_SECRET" } });
   var token = (await authResp.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("access_token").GetString();

   📘Note

   SIGN ES racchiude tutti i corpi delle richieste in un envelope content. Questo vale per l’autenticazione e tutte le chiamate API successive.

2. Creare un contribuente

   Registra le informazioni del contribuente. Il territory determina quale normativa si applica:

   • ARABA, BIZKAIA, GIPUZKOA → TicketBAI
   • SPAIN_OTHER, CANARY_ISLANDS, CEUTA, MELILLA → Verifactu

   cURLJavaScriptPythonJavaC#

   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"}}}'

   await fetch(`${BASE}/taxpayer`, { method: "PUT", headers, body: JSON.stringify({ content: { issuer: { tax_number: "B12345678", legal_name: "My Company S.L." }, territory: "SPAIN_OTHER", sii: { state: "ENABLED" } } }) });

   requests.put(f"{BASE}/taxpayer", headers=hdrs, json={"content": {"issuer": {"tax_number": "B12345678", "legal_name": "My Company S.L."}, "territory": "SPAIN_OTHER", "sii": {"state": "ENABLED"}}})

   // PUT /taxpayer
   // Body: {"content":{"issuer":{"tax_number":"B12345678","legal_name":"My Company S.L."},"territory":"SPAIN_OTHER","sii":{"state":"ENABLED"}}}

   await client.PutAsJsonAsync($"{BASE}/taxpayer", new { content = new { issuer = new { tax_number = "B12345678", legal_name = "My Company S.L." }, territory = "SPAIN_OTHER", sii = new { state = "ENABLED" } } });

3. Creare un signer

   Il signer gestisce la firma elettronica delle fatture. Un certificato viene assegnato automaticamente in base al territorio.

   cURLJavaScriptPythonJavaC#

   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();
   await fetch(`${BASE}/signers/${signerId}`, { method: "PUT", headers, body: JSON.stringify({ content: {} }) });

   signer_id = str(uuid.uuid4())
   requests.put(f"{BASE}/signers/{signer_id}", headers=hdrs, json={"content": {}})

   // PUT /signers/{signerId}
   // Body: {"content":{}}

   var signerId = Guid.NewGuid().ToString();
   await client.PutAsJsonAsync($"{BASE}/signers/{signerId}", new { content = new {} });

4. Creare un client

   cURLJavaScriptPythonJavaC#

   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": "'${SIGNER_ID}'"}}'

   const clientId = crypto.randomUUID();
   await fetch(`${BASE}/clients/${clientId}`, { method: "PUT", headers, body: JSON.stringify({ content: { signer_id: signerId } }) });

   client_id = str(uuid.uuid4())
   requests.put(f"{BASE}/clients/{client_id}", headers=hdrs, json={"content": {"signer_id": signer_id}})

   // PUT /clients/{clientId}
   // Body: {"content":{"signer_id":"<signerId>"}}

   var clientId = Guid.NewGuid().ToString();
   await client.PutAsJsonAsync($"{BASE}/clients/{clientId}", new { content = new { signer_id = signerId } });

5. Creare la prima fattura

   cURLJavaScriptPythonJavaC#

   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 invoice = await fetch(`${BASE}/clients/${clientId}/invoices/${invoiceId}`, { method: "PUT", headers, 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" } }] } }) }).then(r => r.json());
   console.log("Signed invoice:", invoice);

   invoice_id = str(uuid.uuid4())
   invoice = requests.put(f"{BASE}/clients/{client_id}/invoices/{invoice_id}", headers=hdrs, json={"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"}}]}}).json()

   // PUT /clients/{clientId}/invoices/{invoiceId}
   // Body: {"content":{"type":"SIMPLIFIED","number":"INV-001",...}}
   // Response contains the signed, compliant invoice data

   var invoiceId = Guid.NewGuid().ToString();
   var inv = await client.PutAsJsonAsync($"{BASE}/clients/{clientId}/invoices/{invoiceId}", new { content = new { type = "SIMPLIFIED", number = "INV-001", text = "Sales receipt", full_amount = "12.10", items = new[] { new { text = "Product A", quantity = "1", unit_amount = "10.00", full_amount = "12.10", system = new { type = "REGULAR", rate = "21.00" } }} } });

   La risposta contiene i dati della fattura firmata e conforme, incluse tutte le informazioni richieste dalle normative TicketBAI o Verifactu.

Eseguire lo script

Vuoi eseguire automaticamente tutti i passaggi? Scarica ed esegui il nostro script di avvio rapido:

BashNode.js

# Scarica ed esegui
curl -O https://workspace.fiskaly.com/scripts/sign-es-quickstart.sh
export API_KEY="your_api_key"
export API_SECRET="your_api_secret"
bash sign-es-quickstart.sh

# Scarica ed esegui
curl -O https://workspace.fiskaly.com/scripts/sign-es-quickstart.mjs
API_KEY="your_key" API_SECRET="your_secret" node sign-es-quickstart.mjs

Prossimi passi

Guida di integrazione completa

Guida completa passo dopo passo inclusa la configurazione dell'organizzazione

Conformità TicketBAI

Requisiti fattura per i Paesi Baschi

Conformità Verifactu

Requisiti fattura per la Spagna continentale