Schnellstart Spanien

Dieser Schnellstart führt Sie durch die Signierung Ihrer ersten konformen Rechnung mit fiskaly SIGN ES und deckt sowohl TicketBAI (Baskenland) als auch Verifactu (restliches Spanien) ab.

Bevor Sie beginnen

SIGN ES ist fiskaly’s rein softwarebasierte, plattformunabhängige API für die spanische Fiskalkonformität. Sie deckt Verifactu und SII in den meisten Teilen Spaniens, TicketBAI im Baskenland und NaTicket in Navarra (in Kürze) — alles über eine REST-API ab.

Verifactu

Nationale Regulierung für die meisten Teile Spaniens gemäß dem Betrugsbekämpfungsgesetz, Königlichem Dekret 1007/2023 und Verordnung HAC/1177/2024.

TicketBAI

Baskisches Fiskalisierungsrahmenwerk für Álava, Bizkaia und Gipuzkoa.

SII

Elektronische Umsatzsteuermeldung an die AEAT für Großsteuerpflichtige in Spanien. Schließt Verifactu aus.

NaTicket

Navarras kommendes Rechnungskontrollsystem, angekündigt im September 2025. Erwartet ab 2026–2027.

API

Echtzeit-API-Ablauf

SIGN ES generiert Rechnungs-XML, signiert es, verkettet es und übermittelt es an die zuständige Steuerbehörde.

Regulierung	Gilt für	Hauptausgabe
Verifactu	Großteil Spaniens, außer Baskenland und derzeit Navarra	Signiertes XML, Echtzeit-AEAT-Übermittlung, Verifactu-Hinweis und QR-Code
TicketBAI	Álava, Bizkaia, Gipuzkoa	Signiertes XML, Übermittlung an regionale Steuerbehörde, TicketBAI-ID und QR-Code
SII	Spanien (Großsteuerpflichtige)	Elektronische Umsatzsteueraufzeichnungen, innerhalb von 4 Tagen an die AEAT übermittelt; kein QR-Code
NaTicket	Navarra (in Kürze, ~2026–2027)	Geplant: signiertes XML, übermittelt an die Hacienda Foral de Navarra

💡Zuerst die rechtliche und prozessuale Übersicht benötigt?

Lesen Sie die Einführung für den vollständigen Hintergrund zu Verifactu, TicketBAI, BATUZ und LROE, bevor Sie mit den Integrationsschritten beginnen.

Voraussetzungen

Ein fiskaly-Konto mit einer spanischen Organisation (Registrierung unter hub.fiskaly.com)
Ein im TEST-Umfeld generierter API-Schlüssel und Secret
Steuerpflichtigendaten: gesetzlicher Name, NIF (Steuernummer) und Gebiet

⚠️Anmeldedaten sicher aufbewahren

Ihr API-Secret wird nur einmal angezeigt. Speichern Sie es sofort an einem sicheren Ort.

Schritte

Authentifizieren

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 kapselt alle Anfrage-Bodys in einen content-Umschlag. Dies gilt für die Authentifizierung und alle nachfolgenden API-Aufrufe.

Steuerpflichtigen anlegen

Registrieren Sie die Steuerpflichtigendaten. Das territory bestimmt, welche Regulierung gilt:

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

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

Signer erstellen

Der Signer übernimmt die elektronische Signierung der Rechnungen. Ein Zertifikat wird automatisch basierend auf dem Gebiet zugewiesen.

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

Client erstellen

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

Erste Rechnung erstellen

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()
print("Signed:", invoice)

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

Die Antwort enthält die signierten, konformen Rechnungsdaten einschließlich aller Informationen, die gemäß den TicketBAI- oder Verifactu-Vorschriften erforderlich sind.

Skript ausführen

Möchten Sie alle Schritte automatisch durchlaufen? Laden Sie unser Schnellstart-Skript herunter und führen Sie es aus:

# Herunterladen und ausführen
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

# Herunterladen und ausführen
curl -O https://workspace.fiskaly.com/scripts/sign-es-quickstart.mjs
API_KEY="your_key" API_SECRET="your_secret" node sign-es-quickstart.mjs

Nächste Schritte

Vollständiger Integrationsleitfaden

Vollständige Schritt-für-Schritt-Anleitung einschließlich Organisationseinrichtung

TicketBAI-Konformität

Rechnungsanforderungen für das Baskenland

Verifactu-Konformität

Rechnungsanforderungen für das spanische Festland

Was this page helpful?