NewsKontakt

POS System API

Fünf Endpunkte. Ein fiskalischer Zustandsautomat.

Die POS System API führt jede Transaktion durch deterministische Zustandsübergänge. Ihr Kassensystem sendet jeweils einen Schritt. Die Middleware signiert, verkettet und journalisiert hinter denselben Endpunkten nach dem Recht des jeweiligen Landes.

Referenz 2.1 öffnenSandbox-Beleg signieren

Die fünf Endpunkte

  • /echo – Verbindungsprüfung beim Start des KassensystemsMinimum
  • /pay – Elektronische Zahlung über die Middleware
  • /sign – Jede Transaktion nach nationalen Vorschriften fiskalisierenMinimum
  • /issue – Beleg zustellen, digital oder gedruckt
  • /journal – Prüfdaten, Abschlüsse und Prüfungen exportieren

Zwei Endpunkte ergeben eine konforme Integration. Drei weitere runden den Checkout ab.

Endpunkte decken den Fiskalisierungsablauf ab
5
Endpunkte für eine Mindest-Integration
2
Header bei jeder Anfrage
4
Integration für alle unterstützten Märkte
1

API-UMFANG

Kompakt gebaut.

Dieselben fünf Endpunkte funktionieren in jedem unterstützten Markt. Die länderspezifische Compliance liegt in der CashBox-Konfiguration, nicht in einer eigenen API-Oberfläche.

EndpunktZweckTypische Verwendung
/echoVerbindungs- und Funktionsprüfung, bestätigt Middleware-Version und FähigkeitenVerbindung beim Start des Kassensystems testen
/payZahlungsabwicklung ausführen und überwachen, inklusive Timeouts und Zuordnung der ZahlungsartenEinen Auftrag mit einer oder mehreren Zahlungsarten abschließen
/signBeleg nach nationalen Vorschriften abschließen und fiskalisieren, Signatur und Hash-VerkettungEinen revisionssicheren, länderkonformen Beleg erzeugen
/issueBelegausgabe erzeugen und Zustellstatus aktualisieren, digital oder gedrucktDen signierten Beleg an den Kunden übergeben
/journalPrüfrelevante Journaldaten und Bereiche abrufenTagesabschlüsse, Prüfexporte, Archiv-Snapshots

WENN DAS NETZ AUSFÄLLT

Erneut senden. Kein Beleg wird doppelt signiert.

Netzwerke in Geschäften fallen aus, meist mitten in einer Transaktion. Die API ist darauf ausgelegt: Jede Anfrage trägt ihre eigene ID. Erhält Ihr Kassensystem keine Antwort und sendet dieselbe Anfrage erneut, liefert der zweite Aufruf das Ergebnis des ersten. Kein Verkauf wird doppelt signiert, kein Beleg doppelt nummeriert.

x-operation-id: 9f4e…c21a  # one UUID per logical operation, unchanged on retry

  • Einmal abgeschlossen, erneut geliefert

    Ein wiederholter Aufruf mit derselben Kennung liefert das Ergebnis des ursprünglichen Vorgangs.

  • Noch in Arbeit, dann Warten

    Ein erneuter Aufruf während der Verarbeitung wartet, bis der ursprüngliche Vorgang abgeschlossen ist, und liefert dann dessen Ergebnis.

  • Anderer Body, abgelehnt

    Dieselbe Kennung mit geändertem Request-Body liefert 409 Conflict. Wiederholungen müssen exakt den ursprünglichen Body senden.

AUTHENTIFIZIERUNG

Vier Header. Kein Login-Schritt.

Die API gilt je CashBox. Die Zugangsdaten stammen beim Anlegen der CashBox aus dem fiskaltrust.Portal und werden bei jeder Anfrage mitgeschickt. Kein Token-Austausch, kein Sitzungszustand.

request headers
x-cashbox-id:           <from the Portal>
x-cashbox-accesstoken:  <from the Portal>
x-possystem-id:         <your registered variant>
x-operation-id:         <fresh UUID per operation>
x-cashbox-id
Kennzeichnet die Ziel-CashBox. Wird im Portal mit der CashBox-Konfiguration ausgegeben.
x-cashbox-accesstoken
Authentifiziert den Aufrufer. Auf Seiten des Kassensystems sicher aufbewahren.
x-possystem-id
Kennzeichnet die registrierte Variante Ihres Kassensystems. Sie wird ausgegeben, wenn Sie die Variante im Portal registrieren.
x-operation-id
Ihr Idempotenzschlüssel. Erzeugen Sie pro logischem Vorgang eine UUID und verwenden Sie bei jeder Wiederholung denselben Wert.

Ihr Kassensystem spricht mit einer API. Die API spricht mit allem, was das Land verlangt.

VON ANFANG BIS ENDE

Eine Transaktion, Schritt für Schritt.

