Schritt-für-Schritt-Integrationsprozess

Diese Anleitung führt Sie durch den gesamten Integrationsprozess für fiskaly SIGN ES, von der Kontoregistrierung bis zur Ausstellung Ihrer ersten signierten Rechnung. Am Ende werden Sie einen Steuerpflichtigen, einen Unterzeichner und einen Client konfiguriert haben, der bereit ist, steuerlich konforme Rechnungen für Spanien zu erstellen.

📘Bereits SIGN DE im Einsatz?

Wenn Sie bereits mit fiskaly SIGN DE integriert sind, wurde der Prozessablauf so gestaltet, dass er über beide APIs hinweg konsistent ist. Weitere Informationen zu den Unterschieden und Gemeinsamkeiten zwischen den beiden APIs finden Sie im Leitfaden für SIGN DE-Kunden.

Überblick

Bevor Sie mit der Einrichtung beginnen, folgt eine Übersicht dessen, was Sie benötigen:

🏢

Organisation

Ihre übergeordnete Einheit in fiskaly. Verwaltete Organisationen repräsentieren einzelne Händler.

🔑

API-Schlüssel & Secret

In HUB generierte Zugangsdaten, die für alle nachfolgenden API-Anfragen zur Authentifizierung verwendet werden.

🧾

Steuerpflichtiger

Die Einheit, die den TicketBAI- oder Verifactu-Vorschriften unterliegt, mit Steuernummer und Gebiet.

🔏

Unterzeichner

Verantwortlich für die elektronische Signatur von Rechnungen. Zertifikate werden automatisch verwaltet.

💻

Client

Repräsentiert ein POS-Terminal oder ein Rechnungsstellungsgerät, das Rechnungen über einen Unterzeichner erstellt.

📄

Rechnung

Ein signierter Steuerbeleg. Sobald Ihre Einrichtung abgeschlossen ist, können Sie konforme Rechnungen erstellen.

Voraussetzungen

📘Bevor Sie beginnen

Sie benötigen ein fiskaly-Konto und Zugang zum fiskaly HUB. Wenn Sie noch kein Konto haben, registrieren Sie sich hier.

Um SIGN ES zu verwenden, benötigen Sie folgende Informationen:

Für den Steuerpflichtigen, der den TicketBAI- oder Verifactu-Vorschriften unterliegt:
- Firmenname
- Spanische Steuernummer (NIF)
- Gebiet
- E-Mail und Adresse
- Zusätzlich Vertreterinformationen für Unternehmen
Den Inhalt des Rechnungsdokuments, einschließlich:
- Die detaillierten Positionen für alle Transaktionen, einschließlich MwSt.-Sätze, Menge und Preis
- Die Empfängerinformationen (Firmenname, spanische oder internationale Identifikationsnummer und Adresse) für B2B- oder angereicherte B2C-Transaktionen

Sie benötigen außerdem ein Tool für HTTP-Anfragen – zum Beispiel cURL (Befehlszeile), Postman oder Ihren eigenen Anwendungscode.

Integrationsablauf

Das folgende Diagramm veranschaulicht den Ablauf und hebt die wesentlichen Schritte hervor, die für eine erfolgreiche Integration erforderlich sind. Jede Kachel verweist direkt auf den entsprechenden Einrichtungsschritt unten.

Schritt-für-Schritt-Einrichtung

