Schritt-für-Schritt-Integrationsprozess

B2B-E-Invoicing

Rechtskonforme elektronische Rechnungen für B2B-Transaktionen über das PEPPOL-Netzwerk ausstellen.

Mehrländer-Unterstützung

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

Unified API

Einzelne Integration für E-Invoicing in allen unterstützten Ländern mit einheitlichen Endpunkten.

Voraussetzungen

Stellen Sie vor dem Start sicher, dass Sie Folgendes haben:

• Zugang zum fiskaly HUB (TEST-Umgebung)
• Grundlegende Kenntnisse von REST-APIs und Authentifizierungsabläufen
• Ihre Unternehmensregistrierungsdaten für die Steuerpflichtigen-Einrichtung

📘Note

Wenn Sie bereits SIGN IT oder SIGN FR integriert haben, sind die anfänglichen Einrichtungsschritte in diesem Leitfaden wahrscheinlich vertraut und möglicherweise bereits abgeschlossen. In diesem Fall können Sie direkt zu Schritt 10 wechseln, um die erforderlichen zusätzlichen Schritte zu überprüfen.

Integrations-Workflow

📘Wichtig

In Gelb markierte Schritte müssen direkt im HUB ausgeführt werden, während die verbleibenden Schritte über die API abgewickelt werden müssen. Die Durchführung jeder Aktion im richtigen Kontext ist ein wichtiger Schritt für eine erfolgreiche Integration.

Schritt-für-Schritt-Einrichtung

1. Schritt 1: Im HUB registrieren

   Beginnen Sie mit der Registrierung im fiskaly HUB.

   
2. Schritt 2: Konto & Organisations-GRUPPE erstellen

   Die Erstellung eines fiskaly-Kontos ist der erste Schritt. Anschließend können Sie die erste Organisationsstruktur für Ihr Unternehmen einrichten und Ihren API-Schlüssel generieren.

   Das Konto repräsentiert den Kassensystemanbieter oder einen Einzelhändler, der sein eigenes Kassensystem 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 Zwischenebene innerhalb eines Kontos, die dabei hilft, mehrere Einheiten in logische Cluster zu organisieren.