Jeder Aufruf bringt die Transaktion einen Zustand weiter. Die Middleware spricht mit den Signaturkomponenten und der fiskaltrust.Cloud. Ihr Kassensystem ruft nie direkt eine TSE, eine RT oder eine Smartcard auf.

  1. /echo

    Verbinden

    Beim Start Verbindung, Middleware-Version und Fähigkeiten prüfen.
  2. /pay

    Bezahlen (optional)

    Elektronische Zahlung mit Timeouts und Zuordnung der Zahlungsart abwickeln. Bargeld überspringt diesen Schritt.
  3. /sign

    Fiskalisieren

    Der Beleg wird nach den nationalen Vorschriften signiert, verkettet und versiegelt.
  4. /issue

    Zustellen (optional)

    Den Beleg digital oder gedruckt ausgeben und seinen Zustellstatus verfolgen.
  5. /journal

    Exportieren

    Prüfrelevante Daten für Abschlüsse, Exporte und Prüfungen abrufen.

Eine Übergabe, kein Neu-Mapping: Das von /pay zurückgegebene Array ftPayItems passt direkt als cbPayItems in /sign. Der fiskalische Beleg verknüpft sich mit der elektronischen Zahlung, ohne Terminaldaten anzufassen.

LÄUFT ÜBERALL, SAUBER VERSIONIERT

Ein Anfrageformat. Jede Umgebung.

Dasselbe v2-Anfrageformat funktioniert gegen den Cloud-Endpunkt und gegen die lokale Middleware unter Windows, Linux und Android. Setzen Sie ein, wo Ihre Architektur es verlangt, Ihre Integration bleibt unverändert.

  • Cloud-Endpunkt
  • Lokal · Windows
  • Lokal · Linux
  • Lokal · Android

  • Semantische Versionierung

    Breaking Changes gibt es nur in Hauptversionen. Abwärtskompatible Änderungen ergänzen Felder, ohne bestehende Modelle zu verändern.

  • Hauptversion festschreiben

    Anfragen ohne Version erhalten die neueste. Produktive Integrationen legen eine Hauptversion fest und steigen in ihrem eigenen Tempo um.

  • Zwei veröffentlichte Referenzen

    Version 2.1 ist aktuell, Version 2.0 bleibt für laufende Integrationen dokumentiert. Ein Migrationsleitfaden beschreibt den Weg von v0.

SELF-SERVICE

Alles, was Sie vor einem Gespräch brauchen.

Beurteilen Sie Machbarkeit und Eignung nach Ihren eigenen Kriterien. Der Stack ist dokumentiert, öffentlich und schon heute testbar.

FAQ

Direkt aus der Dokumentation.

Die Antworten folgen der Dokumentationsplattform. Die Referenz enthält alle Details.

POS System API oder Middleware, was ist der Unterschied?

Die Middleware übernimmt Fiskalisierung, Signatur und Journalisierung. Die POS System API ist die HTTP/JSON-Schnittstelle, die die Middleware bereitstellt. Ihr Kassensystem ruft Signaturkomponenten nie direkt auf.

Brauche ich pro Land eine eigene Integration?

Nein. Die Endpunkte sind in allen Märkten identisch. Länderspezifisches Verhalten ergibt sich aus der CashBox-Konfiguration und den Anfragedaten, nicht aus einer eigenen API-Oberfläche.

Ist eine Wiederholung nach einem Netzwerk-Timeout sicher?

Ja. Wiederholen Sie die Anfrage mit demselben x-operation-id und demselben Body. Die Middleware liefert das ursprüngliche Ergebnis oder wartet auf den Abschluss. Ein geänderter Body liefert 409 Conflict.

Woher stammen die Zugangsdaten?

Das fiskaltrust.Portal stellt x-cashbox-id und x-cashbox-accesstoken mit der CashBox-Konfiguration aus und x-possystem-id, wenn Sie die Variante Ihres Kassensystems registrieren.

Brauche ich /pay bei jeder Transaktion?

Nein. Nutzen Sie /pay, wenn elektronische Zahlungen über die Middleware laufen. Bargeldtransaktionen gehen direkt an /sign. Welche Schritte erforderlich sind, hängt von den Vorschriften des Landes und vom Anwendungsfall ab.

Dieselbe Integration für Cloud und lokal?

Ja. Der Cloud-Endpunkt und die lokale Middleware unter Windows, Linux und Android akzeptieren dasselbe v2-Anfrageformat. Eine Integration läuft ohne Codeänderung gegen alle.

Referenz lesen. Anfrage senden.

Die Referenz 2.1 enthält jedes Modell, Schema und jeden Fehlercode. Der Quickstart auf der Entwicklerseite führt Sie zu einem signierten Sandbox-Beleg.

Referenz 2.1 öffnenEntwicklergespräch anfragen

Sie sprechen mit echten Menschen