Démarrage rapide Espagne

Ce démarrage rapide vous guide pour signer votre première facture conforme avec fiskaly SIGN ES, couvrant à la fois TicketBAI (Pays Basque) et Verifactu (reste de l’Espagne).

Avant de commencer

SIGN ES est l’API de fiskaly uniquement logicielle, indépendante de la plateforme pour la conformité fiscale espagnole. Elle couvre Verifactu et SII dans la majeure partie de l’Espagne, TicketBAI au Pays Basque et NaTicket en Navarre (à venir) — le tout via une seule API REST.

VF

Verifactu

Réglementation nationale pour la majeure partie de l'Espagne en vertu de la Loi antifraude, du Décret royal 1007/2023 et de l'Ordre HAC/1177/2024.

TB

TicketBAI

Cadre de fiscalisation du Pays Basque pour l'Álava, la Biscaye et le Guipúzcoa.

SII

SII

Déclaration électronique de TVA à l'AEAT pour les grands contribuables en Espagne continentale. Incompatible avec Verifactu.

NT

NaTicket

Système de contrôle des factures de Navarre, annoncé en septembre 2025. Prévu pour 2026–2027.

API

Flux API en temps réel

SIGN ES génère le XML de la facture, le signe, le chaîne et le transmet à l'autorité fiscale concernée.

Réglementation	S’applique à	Sortie principale
Verifactu	Majeure partie de l’Espagne, excluant le Pays Basque et actuellement la Navarre	XML signé, transmission AEAT en temps réel, mention Verifactu et code QR
TicketBAI	Álava, Biscaye, Guipúzcoa	XML signé, transmission à l’autorité fiscale régionale, ID TicketBAI et code QR
SII	Espagne continentale (grands contribuables TVA)	Registres TVA électroniques transmis à l’AEAT sous 4 jours ; pas de code QR
NaTicket	Navarre (à venir, ~2026–2027)	Prévu : XML signé transmis à la Hacienda Foral de Navarre

💡Besoin d'abord de la présentation légale et de processus ?

Consultez l’Introduction pour le contexte complet sur Verifactu, TicketBAI, BATUZ et LROE avant de commencer les étapes d’intégration.

Prérequis

• Un compte fiskaly avec une organisation espagnole (inscrivez-vous sur hub.fiskaly.com)
• Une clé API et un secret générés dans l’environnement TEST
• Informations sur le contribuable : nom légal, NIF (numéro fiscal) et territoire

⚠️Stockez les identifiants en toute sécurité

Votre secret API n’est affiché qu’une seule fois. Stockez-le immédiatement dans un endroit sécurisé.

Étapes

1. S'authentifier

   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 encapsule tous les corps de requête dans une enveloppe content. Cela s’applique à l’authentification et à tous les appels API suivants.

2. Créer un contribuable

   Enregistrez les informations du contribuable. Le territory détermine quelle réglementation s’applique :

   • 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. Créer un signataire

   Le signataire gère la signature électronique des factures. Un certificat est automatiquement attribué en fonction du territoire.

   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. Créer 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. Créer votre première facture

   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 réponse contient les données de facture signée et conforme, incluant toutes les informations requises par les réglementations TicketBAI ou Verifactu.

Exécuter le script

Vous souhaitez exécuter toutes les étapes automatiquement ? Téléchargez et exécutez notre script de démarrage rapide :

BashNode.js

# Télécharger et exécuter
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

# Télécharger et exécuter
curl -O https://workspace.fiskaly.com/scripts/sign-es-quickstart.mjs
API_KEY="your_key" API_SECRET="your_secret" node sign-es-quickstart.mjs

Prochaines étapes

Guide d'intégration complet

Guide complet étape par étape incluant la configuration de l'organisation

Conformité TicketBAI

Exigences de facture pour le Pays Basque

Conformité Verifactu

Exigences de facture pour l'Espagne continentale