3. Schritt 3: API-Schlüssel erstellen

   Im nächsten Schritt generieren Sie einen API-Schlüssel für Ihre Organisation über den HUB innerhalb Ihrer Gruppe. Dieses API-Schlüssel-und-Secret-Paar wird benötigt, um Ihre erste Organisation vom Typ UNIT zu erstellen (Schritt 5).

   💡TEST- vs. LIVE-Umgebungen

   In der TEST-Umgebung generierte API-Schlüssel (https://test.api.fiskaly.com) 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 createToken Endpunkt. Sie müssen ein Token erstellen, um sich für die nächsten Schritte zu authentifizieren.

2. Schritt 5: MANAGEMENT — Eine Organisations-EINHEIT erstellen

   Fahren Sie mit der Erstellung einer Organisation vom Typ UNIT über den createOrganization Endpunkt fort. Eine UNIT repräsentiert eine einzelne juristische Person (Händler). Sie müssen eine UNIT für jede Steuerpflichtigendarstellung erstellen, die Sie verwalten.

   Wenn Sie Ihre erste Organisation vom Typ UNIT erstellen, stellen Sie sicher, dass sie mit Ihrer über den HUB erstellten Gruppe verknüpft ist. Verwenden Sie dazu das Token, das aus den für Ihre Gruppe erstellten API-Schlüsseln generiert wurde. Dies spiegelt die hierarchische Struktur wider, bei der die UNIT unter Ihrer GROUP liegt, die ihrerseits innerhalb Ihres ACCOUNT sitzt.

3. Schritt 6: MANAGEMENT — Subject erstellen (API-Schlüssel)

   Erstellen Sie ein Subject vom Typ API_KEY über den createSubject Endpunkt. Die Verbindung zwischen der Organisations-UNIT und dem API-Schlüssel 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 verwendet wird, um Ressourcen innerhalb der entsprechenden Organisations-UNIT zu erstellen.

5. Schritt 8: OPERATION — Steuerpflichtigen erstellen

   Sie können jetzt die für das E-Invoicing erforderlichen Steuerpflichtigen erstellen. Verwenden Sie dazu den createTaxpayer Endpunkt. Sie müssen den Steuerpflichtigen vom Typ COMPANY festlegen.

   Je nach Land können die erforderliche Fiskalisierungseinrichtung und die erforderlichen Steuerpflichtigendaten unterschiedlich sein. Bitte lesen Sie dazu die entsprechenden Länder-Leitfäden:

   • Belgien
   • Deutschland
   • Italien (demnächst)
   • Frankreich (demnächst)
   • Polen (demnächst)

   Sobald Sie einen Steuerpflichtigen vom Typ COMPANY erstellen, wird sein state auf ACQUIRED gesetzt. Um vollständig funktionsfähig zu sein, muss der Status mithilfe des updateTaxpayer Endpunkts auf COMMISSIONED aktualisiert werden.

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

6. Schritt 9: OPERATION — Standort erstellen

   Neukunden, die nur E-Invoicing integrieren, können diesen Schritt überspringen.

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

   Wenn Sie einen Standort vom Typ BRANCH erstellen, wird sein state zunächst auf ACQUIRED gesetzt. Um fortzufahren, müssen Sie den Status mithilfe des updateLocation Endpunkts auf COMMISSIONED ändern.

7. Schritt 10: OPERATION — System erstellen

   Der createSystem Endpunkt wird verwendet, um eine Abstraktion eines für fiskalische Operationen verwendeten Systems zu erstellen.

   Je nach Ihrer Einrichtung gilt Folgendes:

   • Neukunden, die nur E-Invoicing nutzen: Erstellen Sie ein einzelnes E_INVOICE_SERVICE-System (nur eines pro Steuerpflichtigen) und verknüpfen Sie es mit dem HEAD_OFFICE-Standort, der in Schritt 8 automatisch für Sie erstellt wurde.

   • Neukunden, die Belegfiskalisierung und E-Invoicing nutzen: Erstellen Sie FISCAL_DEVICE-Systeme für Belege und ein zusätzliches E_INVOICE_SERVICE-System (eines pro Steuerpflichtigen). Verknüpfen Sie das E_INVOICE_SERVICE-System mit dem Standort vom Typ HEAD_OFFICE und die FISCAL_DEVICE-Systeme mit einem Standort vom Typ BRANCH.

   • Bestehende Kunden mit in Betrieb genommenen Fiskalisierungsgeräten, die E-Invoicing hinzufügen: Erstellen Sie ein zusätzliches E_INVOICE_SERVICE-System und verknüpfen Sie es mit dem Standort vom Typ HEAD_OFFICE. Bei der Erstellung eines Steuerpflichtigen wird automatisch ein Standort vom Typ HEAD_OFFICE mit derselben ID generiert. Dies kann durch Auflisten Ihrer Standorte überprüft werden.

   Bei der Erstellung eines Systems wird sein anfänglicher Status auf ACQUIRED gesetzt. Um mit dem E-Invoicing-Integrationsprozess fortzufahren, beantragen Sie die Inbetriebnahme des E_INVOICE_SERVICE-Systems mithilfe von updateSystem.

   ⚠️Wichtig

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

8. Schritt 11: OPERATION — Eigentumsnachweis hochladen

   Laden Sie den Eigentumsnachweis-PDF über den createRecord Endpunkt hoch, indem Sie einen Datensatz 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. Nach Abschluss der Überprüfung wechselt das System automatisch vom Modus DEGRADED in den Modus OPERATIVE.

   Weitere Details zum erforderlichen Dokumentinhalt finden Sie im Abschnitt Eigentumsnachweis.

9. Schritt 12: OPERATION — Datensatz erstellen

   ⚠️Wichtig

   Alle in der LIVE-Umgebung erstellten Datensätze sind rechtlich gültig und müssen daher stets echte und gültige Geschäftstransaktionen darstellen.

   💡Hinweis

   Das Erstellen eines Datensatzes in der E-INVOICE API erfordert immer zwei aufeinanderfolgende Aufrufe: - Teil A) INTENTION — zu Beginn des E-Invoicing-Prozesses - Teil B) TRANSACTION — sobald die E-Invoicing-Daten vollständig sind

   TEIL A) Intention

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

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

   • Verknüpfung mit dem E_INVOICE_SERVICE-System, das zur Ausstellung der E-Rechnung verwendet wird
   • Operation vom Typ TRANSACTION, die anzeigt, dass das System beabsichtigt, eine E-Invoicing-Operation durchzuführen.

   Teil B) Transaktion

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

   Folgende Operationstypen werden unterstützt:

   • INVOICE: Stellt eine Standard-E-Rechnung aus.

   Sobald die Transaktion erfolgreich verarbeitet wurde, wird die elektronische Rechnung erstellt und gemäß den anwendbaren E-Invoicing-Anforderungen behandelt.

   📘Wichtig

   Für E-INVOICE muss der Empfänger vom Typ BUSINESS sein und der invoicing-Block muss ausgefüllt werden, andernfalls kann die E-Rechnung nicht übertragen werden. Die Übermittlungsmethode und die erforderlichen Felder im invoicing-Block variieren je nach Land — bitte beachten Sie die entsprechenden Länder-Leitfäden unten.

   • Belgien
   • Deutschland
   • Italien (demnächst)
   • Frankreich (demnächst)
   • Polen (demnächst)

   • CORRECTION mit data.type = INVOICE: Stellt eine Gutschrift aus, die auf eine zuvor übermittelte Rechnung verweist. Die Transaktion muss einen vorausgehenden Dokumentverweis auf die ursprüngliche Rechnung enthalten, und der Empfänger muss mit dem Original übereinstimmen. Weitere Informationen zu Workflows und Regeln finden Sie im Gutschrift-Leitfaden.

   💡Hinweis

   CORRECTION::INVOICE-Datensätze werden nur von einem E_INVOICE_SERVICE-System akzeptiert.

Nächste Schritte

Belgien-Leitfaden

Länderspezifische Anforderungen für die belgische E-Rechnungsstellung.

Deutschland-Leitfaden

Länderspezifische Anforderungen für die deutsche E-Rechnungsstellung.

Eigentumsnachweis

Erfahren Sie mehr über den Dokumentenüberprüfungsprozess.

API-Referenz

Vollständige E-INVOICE API-Dokumentation.