Für SIGN ES-Kunden

SIGN PT Integrationsleitfaden für SIGN ES-Kunden

Diese Anleitung hilft Teams, die bereits SIGN ES integriert haben, zu verstehen, wie der gleiche Geschäftsablauf mit dem Unified API-Ansatz von fiskaly in SIGN PT abgebildet wird.

Von SIGN ES zu SIGN PT

Wenn Sie SIGN ES bereits kennen, wird Ihnen vieles im Ablauf vertraut erscheinen. Gleichzeitig bringt SIGN PT einige wichtige Unterschiede in der Endpunktstruktur, den Ressourcenbezeichnungen und dem Lebenszyklus der Ressourcen mit sich.

Vergleichsübersicht

SIGN ES	SIGN PT / Unified API	Bedeutung
Hauptorganisation	Organization::GROUP	Repräsentiert den Integrator (Softwareanbieter oder Händler mit eigenem Abrechnungssystem).
Verwaltete Organisation	Organization::UNIT	Repräsentiert eine NIF (Händler oder Steuerpflichtiger).
Ein Steuerpflichtiger pro verwalteter Organisation	Steuerpflichtiger verknüpft mit einer oder mehreren Location::BRANCH-Ressourcen	Ein Steuerpflichtiger kann von verschiedenen Geschäftsstandorten aus operieren. Location::BRANCH repräsentiert einzelne Filialstandorte.
signer	automatisch verwaltet	Die Signierkomponente wird im Unified API-Ablauf automatisch verwaltet. Der Integrator muss diese Ressource nicht erstellen.
client	System::FISCAL_DEVICE	POS-/Rechnungsterminals werden als Systeme statt als Client-Objekte dargestellt.
invoice	Record::INTENTION und Record::TRANSACTION	Rechnungen oder Belege werden als Records verwaltet, mit zwei Aufrufen: INTENTION zur Absichtserklärung und TRANSACTION mit dem endgültigen Beleg- oder Rechnungsinhalt.
Vom Client definierte UUIDs	Automatisch zugewiesene UUIDs plus X-Idempotency-Key	Sie stellen keine Ressourcen-UUIDs direkt bereit; Idempotenz schützt vor Duplikaten.

Bevor Sie beginnen

📘Voraussetzungen

Sie benötigen ein fiskaly-Konto und Zugang zum fiskaly HUB. Sie benötigen außerdem ein Tool für HTTP-Anfragen, z. B. cURL, Postman oder Ihren eigenen Anwendungscode.

Wenn Sie bereits SIGN ES integriert haben, wird Ihnen der Geschäftsablauf vertraut sein, aber die Einrichtung ist in SIGN PT expliziter und verwendet das Unified API-Ressourcenmodell. Mit dieser Integration erschließen Sie mehrere Länder mit nur einer Integration.

Vor dem Start ist es hilfreich, in den Begriffen der zu konfigurierenden Ressourcen zu denken:

• Organization — eine GROUP für die übergeordnete Struktur und eine oder mehrere UNIT-Organisationen für einzelne Händler oder Steuerpflichtige.
• API Key und Token — Anmeldedaten, die im HUB erstellt und dann gegen Token ausgetauscht werden, die im Unified API-Ablauf verwendet werden.
• Taxpayer — eine COMPANY- oder INDIVIDUAL-Ressource, die die juristische Person repräsentiert, die Steuerdokumente ausstellt.
• Location — eine BRANCH-Ressource für jeden physischen Laden oder Betriebsstandort.
• System — eine FISCAL_DEVICE-Ressource, die das POS oder das Fiskalgerät repräsentiert, das Dokumente ausstellt.
• Record — ein zweistufiger Fiskalablauf mit INTENTION und TRANSACTION anstelle der direkten Rechnungserstellung.

Integrationsablauf

