POS-Schnittstelle

#Definition

Eine POS-Schnittstelle ist die technische Brücke zwischen deinem Kassensystem und nachgelagerten Anwendungen. Sie überträgt Bon-Daten, Artikel-Verkäufe, Storni und Rabatte an externe Systeme wie Heptic, an die Buchhaltung oder an ein zentrales Konzern-Reporting. Ohne saubere Schnittstelle bleiben Daten im POS-Silo und manuelle CSV-Exporte fressen Stunden pro Woche.

Technisch sprechen wir von zwei Mustern. Erstens REST-APIs, mit denen du gezielt Daten beim POS abfragen kannst. Zweitens Webhooks, bei denen der POS aktiv Ereignisse an deinen Endpunkt schickt. Die meisten modernen Cloud-POS bieten beides. Ältere Server-POS wie Vectron oder MICROS liefern oft nur Datei-Export oder eine SQL-Replik. Diese Unterschiede entscheiden, wie tief die Kassensystem-Integration gehen kann.

Die typische Datenmenge liegt bei 500 bis 5.000 Bons pro Standort und Tag. Bei einer Kette mit 20 Standorten sind das schnell 50.000 bis 100.000 API-Aufrufe täglich. Saubere Schnittstellen sind deshalb auf Idempotenz, Rate-Limits und Wiederholbarkeit ausgelegt.

Wichtig ist auch die Verzahnung mit der TSE und der KassenSichV. Jeder über die Schnittstelle gelesene Bon trägt eine TSE-Signatur. Diese Signatur muss in der Empfänger-Datenbank gespeichert werden, sonst ist der Audit-Trail bei einer Betriebsprüfung unterbrochen. Saubere Integrationen bilden die TSE-Referenz im internen Datenmodell ab und liefern bei Bedarf einen lückenlosen Export.

#Technische Details

REST-APIs arbeiten mit HTTP-Methoden wie GET, POST und PUT. Ein typischer Endpunkt sieht so aus: GET /v1/orders?location=42&from=2026-05-27T00:00&to=2026-05-27T23:59. Die Antwort kommt als JSON-Liste, paginiert in Blöcken von 50 bis 200 Einträgen. Authentifizierung läuft über OAuth 2.0 oder API-Key im Authorization-Header.

Webhooks sind das Gegenstück. Du registrierst beim POS einen Endpunkt wie https://api.heptic.de/webhooks/lightspeed. Sobald eine Bestellung abgeschlossen wird, schickt der POS einen POST-Request mit dem Payload. Wichtig sind HMAC-Signaturen, damit der Empfänger die Echtheit prüfen kann. Idempotenz-Keys verhindern doppelte Verarbeitung bei Retries.

Standard-Datenfelder über alle POS hinweg sind Bon-Nummer, Zeitstempel, Standort-ID, Artikel-ID, Menge, Einzelpreis, Brutto-Umsatz, MwSt-Satz und Zahlungsmittel. Spezialfelder wie Modifier, Tisch-ID oder Bediener-ID variieren stark zwischen Anbietern. Bei der Integration wirst du Mapping-Logik schreiben, die unterschiedliche Schemata auf ein einheitliches internes Format normalisiert.

Push-Patterns eignen sich für Live-Dashboards und Sofort-Alerts. Pull-Patterns sind robuster und werden als Fallback genutzt, etwa um verpasste Webhooks alle 15 Minuten nachzuholen. Batch-Patterns mit nächtlichem Export kommen bei Legacy-POS zum Einsatz, sind aber latent und für tägliches Reporting ausreichend. Eine ausgewogene Architektur kombiniert alle drei Muster und definiert pro Datentyp das geeignete Pattern.