In HUB registrieren
Beginnen Sie mit der Registrierung im fiskaly HUB. Die Erstellung eines Kontos ist der erste Schritt. Danach können Sie mit der Einrichtung der Organisationsstruktur für Ihr Unternehmen in unserem System fortfahren.
💡Noch nicht bereit für die Produktion?
Sie können mit der TEST-Umgebung beginnen, um die API ohne Auswirkung auf Echtdaten zu erkunden. Mit API-Schlüsseln, die in der TEST-Umgebung generiert werden, werden TEST-Ressourcen erstellt, während solche aus der LIVE-Umgebung LIVE-Ressourcen erstellen.
📘Note
Standardmäßig startet Ihr Konto in der TEST-Umgebung. Um live zu gehen, wenden Sie sich an unser Vertriebsteam, um die LIVE-Umgebung für Ihre erste Organisation zu aktivieren. In der TEST-Umgebung erstellte Ressourcen werden nicht in die LIVE-Umgebung übertragen. Sobald Sie mindestens eine LIVE-Organisation haben, können Sie weitere Organisationen ohne Kontaktaufnahme mit dem Vertrieb auf LIVE umstellen. Die TEST-Umgebung bleibt jederzeit verfügbar.
Erste Organisation erstellen
Erstellen Sie zunächst Ihre erste Organisation über HUB. Diese Organisation repräsentiert den POS-Anbieter oder Händler mit seinem eigenen POS-System. Sie müssen an dieser Stelle eine Rechnungsadresse angeben. Diese Adresse wird ausschließlich für Abrechnungszwecke von fiskaly verwendet. In HUB wird diese Organisation als Group bezeichnet.
Eine Hauptorganisation repräsentiert einen POS-Anbieter oder Händler mit seinem eigenen POS-System. Eine verwaltete Organisation repräsentiert einen Händler. Wenn die Hauptorganisation beispielsweise ein POS-Anbieter ist, repräsentiert jede verwaltete Organisation einen einzelnen Händler (Steuerpflichtigen) mit seiner eigenen NIF und seinem Steuergebiet.
📘Note
Das relevante Steuergebiet wird durch die Rechtsadresse des Unternehmens bestimmt – nicht durch den physischen Standort eines Geschäfts.

Verwaltete Organisation(en) erstellen
Erstellen Sie nach der Einrichtung Ihrer ersten Organisation verwaltete Organisationen. Jede verwaltete Organisation repräsentiert einen Händler und ermöglicht es Ihnen, diese separat zu verwalten. In HUB wird eine verwaltete Organisation als Organization UNIT bezeichnet.
💡Mit der Management API automatisieren
Wenn Sie viele Händler einbinden möchten, verwenden Sie den createOrganization-Endpunkt der Management API und übergeben Sie die ID der Hauptorganisation im Feld managed_by_organization_id, um den Prozess zu automatisieren.
API-Schlüssel erstellen
Generieren Sie einen API-Schlüssel innerhalb jeder verwalteten Organisation. Dies kann über HUB (Einstellungen → API-Schlüssel → API-SCHLÜSSEL ERSTELLEN) oder den createApiKey-Endpunkt der Management API erfolgen.
⚠️Zugangsdaten sicher aufbewahren
Das API-Secret wird nur einmal angezeigt. Stellen Sie sicher, dass Sie es kopieren und an einem sicheren Ort speichern, bevor Sie den Dialog schließen.
Dieses API-Schlüssel- und Secret-Paar wird benötigt, um ein Zugriffstoken zu generieren, das für alle nachfolgenden SIGN ES-API-Aufrufe verwendet wird. Verwenden Sie die Zugangsdaten, um ein Zugriffstoken zu erhalten, bevor Sie fortfahren. Beachten Sie, dass alle SIGN ES-Anfragetexte einen content-Envelope-Wrapper verwenden.
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" } }'
Die Antwort enthält ein access_token, das Sie als Bearer-Token im Authorization-Header aller folgenden Anfragen angeben müssen.

Steuerpflichtige Informationen hinzufügen

Nach der Authentifizierung fügen Sie die Informationen des Steuerpflichtigen in das System ein. Der Steuerpflichtige repräsentiert die Einheit, die den TicketBAI- oder Verifactu-Vorschriften unterliegt.

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

⚠️Das Gebiet bestimmt die Vorschrift

Stellen Sie sicher, dass das Feld territory mit der Rechtsadresse des Steuerpflichtigen übereinstimmt. SIGN ES wendet die entsprechende Gesetzgebung automatisch auf Basis dieses Wertes an.

Verifactu: SPAIN_OTHER (Festlandspanien), CANARY_ISLANDS, CEUTA, MELILLA

TicketBAI: ARABA, BIZKAIA, GIPUZKOA

Für NAVARRE gilt derzeit keine Steuervorschrift.

Dies ist ein Konformitätsschritt, um sicherzustellen, dass alle generierten Rechnungen mit den Steuervorschriften übereinstimmen und alle erforderlichen Steuerpflichtigenangaben enthalten.

