Schritt-für-Schritt-Integration

⚠️Vorschau

SIGN ES (Unified API) ist derzeit in der TEST-Umgebung für die erste Entwicklung und Erprobung verfügbar, wobei in diesem Stadium nur ein begrenzter Funktionsumfang getestet werden kann. Die Produktion ist noch nicht aktiviert. Für den Produktionseinsatz verwenden Sie bitte die Spezialisierte SIGN ES API.

Um den Integrationsprozess zu beginnen, folgen Sie bitte den hier bereitgestellten detaillierten Schritt-für-Schritt-Anweisungen.

Das begleitende Diagramm veranschaulicht den Workflow und hebt die wesentlichen Schritte hervor, die für eine erfolgreiche Integration erforderlich sind. Dazu müssen Sie unsere SIGN ES (Unified API) verwenden.

1. Auf dem HUB registrieren

   Beginnen Sie mit der Registrierung auf dem fiskaly HUB. Weitere Hinweise zu den ersten Schritten finden Sie in unserem Abschnitt HUB – Erste Schritte.

2. Konto und Organisation GROUP erstellen

   Das Erstellen eines fiskaly-Kontos ist der erste Schritt, danach können Sie die erste organisatorische Struktur für Ihr Unternehmen einrichten und Ihren API-Key generieren.

   Das Konto repräsentiert den PoS-Anbieter oder einen Einzelhändler, der sein eigenes PoS-System betreibt. Es ist die übergeordnete Organisation in der Struktur.

   Nach der Erstellung Ihres fiskaly-Kontos gelangen Sie zur Organisationsauswahl, wo Sie Ihre Gruppe erstellen können.

   Eine Gruppe ist eine mittlere Ebene innerhalb eines Kontos, die Ihnen hilft, mehrere Units in logische Cluster zu organisieren.