Rate-Limits sind oft der unerwartete Engpass. Viele POS erlauben nur 100 bis 500 API-Calls pro Minute pro Standort. Bei aggressiven Pull-Intervallen läuft die Schnittstelle in HTTP 429 und Daten gehen verloren. Saubere Adapter respektieren Rate-Limits, queuen überschüssige Requests und führen Exponential-Backoff bei Fehlern durch. Diese Mechanik ist unsichtbar, aber entscheidend für stabile Produktion.

#Praxisbeispiel

Eine Burger-Kette mit 23 Standorten und unterschiedlichen POS-Generationen brauchte ein einheitliches Reporting. Sechzehn Standorte fuhren Lightspeed K-Series mit REST-API und Webhook. Vier Standorte hatten ältere Orderbird-Installationen mit nur REST-API. Drei Standorte liefen auf Vectron mit Datei-Export per SFTP.

Das Integrationsteam baute drei Adapter. Für Lightspeed eine Push-Pull-Kombination mit Webhook für neue Bestellungen und REST-Backfill alle 30 Minuten als Sicherung. Für Orderbird einen reinen REST-Pull alle fünf Minuten mit Idempotenz-Key pro Bon. Für Vectron einen nächtlichen SFTP-Job um 03:00 Uhr mit Schema-Mapping auf das interne Datenmodell.

Die Latenz lag bei Lightspeed unter 15 Sekunden, bei Orderbird unter fünf Minuten, bei Vectron bei einem Tag. Das Reporting wurde so gestaltet, dass tagesaktuelle Werte erst nach 04:00 Uhr als final markiert wurden. Die Lücke zwischen Soll und Ist im POS lag konstant unter 0,3 Prozent. Manuelle Excel-Übergaben fielen weg. Der Operations-Manager spart pro Woche rund 14 Stunden Aggregation und kann den Wareneinsatz pro Standort jeden Morgen vergleichen.

#Schnittstellen-Anbieter und ihre Reife

Cloud-native POS wie Lightspeed K-Series, Toast und Square bieten breite, dokumentierte REST-APIs mit Webhook-Support. Authentifizierung läuft über OAuth 2.0, Rate-Limits sind klar dokumentiert. Anbindung in zwei bis fünf Tagen ist realistisch.

Mittlere DACH-POS wie Orderbird, Gastronovi und Ready2Order bieten REST-APIs, oft mit eingeschränktem Webhook-Support. Anbindung dauert eine bis zwei Wochen. Modifier und Sondertypen variieren stark und brauchen Mapping-Aufwand.

Legacy-POS wie Vectron, MICROS Simphony und ältere Hypersoft-Installationen arbeiten oft mit Datei-Export per SFTP oder direkter SQL-Replik. Anbindung dauert zwei bis sechs Wochen, je nach Datenbank-Version und Berechtigungen. Hier liegt der Engpass meist nicht in der Technik, sondern im Provider-Kontakt und im internen IT-Zugang des Standorts.

#Häufige Fehler

• Schnittstelle wird ohne Rate-Limit-Handling gebaut. Bei 30 Standorten und parallelen Abfragen wirft die POS-API HTTP 429 und Daten gehen verloren.
• Webhook-Endpunkte werden ohne HMAC-Signatur gebaut. Theoretisch kann jeder fremde Daten in dein System einschleusen, ein DSGVO- und Sicherheitsrisiko.
• Idempotenz wird nicht abgesichert. Bei Webhook-Retries werden Bons doppelt verbucht und das Reporting zeigt überhöhte Umsätze.
• Storno-Felder werden ignoriert oder falsch interpretiert. Manche POS senden Storno als negativen Betrag, andere als separates Flag, andere als eigenen Endpunkt.
• Time-Zones werden inkonsistent gehandhabt. Ein POS sendet UTC, der nächste lokale Zeit. Wenn das Mapping schlampt, springt das Tages-Reporting um zwei Stunden und Tagesabschlüsse landen am falschen Datum.

#Datenfluss-Monitoring

