POS-System-APIEin einziger Einstiegspunkt von Ihrem POS zu fiskaltrust.Middleware.
Erstellen Sie Belege, führen Sie Zahlungen aus, stellen Sie digitale Belege aus und exportieren Sie Journale über eine prozessgesteuerte HTTP-API.
Mit der API können Sie sich auf Ihr System konzentrieren, während fiskaltrust sich um die Quittungsinfrastruktur kümmert. Anstatt Quittungen als Nebenfunktion oder als Zusatz für den Verbraucher zu behandeln, behandelt die Receipt-API Quittungen als erstklassige, regulierte Systemkomponente. Sie integrieren einmal und verlassen sich auf eine einheitliche, quelloffene API, die gepflegt wird, wenn sich die Vorschriften und betrieblichen Anforderungen weiterentwickeln.
Die fiskaltrust POS System API dient als zentrale Schnittstelle zwischen Kassensystemen und der fiskaltrust Middleware. Sie bietet eine umfassende Reihe von Funktionen, darunter die Fiskalisierung (oder Signierung) von Belegen, die Ausführung von Zahlungen über verschiedene Anbieter, den digitalen Belegdruck und den Datenexport aus der Middleware.
Über einfache und konsistente Endpunkte unterstützt die API wichtige Funktionen: /echo für Konnektivitätstests, /order für die Registrierung von Bestelldaten, /pay für die Zuordnung von Zahlungen, /sign für die Versiegelung von Transaktionen, /issue für die Erstellung digitaler oder druckbarer Quittungen und /journal für revisionssichere Exporte.
Leicht lesbare API-Endpunkte
Internationale PosSystem-API
- /echo,Gesundheitscheck und Zurücksetzen.
- /order,Bestellinformationen und Abfragestatus oder -ergebnis registrieren.
- /pay,Zahlungen ausführen, auf den Abschluss mit Timeouts warten, Ergebnis abrufen.
- /sign,Quittungen mit nationalen Regeln und Hash-Verkettung abschließen.
- /issueerstellen und aktualisieren Sie die ausgestellte Quittung, einschließlich des Lieferstatus.
- /journal,einzelne Einträge oder Bereiche für Audits und Abschlüsse abrufen.
POS-Händler-API. Gebaut für stabile, transparente, revisionssichere Integrationen.
Die API wurde für den plattformübergreifenden Einsatz entwickelt und unterstützt lokale Implementierungen und in der Cloud gehostete Instanzen in europäischen Rechenzentren. Sie bietet eine revisionssichere Speicherung und ist mit der fiskaltrust Middleware für automatische Compliance-Updates integriert.
Teile der API und Middleware sind quelloffen und bieten so Transparenz und langfristige Stabilität. Durch die offene Dokumentation und das einheitliche Datenmodell wird der Wartungsaufwand reduziert und die POS-Lösungen werden revisionssicher.
Eine API, einheitliches Verhalten, unabhängig von länderspezifischen Anforderungen.
Zentrale Konzepte
Die API behandelt eine Transaktion als eine Reise. Jeder Schritt ändert den Status auf dem Server. Sie übergeben bei jedem Aufruf eine eindeutige Vorgangskennung. Wenn das Netzwerk ausfällt, wiederholen Sie den gleichen Aufruf mit der gleichen Kennung.
Das Backend dedupliziert und gibt das erste abgeschlossene Ergebnis zurück. Dieses Design bietet sichere Wiederholungsversuche und vorhersehbare Ergebnisse für kritische Fiskalschritte.
- Zentraler Zugangspunkt zur Middleware für Fiskalisierung, Zahlungen, Ausgabe und Export.
- Prozessuale, zustandsabhängige Aufrufmuster, die sich wie ein Zustandsautomat verhalten.
- Idempotenz durch Header x-operation-id mit deterministischen Antworten bei Wiederholung.
- Callback-Haken zur Beobachtung von Zustandsübergängen bei langen Operationen.
Eine Anfrage mit x-operation-id erreicht die Middleware
Middleware Verarbeitung
Wiederholungsversuch mit derselben x-operation-id
Abgeschlossen Ergebnis
Rückruf-Endpunkt x-operation-callback-state
Authentifizierung und Versionierung
Der Zugang wird von der CashBox bestimmt. Sie verwenden CashBoxId und AccessToken aus dem Portal. Die API folgt der semantischen Versionierung. Änderungen sind auf die Hauptversionen beschränkt und können bei Bedarf in der URL verankert werden.
- Berechtigungsnachweise: CashBoxId und AccessToken.
- Semantische Versionierung, standardmäßig auf dem neuesten Stand, mit Unterstützung für explizites Pinning.
POS-Entwickler
Authentifizierung CashBoxId + AccessToken
V1
V2
V3
AsynchroneAPI-Muster
Mit der API können Sie sich auf Ihr System konzentrieren, während fiskaltrust sich um die Quittungsinfrastruktur kümmert. Anstatt Quittungen als Nebenfunktion oder als Zusatz für den Verbraucher zu behandeln, behandelt die Receipt-API Quittungen als erstklassige, regulierte Systemkomponente. Sie integrieren einmal und verlassen sich auf eine einheitliche, quelloffene API, die gepflegt wird, wenn sich die Vorschriften und betrieblichen Anforderungen weiterentwickeln.
Kopfzeilen und Idempotenz
Jeder kritische Aufruf akzeptiert Kontroll-Header. x-operation-id ist Ihr Idempotenz-Schlüssel. x-operation-lifetime definiert, wie lange die Operation gültig ist. Sie können eine Callback-URL pro Aufruf festlegen, um Statusmeldungen ohne Polling zu erhalten.
- x-operation-id, eindeutig pro Operation, um Wiederholungen zu vermeiden.
- x-operation-lifetime, Akzeptanzfenster in Millisekunden.
- x-operation-callback-state, Benachrichtigung bei jeder Statusänderung.
- Optionale x-terminal-id und x-possystem-id für die Zuweisung.
Liefer- und Empfangsstatus
Nach der Ausgabe können Sie den ausgegebenen Inhalt abrufen, ihn aktualisieren oder den Lieferstatus abfragen. Es gibt blockierende Endpunkte, die bis zu einer maximalen Zeitüberschreitung warten und melden, ob sie zugestellt oder nicht zugestellt wurden. Dies vereinfacht die Benutzerströme an der Kasse und vermeidet lästige Abfragen.
Umgebungen
Die API bietet Sandbox- und Produktionsumgebungen für jeden Endpunkt. Verwenden Sie die Sandbox für Integration und automatisierte Tests. Führen Sie dieselben Aufrufe in der Produktionsumgebung aus, wenn Sie bereit sind. Die AynchronousAPI, Header und Callbacks verhalten sich in beiden Umgebungen identisch.
Fehlerbehandlung
Aufrufe geben standardmäßige HTTP-Statuscodes zurück. Fehlerhafte Anfragen oder fehlende Header führen zu Client-Fehlern. Authentifizierungsfehler geben unautorisiert zurück. Der Server meldet unerwartete Fehler mit Problemdetails, sofern verfügbar. Wiederholungen mit der gleichen Vorgangskennung geben das erste abgeschlossene Ergebnis zurück.
Verwenden Sie eine offene, dokumentierte Schnittstelle, die sich an geänderte Vorschriften anpasst.
So funktioniert es in 3 Schritten
Sie konfigurieren eine CashBox im Portal und erhalten Anmeldedaten. Ihr POS ruft Warenkorb, Bestellung und Bezahlung auf, um die Reise zu beginnen. Sie schließen mit Unterschrift und Ausgabe ab und lesen dann die Journaleinträge für den Tagesabschluss oder Audits. Sie wiederholen fehlgeschlagene Schritte sicher, indem Sie die Vorgangskennung erneut verwenden.
1.
Melden Sie sich auf dem fiskaltrust.Portal an.
2.
Erstellen Sie eine Cashbox und verbinden Sie sie mit Ihrem POS oder ERP.
3.
Fahren Sie den Weg: Warenkorb, Bestellung, Bezahlung, Unterschrift, Ausgabe.
Entwickler essentials
Beginnen Sie mit der OpenAPI-Spezifikation und der Live-Dokumentation. Sehen Sie sich die SynchronousAPI-Diagramme und den Header-Vertrag an. Bauen Sie Wiederholungen mit Idempotenz und Rückrufen auf. Verwenden Sie die Sandbox, um Zustandsübergänge und das Verhalten bei der Zustellung von Quittungen vor der Produktion zu validieren.
- POS System API-Dokumentationsseite und OpenAPI-Datei.
- SynchronousAPI Zeit- und Zustandsdiagramme.
- Sandbox-Endpunkte für Echo, Warenkorb, Bestellung, Bezahlung, Unterschrift, Ausgabe, Journal.
Fragen zur Integration? Unser technisches Team ist nur eine Nachricht entfernt.
Kontaktieren Sie uns