Schritt	Was Sie tun	Warum es existiert
1. Im HUB registrieren	Erstellen Sie Ihr fiskaly-Konto im HUB	Dies ist der Einstiegspunkt für die Einrichtung Ihrer Organisation und API-Anmeldedaten.
2. Erste Organisation erstellen	Erstellen Sie Ihre erste Organization::GROUP im HUB	Dies repräsentiert den POS-Anbieter oder Händler auf oberster Ebene. Erstellen Sie nach diesem Schritt einen API-Schlüssel für diese Organisation im HUB.
3. API-Schlüssel erstellen	Generieren Sie einen API-Schlüssel und ein Secret für die Gruppe im HUB	Sie benötigen diese Anmeldedaten zur Authentifizierung und für die weitere Einrichtung.
4. Token erstellen	createToken aufrufen	Dieses Token wird für die nächsten API-Anfragen verwendet.
5. Organisation UNIT erstellen	Eine Organization::UNIT pro Steuerpflichtigem erstellen	Dies ersetzt das alte Konzept der verwalteten Organisation.
6. Subject API-Schlüssel erstellen	createSubject mit X-Scope-Identifier aufrufen	Dadurch wird ein API-Schlüssel mit der richtigen Organization::UNIT verknüpft.
7. Scoped Token erstellen	Ein zweites Token für den Unit-Scope erstellen	Dieses Token wird dann für Ressourcen auf Steuerpflichtiger-Ebene und Betriebsressourcen verwendet.
8. Steuerpflichtigen erstellen	Eine Taxpayer::COMPANY oder Taxpayer::INDIVIDUAL erstellen	Dies repräsentiert die juristische Person, die die Steuerdokumente ausstellt.
9. Standort erstellen	Eine Location::BRANCH für jeden Laden oder Betriebsstandort erstellen	Dadurch wird jeder Geschäftsstandort explizit im Modell abgebildet.
10. System erstellen	Ein System::FISCAL_DEVICE und zugehörige POS-Systeme erstellen	Dies ersetzt die Einrichtung von Signer und Client.
11. Steuereintrag erstellen	Den Fiskalvorgang als Records erstellen	Dies ersetzt den rechnungsorientierten Ablauf aus SIGN ES.

Praktische Übersetzung

Für eine bestehende SIGN ES-Integration ist der klarste Weg zur Modellübersetzung:

• managed organization wird zu Organization::UNIT
• taxpayer verfügt über eine oder mehrere verbundene Location::BRANCH-Ressourcen, abhängig von der Anzahl der Geschäftsstandorte
• signer wird automatisch vom Unified API-Ablauf verwaltet
• client wird zu System::FISCAL_DEVICE
• invoice wird zu einem Record

Ressourcenverhalten

Ein wichtiger Unterschied zu SIGN ES ist, wie betriebliche Ressourcen nutzbar werden.

In SIGN ES sind wichtige Ressourcen in der Regel sofort nach ihrer Erstellung einsatzbereit.

In SIGN PT folgen Ressourcen wie Taxpayer, Location und System einem Lebenszyklus:

• Sie werden zunächst im Zustand ACQUIRED erstellt
• Sie müssen dann auf COMMISSIONED aktualisiert werden
• Erst danach sind sie für den Betrieb bereit

Das bedeutet, dass der Einrichtungsablauf einen expliziten Aktivierungsschritt für Ressourcen enthält, die in SIGN ES sofort nutzbar sind.

Record-Zustände und -Modi

Ein Record durchläuft während seines Lebenszyklus verschiedene Zustände und Modi. Einige Änderungen erfolgen, wenn Sie die API aufrufen, andere automatisch während das System den Record verarbeitet.

SIGN PT

Zustände

UAPI-Zustand	Bedeutung	SIGN ES-Äquivalent
Accepted	Record wurde korrekt empfangen und wird verarbeitet	Rechnung erfolgreich erstellt (ISSUED) und zur Übermittlung bereit — entspricht einer 200 OK-Antwort in SIGN ES.
Rejected	Record ist fehlgeschlagen und wird nicht weiter verarbeitet	Rechnungserstellung schlägt fehl, keine Rechnung wird gespeichert — entspricht einer 400- oder 500-Fehlerantwort in SIGN ES.
Completed	Record wurde erfolgreich von der zuständigen Behörde verarbeitet	Rechnung von der Steuerbehörde akzeptiert — entspricht dem Registrierungsstatus REGISTERED in SIGN ES.
Failed	Record konnte von der zuständigen Behörde nicht verarbeitet werden	Rechnung wurde gesendet, aber von der Steuerbehörde abgelehnt oder mit Fehlern akzeptiert — entspricht dem Registrierungsstatus REQUIRES_INSPECTION oder REQUIRES_CORRECTION in SIGN ES.

Modi

UAPI-Modus	Bedeutung	SIGN ES-Äquivalent
Processing	Record wird verarbeitet (zwischen Erstellung und einem endgültigen Zustand)	Rechnung ISSUED und wartet auf Antwort von der Steuerbehörde — entspricht dem Registrierungsstatus PENDING in SIGN ES.
Finished	Verarbeitung ist abgeschlossen; Zustand ist nun Completed, Failed oder Rejected	Rechnung hat einen endgültigen Registrierungsstatus: REGISTERED, REQUIRES_CORRECTING oder REQUIRES_INSPECTION.