Eine Schnittstelle ohne Monitoring ist ein Risiko. Saubere Integrationen tracken pro Standort die Anzahl empfangener Bons pro Stunde, die durchschnittliche Latenz und die Fehlerrate. Bei Abweichungen vom Erwartungswert (etwa nachts kein Traffic an einem Standort, der bis 02:00 Uhr Service hat) löst das System einen Alert aus. Operativ verhindert das stille Datenlücken, die erst beim Monatsabschluss auffallen würden.

Ein bewährtes Pattern ist die tägliche Reconciliation gegen den Z-Bon. Das externe System summiert alle empfangenen Bons des Tages und gleicht die Summe mit dem Z-Bon-Totalbetrag ab. Differenzen über 0,5 Prozent lösen einen Alert und werden manuell geprüft. So bleibt die Schnittstelle nicht nur technisch, sondern auch betriebswirtschaftlich verlässlich.

#So unterstützt Heptic

Heptic Integrationen bietet vorgefertigte Adapter für die gängigen DACH-Kassensysteme wie Lightspeed, Orderbird, Gastronovi, Vectron, Simphony oder Ready2Order. Jeder Adapter kapselt die Eigenheiten der jeweiligen API und liefert ein einheitliches Datenmodell für Bons, Artikel und Storni. Idempotenz, Retry-Logik und Schema-Mapping sind integriert. Heptic Intelligence konsolidiert die Daten standortübergreifend und macht aus heterogenen POS-Landschaften ein einheitliches Reporting. Heptic ist kein Kassensystem und ersetzt deinen POS nicht.

Häufige Fragen

REST-API oder Webhook, was ist besser?

Beide haben ihre Stärken. Eine REST-API eignet sich für initiale Abfragen, historische Daten und gezielte Pulls. Webhooks sind ideal für Echtzeit-Benachrichtigungen, etwa wenn eine Bestellung abgeschlossen wird. In der Praxis kombinierst du beides. REST für Stammdaten und Backfill, Webhook für Live-Ereignisse. Wer nur REST nutzt, pollt häufiger und belastet die API unnötig. Wer nur Webhooks nutzt, verliert bei einem Ausfall die Sicht.

Welche Daten werden typisch synchronisiert?

Standard-Felder sind Bon-Nummer, Zeitstempel, Standort-ID, Artikel-ID, Artikelname, Menge, Einzelpreis, Brutto-Umsatz, Mehrwertsteuersatz, Zahlungsmittel und Bediener-ID. Dazu kommen Storno-Flag, Rabatt-Code und TSE-Signatur. Manche POS liefern auch Tisch-ID, Gäste-Anzahl und Modifier wie Beilagen oder Sonderwünsche. Je mehr Felder, desto präziser dein Reporting. Wenig POS liefern Modifier sauber strukturiert, das ist häufig der Engpass.

Was ist der Unterschied zwischen Push und Pull?

Bei Pull fragt deine externe Anwendung in festen Intervallen beim POS nach neuen Daten. Das ist robust, aber latent. Bei Push schickt der POS aktiv Daten an einen Webhook-Endpunkt, sobald ein Ereignis eintritt. Das ist schneller, aber empfindlicher gegen Netzwerk-Ausfälle. Saubere Integrationen kombinieren beides. Push für Echtzeit-Reaktion, Pull als Sicherungsnetz für verlorene Webhooks.

Welche Authentifizierung ist Standard?

OAuth 2.0 mit Client-Credentials ist heute der Branchenstandard für REST-APIs. Einzelne POS-Anbieter nutzen noch API-Keys mit Bearer-Token. Webhooks werden über HMAC-Signaturen abgesichert, damit der Empfänger die Echtheit prüfen kann. Wichtig ist die Token-Rotation alle drei bis zwölf Monate und ein dedizierter Service-Account pro Integration. Persönliche User-Logins als API-Zugang sind ein Sicherheitsrisiko und nicht DSGVO-konform.

Zuletzt aktualisiert: Mai 2026