Schritt-für-Schritt-Integration

📘Note

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

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 PT 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 PT 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.

   Tokens sind kurzlebige JWTs, die jeden nachfolgenden SIGN PT-Aufruf authentifizieren. Sie werden pro Konto- oder Organisationsbereich abgerufen.

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 Portugal erforderlichen operativen Teile zu erstellen.

   Verwenden Sie den Endpunkt createTaxpayer der SIGN PT API, um einen Steuerpflichtigen wie folgt zu erstellen:

   • Legen Sie den Steuerpflichtigen als Typ Company (juristische Person) oder Individual (natürliche Person) fest. In beiden Fällen müssen Name und Adresse angegeben werden.
   • Innerhalb der portugiesischen Fiskalisierungsinformationen müssen mindestens folgende Steuerpflichtigendaten angegeben werden:
     • tax_id_number: die portugiesische NIF (Número de Identificação Fiscal) des Steuerpflichtigen. 9 Ziffern, ohne Leerzeichen oder Trennzeichen (z. B. 501234567).
     • credentials: die AT-Unterbenutzer-Zugangsdaten, die SIGN PT verwendet, um AT-Webservices im Namen dieses Steuerpflichtigen aufzurufen:
       • Benutzername: die Unterbenutzerkennung im Format <NIF>/<subuser-id> (z. B. 501234567/5), wie vom Portal das Finanças ausgegeben.
       • Passwort: das für diesen Unterbenutzer festgelegte Passwort.

   Dies sind nicht die Hauptanmeldedaten des Händlers für das Portal das Finanças. Es muss sich um einen dedizierten Unterbenutzer handeln, der speziell für den Webservice-Zugang erstellt wurde — siehe den Wichtigen Hinweis unten.

   ⚠️Wichtig

   Die Nutzung von AT-Webservices über SIGN PT erfordert eine vorherige Einrichtung im Portal das Finanças durch den Steuerpflichtigen oder dessen gesetzlichen Vertreter: Ein dedizierter Webservice-Unterbenutzer sollte erstellt, mit den erforderlichen Berechtigungen (z. B. WSE, WFA, WDT) ausgestattet und die geltenden AT-Nutzungsbedingungen akzeptiert werden.

   Schritt-für-Schritt-Anweisungen zur Erstellung des Unterbenutzers finden Sie unter Unterbenutzer im Portal das Finanças erstellen.

   Sobald Sie einen Taxpayer erstellt haben — ob vom Typ Company oder Individual — 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 zusammen mit dem Steuerpflichtigen erstellt. 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 System (ERS) 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.

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 kann eine der folgenden Operationen durchführen:

   • INVOICE/RECEIPT: Repräsentiert den Verkauf einer Ware oder Dienstleistung, einschließlich Dokumentdetails (Dokumentnummer, Aktivitätscode, Transaktionsdatum, Gesamtbeträge inkl. und exkl. MwSt.) und Positionen (jede Position hat einen entries[].type wie SALE, Beschreibung, ob es sich um eine GOOD oder SERVICE handelt usw.).
   • CORRECTION: Erstellt ein Korrekturdokument (NC für Gutschrift / ND für Lastschrift) mit Verweis auf einen zuvor erstellten INVOICE/RECEIPT. Enthält die korrigierten Positionen und eine reference_id zum Originaldokument.
   • CANCELLATION: Dient zur Ungültigmachung einer gesamten Transaktion. Erfordert die id eines zuvor erstellten Records.

   Nach Einreichung des TRANSACTION-Records führt SIGN PT die konformen Ausstellungsschritte für die ausgewählte Operation durch: Es weist die nächste fortlaufende Nummer in der Serie zu (Nummern werden nicht vorab zugewiesen), signiert und verketten das Dokument und generiert die für die endgültige kundenorientierte Darstellung erforderlichen Daten.

   Je nach Berichtskonfiguration des Steuerpflichtigen werden dieselben Transaktionsdaten dann entweder:

   • in SAF-T (PT)-Berichterstattung/Export einbezogen (für monatliche Übermittlung), und/oder
   • an AT über Webservices gemeldet (z. B. Rechnungen über WFA; Transportdokumente über WDT, sofern zutreffend und Berechtigungen erteilt wurden).

   Nach Abschluss der Verarbeitung gibt SIGN PT zurück (über die Record-Antwort und/oder abrufbare Record-Artefakte):

   • die für den Druck erforderliche Compliance-Nutzlast (z. B. ATCUD, QR-Code-Inhalt, den Hash-Auszug und die Softwarezertifikatsnummer)
   • die signierten/verketteten Dokumentdaten, die für die endgültige Quittungs-/Rechnungsdarstellung benötigt werden, und
   • Verarbeitungsstatusinformationen für den Record (Erfolg/Misserfolg und relevante Fehlerdetails).

   📘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.