3. API-Key erstellen

   Der nächste Schritt ist die Generierung eines API-Keys für Ihre Organisation über den HUB. Dieses API-Key- und Secret-Paar ist erforderlich, um Ihre erste Organisation vom Typ UNIT zu erstellen (Schritt 5).

   💡TEST- vs. LIVE-Umgebung

   API-Keys, die in der TEST-Umgebung (https://test.api.fiskaly.com) generiert werden, erstellen TEST-Ressourcen, während diejenigen aus der LIVE-Umgebung (https://live.api.fiskaly.com) LIVE-Ressourcen erstellen.

1. Token erstellen

   Ab diesem Schritt verwenden Sie die SIGN ES (Unified API).

   Rufen Sie den Endpunkt createToken mit dem API-Key und Secret aus Schritt 3 auf, um ein bearer-Token zu erhalten. Fügen Sie dieses Token in den Authorization-Header der Schritte 5 und 6 ein.

2. Organisation UNIT erstellen

   Erstellen Sie über den Endpunkt createOrganization eine Organisation vom Typ UNIT. Eine UNIT repräsentiert eine einzelne juristische Person (Händler). Sie müssen für jede von Ihnen verwaltete Steuerpflichtigendarstellung eine Organisation UNIT erstellen.

   Die Verwendung des in Schritt 4 generierten Bearer-Tokens mit dem für Ihre Gruppe erstellten API-Key und Secret stellt sicher, dass die UNIT korrekt unter dieser Gruppe in der Hierarchie eingeordnet ist.

3. Subject (API-Key) erstellen

   Erstellen Sie über den Endpunkt createSubject ein Subject vom Typ API_KEY für die Organisation UNIT.

   Um das Subject (API-Key) mit Ihrer UNIT zu verknüpfen, fügen Sie den Header X-Scope-Identifier mit der id der Organisation UNIT in Ihrer Anfrage ein.

4. Neues Token erstellen

   Erstellen Sie ein Token mit dem soeben generierten Subject-API-Key und Secret. Dieses Bearer-Token wird für alle nachfolgenden Schritte zur Erstellung von Ressourcen innerhalb der entsprechenden Organisation UNIT verwendet.

1. Steuerpflichtigen erstellen

   Jetzt sind Sie bereit, die für die Fiskalisierung in Spanien erforderlichen operativen Teile zu erstellen.

   Verwenden Sie den Endpunkt createTaxpayer, um die Darstellung eines Steuerpflichtigen wie folgt zu erstellen:

   • Legen Sie den Steuerpflichtigen als Typ Company (juristische Person) oder Individual (natürliche Person) fest.
   • Geben Sie die spanische NIF (Número de Identificación Fiscal) des Steuerpflichtigen an.
   • Das Steuergebiet des Steuerpflichtigen bestimmt, ob Verifactu, SII oder TicketBAI gilt — siehe die Einführung zu SIGN ES für die Zuordnung dieser Vorschriften zu den spanischen Steuergebieten.

   Sobald Sie einen Taxpayer erstellt haben, ist sein Zustand standardmäßig auf ACQUIRED gesetzt. Um ihn voll funktionsfähig zu machen, aktualisieren Sie den Zustand über den Endpunkt updateTaxpayer auf COMMISSIONED.

2. Standort erstellen

   📘Note

   Ein HEAD_OFFICE-Standort wird automatisch bei der Erstellung des Steuerpflichtigen angelegt und teilt sich dieselbe UUID wie der Steuerpflichtige. Für Fiskalisierungszwecke empfehlen wir jedoch die Erstellung eines separaten Standorts vom Typ BRANCH (er kann dieselbe Adresse haben). Bei mehreren Standorten sollte für jeden ein entsprechender Branch erstellt werden.

   Erstellen Sie für jeden Betriebsstandort über den Endpunkt createLocation einen Standort vom Typ BRANCH.

   Sobald ein Standort erstellt ist, ist sein Zustand standardmäßig auf ACQUIRED gesetzt. Aktualisieren Sie den Zustand über den Endpunkt updateLocation auf COMMISSIONED, bevor Sie fortfahren.

3. System erstellen

   Der Endpunkt createSystem ermöglicht Ihnen, eine Abstraktion jedes für Steueroperationen verwendeten Electronic Recording Systems zu erstellen. Jede Kasse oder jeder Point of Sale muss als neues System vom Typ FISCAL_DEVICE angelegt werden.

   • Ein System wird mit einem bestimmten, zuvor erstellten Standort vom Typ BRANCH verbunden.

   Sobald ein System erstellt ist, ist sein Zustand standardmäßig auf ACQUIRED gesetzt. Um Records erstellen zu können, muss sein Zustand über den Endpunkt updateSystem auf COMMISSIONED aktualisiert werden.

   📘Abrechnungshinweis

   Für die meisten Verträge sind Systeme die Abrechnungseinheiten bei fiskaly. Ein System wird abrechnungsrelevant, sobald sich sein Status in der LIVE-Umgebung von ACQUIRED zu COMMISSIONED ändert. Ressourcen in der TEST-Umgebung werden nicht abgerechnet. Die genauen Abrechnungsbedingungen entnehmen Sie bitte Ihrem Vertrag mit fiskaly.

4. Beleg erstellen

   Für jeden im System durchgeführten Geschäftsvorgang muss der Endpunkt createRecord zweimal in Folge aufgerufen werden: zuerst zur Aufzeichnung der Absicht, eine Transaktion zu starten, und dann zur Übermittlung der Transaktionsdaten.

   Teil A) Intention

   Ein Record vom Typ INTENTION enthält die Verknüpfung mit dem System, das die Transaktion durchführt, und eine Operation vom Typ TRANSACTION, die die Absicht des Systems darstellt, eine Transaktion aufzuzeichnen.

   Teil B) Transaction

   Ein Record vom Typ TRANSACTION ist mit der zuvor erstellten INTENTION verknüpft und enthält die Transaktionsdaten, die anschließend gemäß der für den Steuerpflichtigen geltenden Vorschrift (Verifactu, SII oder TicketBAI) signiert und übermittelt werden.

   📘Note

   Alle in der LIVE-Umgebung erstellten Records stellen steuerlich relevante Dokumente dar und müssen stets tatsächliche Transaktionen widerspiegeln. Verwenden Sie die designierte TEST-Umgebung für Integrationstests.