Schritt-für-Schritt-Integrationsprozess

B2B-E-Rechnungen

Erstellen und empfangen Sie rechtskonforme B2B-E-Rechnungen über alle unterstützten Netzwerke.

Länderübergreifende Unterstützung

Belgien, Deutschland und Italien mit integrierter länderspezifischer Compliance.

Unified API

Eine einzige Integration für E-Rechnungen in allen unterstützten Ländern mit einheitlichen Endpunkten.

Voraussetzungen

Stellen Sie vor dem Start sicher, dass Sie über Folgendes verfügen:

• Zugang zum fiskaly HUB (TEST-Umgebung)
• Grundlegendes Verständnis von REST-APIs und Authentifizierungsabläufen
• Ihre Unternehmensregistrierungsdaten für die Einrichtung des Taxpayers

📘Note

Wenn Sie bereits SIGN IT oder SIGN FR integriert haben, sind Ihnen die ersten Einrichtungsschritte in dieser Anleitung wahrscheinlich bereits vertraut und möglicherweise schon abgeschlossen. In diesem Fall können Sie direkt zu Schritt 10 springen, um die zusätzlich erforderlichen Schritte zu prüfen.

Integrationsablauf

📘Wichtig

Die gelb markierten Schritte müssen direkt im HUB durchgeführt werden, während die übrigen Schritte über die API abgewickelt werden. Jede Aktion im richtigen Kontext auszuführen ist ein wichtiger Schritt für eine erfolgreiche Integration.

* Step required for BE 🇧🇪 and DE 🇩🇪
* Not required for IT 🇮🇹

Einrichtung Schritt für Schritt

1. Schritt 1: Im HUB registrieren

   Registrieren Sie sich zunächst im fiskaly HUB.

   
2. Schritt 2: Account und Organisation GROUP erstellen

   Das Erstellen eines fiskaly Accounts ist der erste Schritt. Anschließend können Sie mit der Einrichtung der ersten Organisationsstruktur für Ihr Unternehmen fortfahren und Ihren API Key generieren.

   Der Account repräsentiert den Kassensystemanbieter oder einen Händler, der ein eigenes Kassensystem betreibt. Er ist die oberste Organisationsebene in der Struktur.

   Nach dem Erstellen Ihres fiskaly Accounts gelangen Sie zum Organisation Selector, in dem Sie Ihre Group anlegen können. Eine Group ist eine Zwischenebene innerhalb eines Accounts, die Ihnen dabei hilft, mehrere Units in logische Cluster zu gliedern.