Unterzeichner erstellen
Erstellen Sie einen Unterzeichner für jede verwaltete Organisation. Der Unterzeichner ist für die elektronische Signatur von Rechnungen verantwortlich.
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": {} }'
Jeder Unterzeichner benötigt ein Zertifikat. Die Zertifikatsverwaltung hängt von der jeweiligen Vorschrift ab.
Verifactu: Ein von fiskaly verwaltetes elektronisches Zertifikat wird bei der Erstellung des Unterzeichners automatisch zugewiesen. fiskaly ist als sozialer Mitarbeiter bei der AEAT für Verifactu registriert, wofür der Steuerpflichtige eine Vereinbarung zur sozialen Zusammenarbeit mit fiskaly unterzeichnen muss. Weitere Informationen finden Sie unter Soziale Zusammenarbeit.
TicketBAI: Ein Gerätezertifikat wird bei der Erstellung des Unterzeichners automatisch zugewiesen, sofern Sie kein eigenes externes Gerätezertifikat bereitstellen. Das Zertifikat kann aus der API-Antwort abgerufen werden. Wenn sich Ihre Kunden im Baskenland befinden, stellen Sie sicher, dass Sie ihnen die Registrierungsanleitung von fiskaly zusenden, damit sie die Gerätezertifikate ordnungsgemäß bei der zuständigen Steuerbehörde registrieren können.

Clients erstellen

Erstellen Sie einen Client für jedes POS-Gerät oder Rechnungsstellungsgerät, das in Ihrer Organisation verwendet wird. Der Client muss mit einem Unterzeichner verknüpft sein.

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

Rechnungen erstellen

Nachdem alle vorherigen Schritte abgeschlossen sind, können Sie jetzt Rechnungen erstellen. Dies ist der letzte Schritt, bei dem Rechnungen generiert und signiert werden. SIGN ES stellt sicher, dass alle Rechnungen mit TicketBAI im Baskenland und mit Verifactu im restlichen spanischen Gebiet konform sind.

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

Die Antwort enthält die signierten Rechnungsdaten mit allen konformen Informationen, die von der jeweils geltenden Steuervorschrift verlangt werden.

📘Wichtig

Stellen Sie für die Konformität mit Verifactu sicher, dass eine gültige Vereinbarung zur sozialen Zusammenarbeit vom Steuerpflichtigen unterzeichnet wurde, bevor mit der Rechnungsausstellung begonnen wird. Weitere Informationen finden Sie im Abschnitt Soziale Zusammenarbeit.

Weitere Informationen zur Rechnungserstellung finden Sie in den Rechnungsstellungsvorschriften in Spanien.

Digitaler Beleg

Nach dem Erstellen einer Rechnung können Sie mit dem Endpunkt für digitale Belege einen digitalen Beleg generieren. Die zurückgegebene URL kann dem Verbraucher beim Bezahlvorgang als QR-Code angezeigt werden – ohne dass ein physischer Beleg ausgedruckt werden muss. Dies reduziert Kosten, schont die Umwelt und schafft einen neuen Kundenkontaktpunkt für den Händler.

Um mehr über digitale Belege und wie Sie die Kundenbindung durch das fiskaly-Partner-Ökosystem verbessern können zu erfahren, nehmen Sie unter sales@fiskaly.com Kontakt auf. Weitere Einzelheiten finden Sie im Leitfaden für digitale Belege.

💡Einrichtung automatisieren

Diese gesamte Abfolge von Anfragen kann in eine Bereitstellungslösung integriert werden, die keine manuelle Benutzerinteraktion erfordert. Die Implementierungsdetails liegen bei Ihnen.

Nächste Schritte

SIGN ES API-Referenz

Vollständige API-Dokumentation für den SIGN ES v1-Endpunkt — alle Ressourcen, Parameter und Antworten.

Rechnungskonformität

Erfahren Sie mehr über die Konformitätsanforderungen für TicketBAI- und Verifactu-Rechnungen.

Elektronische Zertifikate

Verstehen Sie die Zertifikatsverwaltung, Vereinbarungen zur sozialen Zusammenarbeit und Gerätezertifikate.

Glossar

Referenz zu wichtigen Begriffen und Konzepten, die in der SIGN ES-Dokumentation verwendet werden.

Was this page helpful?