3. Schritt 3: API Key erstellen

   Der nächste Schritt besteht darin, über den HUB innerhalb Ihrer Group einen API Key für Ihre Organisation zu generieren. Dieses Paar aus API Key und Secret wird benötigt, um Ihre erste Organisation vom Typ UNIT zu erstellen (Schritt 5).

   💡TEST- vs. LIVE-Umgebung

   In der TEST-Umgebung (https://test.api.fiskaly.com) generierte API Keys erstellen TEST-Ressourcen, während solche aus der LIVE-Umgebung (https://live.api.fiskaly.com) LIVE-Ressourcen erstellen.

1. Schritt 4: MANAGEMENT - Token erstellen

   Beginnen Sie mit der Nutzung der E-INVOICE API über den Endpunkt createToken. Sie müssen ein Token erstellen, um sich für die nächsten Schritte zu authentifizieren.

2. Schritt 5: MANAGEMENT - Organisation UNIT erstellen

   Fahren Sie fort, indem Sie über den Endpunkt createOrganization eine Organisation vom Typ UNIT erstellen. Eine UNIT repräsentiert eine einzelne juristische Person (Händler). Sie müssen für jede von Ihnen verwaltete Taxpayer-Repräsentation eine UNIT erstellen.

   Achten Sie beim Erstellen Ihrer ersten Organisation vom Typ UNIT darauf, dass diese mit Ihrer über den HUB erstellten Group verknüpft ist. Verwenden Sie dazu das Token, das aus den für Ihre Group erstellten API Keys generiert wurde. Dies spiegelt die hierarchische Struktur wider, in der die UNIT unterhalb Ihrer GROUP verschachtelt ist, die wiederum innerhalb Ihres ACCOUNT liegt.

3. Schritt 6: MANAGEMENT - Subject (API Key) erstellen

   Erstellen Sie über den Endpunkt createSubject ein Subject vom Typ API_KEY. Die Verbindung zwischen der Organisation UNIT und dem API Key wird über den X-Scope-Identifier hergestellt (unter Verwendung der id der neu erstellten Organisation).

4. Schritt 7: MANAGEMENT - Neues Token erstellen

   Erstellen Sie als Nächstes ein Token, das zum Erstellen von Ressourcen innerhalb der entsprechenden Organisation UNIT verwendet wird.

5. Schritt 8: OPERATION - Taxpayer erstellen

   Sie sind nun bereit, die für die E-Rechnung erforderlichen Taxpayer zu erstellen. Verwenden Sie dazu den Endpunkt createTaxpayer. Sie müssen den Taxpayer vom Typ COMPANY anlegen.

   Je nach Land können die erforderliche Fiskalisierungs-Einrichtung und die benötigten Taxpayer-Daten unterschiedlich sein. Bitte lesen Sie daher die jeweiligen Länderanleitungen:

   • Belgien
   • Deutschland
   • Italien
   • Frankreich (in Kürze)
   • Polen (in Kürze)

   Sobald Sie einen Taxpayer vom Typ COMPANY erstellen, wird dessen state auf ACQUIRED gesetzt. Um vollständig funktionsfähig zu sein, muss der Status über den Endpunkt updateTaxpayer auf COMMISSIONED aktualisiert werden.

   Beim Aufruf des Endpunkts createTaxpayer wird automatisch eine Location vom Typ HEAD_OFFICE erstellt. Sie können dies über den Endpunkt listLocations bestätigen.

6. Schritt 9: OPERATION - Location erstellen

   Neukunden, die ausschließlich E-Rechnungen integrieren, können diesen Schritt überspringen.

   Für die Belegfiskalisierung müssen Sie für jeden Geschäftsstandort über den Endpunkt createLocation eine Location vom Typ BRANCH erstellen.

   Wenn Sie eine Location vom Typ BRANCH erstellen, wird deren state zunächst auf ACQUIRED gesetzt. Um fortzufahren, müssen Sie den Status über den Endpunkt updateLocation auf COMMISSIONED ändern.

7. Schritt 10: OPERATION - System erstellen

   Der Endpunkt createSystem wird verwendet, um eine Abstraktion eines für Fiskaloperationen genutzten Systems zu erstellen.

   Je nach Ihrer Einrichtung gilt Folgendes:

   • Neukunden, die ausschließlich E-Rechnungen nutzen: Erstellen Sie ein einzelnes System vom Typ E_INVOICE_SERVICE (nur eines pro Taxpayer) und verknüpfen Sie es mit der Location HEAD_OFFICE, die in Schritt 8 automatisch für Sie erstellt wurde.

   • Neukunden, die Belegfiskalisierung und E-Rechnungen nutzen: Erstellen Sie FISCAL_DEVICE Systeme für Belege sowie ein zusätzliches System vom Typ E_INVOICE_SERVICE (eines pro Taxpayer). Verknüpfen Sie das System E_INVOICE_SERVICE mit der Location vom Typ HEAD_OFFICE und die FISCAL_DEVICE Systeme mit einer Location vom Typ BRANCH.

   • Bestandskunden mit in Betrieb genommenen Fiskalgeräten, die E-Rechnungen ergänzen: Erstellen Sie ein zusätzliches System vom Typ E_INVOICE_SERVICE und verknüpfen Sie es mit der Location vom Typ HEAD_OFFICE. Beim Erstellen eines Taxpayers wird automatisch eine Location vom Typ HEAD_OFFICE mit derselben ID generiert. Dies lässt sich durch Auflisten Ihrer Locations überprüfen.

   Beim Erstellen eines Systems wird dessen Anfangsstatus auf ACQUIRED gesetzt. Um mit dem Integrationsprozess für E-Rechnungen fortzufahren, beantragen Sie die Inbetriebnahme des Systems E_INVOICE_SERVICE über updateSystem.

   ⚠️Wichtig

   Nach einem erfolgreichen Antrag auf Inbetriebnahme befindet sich das System im Status COMMISSIONED und zunächst im Modus DEGRADED, bis Schritt 11 vollständig abgeschlossen ist.

   📘Italien 🇮🇹

   Für italienische Taxpayer wechselt das E_INVOICE_SERVICE System nach der Inbetriebnahme direkt in den Zustand state=COMMISSIONED, mode=OPERATIVE — kein Upload eines Proof of Ownership, sodass Schritt 11 entfällt, und es kann sofort Rechnungen senden. Wenn der Taxpayer außerdem empfangen soll, führen Sie die einmalige AdE-Registrierung durch — jederzeit, vor oder nach der Inbetriebnahme — siehe die Italien-Anleitung. Fahren Sie anschließend mit Schritt 12 fort.

8. Schritt 11: OPERATION - Proof of Ownership hochladen

   Dieser Schritt ist für Integrationen von E-INVOICE BE 🇧🇪 und E-INVOICE DE 🇩🇪 erforderlich.

   Laden Sie das Proof-of-Ownership-PDF über den Endpunkt createRecord hoch, wobei Sie einen Record vom Typ INTENTION und eine Operation vom Typ UPLOAD verwenden. Das eingereichte Dokument wird geprüft und verifiziert, was bis zu 72 Stunden dauern kann. Sobald die Verifizierung abgeschlossen ist, wechselt das System automatisch vom Modus DEGRADED in den Modus OPERATIVE.

   Weitere Einzelheiten zum erforderlichen Dokumentinhalt finden Sie im Abschnitt Proof of Ownership.

   📘Für Italien 🇮🇹 überspringen

   Dieser Schritt gilt nicht für Integrationen von E-INVOICE IT. Fahren Sie direkt mit Schritt 12 fort.

9. Schritt 12: OPERATION - Record erstellen

   ⚠️Wichtig

   Alle in der LIVE-Umgebung erstellten Records sind rechtsgültig und müssen daher stets reale und gültige Geschäftsvorgänge darstellen.

   Das Erstellen eines Records in der E-INVOICE API erfordert stets zwei aufeinanderfolgende Aufrufe:

   • Teil A) INTENTION — zu Beginn des E-Rechnungsprozesses
   • Teil B) TRANSACTION — sobald die E-Rechnungsdaten vollständig sind

   📘Nutzen Sie auch die Belegfiskalisierung?

   Wenn der Taxpayer auch die Belegfiskalisierung nutzt (zum Beispiel SIGN IT), erstellen Sie die INTENTION- und TRANSACTION-Records auf Ihrem FISCAL_DEVICE System (einem beliebigen auf demselben Taxpayer) — wenn ein FISCAL_DEVICE im Einsatz ist, hat es Vorrang. Das E_INVOICE_SERVICE System erstellt und übermittelt die E-Rechnung dennoch aus diesen Daten.

   TEIL A) Intention

   Rufen Sie für jede E-Rechnungsoperation zunächst den Endpunkt createRecord auf, um die Absicht zur Ausstellung einer elektronischen Rechnung zu registrieren.

   Ein Record vom Typ INTENTION enthält die folgenden Informationen:

   • Verknüpfung mit dem System E_INVOICE_SERVICE, das zur Ausstellung der E-Rechnung verwendet wird
   • Operation vom Typ TRANSACTION, die angibt, dass das System eine E-Rechnungsoperation durchführen möchte.

   Teil B) Transaction

   Rufen Sie als Nächstes den Endpunkt createRecord erneut auf, um einen Record vom Typ TRANSACTION zu erstellen, der mit der internen Kennung eines bereits erstellten Records vom Typ INTENTION verknüpft ist. Der Operationstyp bestimmt das ausgestellte Dokument.

   Die folgenden Operationstypen werden unterstützt:

   • INVOICE: Stellt eine standardmäßige elektronische Rechnung aus.
   • CORRECTION: Stellt eine Gutschrift aus. Ausführliche Abläufe und Regeln finden Sie in der Gutschriften-Anleitung.

   Sobald die Transaction erfolgreich verarbeitet wurde, wird die elektronische Rechnung erstellt und gemäß den geltenden E-Rechnungsanforderungen verarbeitet.

   📘Wichtig

   Für E-INVOICE muss der Empfänger vom Typ BUSINESS sein und der invoicing-Block muss befüllt sein, andernfalls kann die E-Rechnung nicht übermittelt werden. Die Zustellmethode und die erforderlichen Felder innerhalb des invoicing-Blocks variieren je nach Land — bitte lesen Sie die jeweiligen Länderanleitungen unten.

   Italien ist die Ausnahme: Dort werden auch CONSUMER-Empfänger für B2C-Rechnungen unterstützt, mit anderen Pflichtfeldern. Siehe B2C-E-Rechnungen senden.

   • Belgien
   • Deutschland
   • Italien
   • Frankreich (in Kürze)
   • Polen (in Kürze)

Nächste Schritte

Anleitung Belgien

Länderspezifische Anforderungen für E-Rechnungen in Belgien.

Anleitung Deutschland

Länderspezifische Anforderungen für E-Rechnungen in Deutschland.

Proof of Ownership

Erfahren Sie mehr über den Prozess der Dokumentverifizierung.

API-Referenz

Vollständige Dokumentation der E-INVOICE API.