WFM-Integrations-API: Das Vertragsmuster für besucherfrequenzgetriebene Schichtanpassungen

Wofür eine WFM-Integrations-API gut ist

Die meisten Einzelhandels- und Veranstaltungsbetriebe führen zwei Systeme, die miteinander reden müssen. Eine Workforce-Management-Plattform (WFM) verwaltet den Dienstplan: Verträge, Schichten, Tausche, Lohnabrechnung. Eine Personenzählplattform verwaltet das Nachfragesignal: wie viele Besucher das Gebäude betraten, wie sich das nach Stunde und Zone aufschlüsselt, wie es im Vergleich zur Prognose verläuft. Keines der Systeme kann die Aufgabe des anderen übernehmen, und die Verzahnung wird fast immer über einen API-Vertrag zwischen beiden gelöst, nicht über eine gemeinsame Datenbank.

Dieser Beitrag richtet sich an die Ingenieurin oder den Solutions Architect auf einer der beiden Seiten dieses Vertrags. Er führt durch die Integrationsform, die sich in der Produktion bewährt hat: wie sich die beiden Systeme authentifizieren, wie Schichtpläne und Prognosen synchronisiert werden, welche Ereignisse Kapazitätsänderungen tragen, wie realisierte Arbeitszeit zurückgeschrieben wird, und welche Betriebsentscheidungen (Idempotenz, Wiederholungen, Sicherheit) darüber entscheiden, ob die Integration jahrelang ruhig läuft oder jeden zweiten Samstag bricht. Sie ist technologie-, nicht herstellergetrieben. Dieselbe Form gilt, ob die WFM-Seite Ariadnes Employees Planner ist oder eine separat lizenzierte Plattform wie SAP, Workday, UKG, Quinyx, Deputy, Humanity oder Microsoft Shifts. Die Integrationsform ist dieselbe, die Feldnamen unterscheiden sich.

Der Knotenpunkt für das, was Ariadne integriert, sind die Plattform-Integrationen. Dieser Beitrag liegt eine Ebene tiefer: nicht der Katalog, sondern der Vertrag.

Die zwei Systeme und die vier Flüsse

Eine funktionierende WFM-Integration mit einer Zählplattform lässt sich auf vier Datenflüsse zurückführen. Alles andere ist eine Variante.

1. Schichtplan-Synchronisation. Die WFM-Plattform veröffentlicht den aktuellen und kommenden Dienstplan an die Zählplattform, damit die Zählseite die Personalabdeckung auf demselben Dashboard gegen die Nachfrage darstellen kann.
2. Prognose-Veröffentlichung. Die Zählplattform veröffentlicht eine zukunftsgerichtete Nachfrageprognose (Besucher pro Stunde, je Zone, je Filiale) an die WFM-Plattform, damit der Planer Schichten gegen den erwarteten Verkehr dimensionieren kann.
3. Intraday-Kapazitätsereignisse. Wenn die Live-Bedingungen von der Prognose abweichen (eine geschäftigere oder ruhigere Stunde als erwartet), emittiert die Zählplattform ein Ereignis, auf das die WFM noch innerhalb des Tages reagieren kann.
4. Rückschreibung der realisierten Arbeitszeit. Nach Abschluss einer Handelsperiode meldet die WFM-Plattform die tatsächlich geleistete Arbeit an die Zählplattform zurück, damit der Bericht zu Nachfrage gegen Abdeckung mit der Realität abgeglichen wird, nicht mit dem Plan.

Jeder davon ist ein eigener Endpunkt oder ein eigenes Topic. Sie teilen sich ein Auth-Modell, ein Identitätsmodell für Filialen und Zonen sowie ein Fehlermodell, werden aber nicht in einen Mega-Endpunkt zusammengefasst. Der Grund ist operativ: Der Fehlermodus eines Prognose-Pushs unterscheidet sich vom Fehlermodus einer Schreibung realisierter Arbeitszeit, und beide als eine Fläche zu behandeln, macht beide schwerer zu debuggen.

Authentifizierung

Zwei Muster dominieren. Wählen Sie eines und wenden Sie es einheitlich auf alle vier Flüsse an; sie zu mischen, ist der häufigste Grund, warum Integrationen über die Zeit driften.

• OAuth 2.0 Client Credentials. Die WFM- und die Zählplattform tauschen Client-ID und Client-Secret gegen ein kurzlebiges Bearer-Token (üblicherweise eine Stunde). Jede Anfrage an das andere System trägt das Token in einem Authorization-Header. Token-Rotation ist automatisch, Secret-Rotation ist betreibergesteuert, und der Entzug ist zentralisiert. Das ist die richtige Voreinstellung für jede Integration, die organisatorische Grenzen überschreitet.
• Langlebiger API-Schlüssel. Ein einzelnes Geheimnis, das als Header bei jeder Anfrage gesendet und manuell rotiert wird. Einfacher zu implementieren, schwächer für die Produktion. Akzeptabel, wenn beide Systeme von derselben Organisation betrieben werden und die Schlüsselrotation auf einem Kalender liegt; nicht akzeptabel, wenn die Integration mehrere Mandanten überspannt oder wenn die WFM Multi-Tenant-SaaS ist.

Beide Muster setzen auf HTTPS mit TLS 1.2 oder höher auf. Mutual TLS taucht im regulierten Einzelhandel und in krankenhausnahen Liegenschaften auf, wo die WFM-Plattform verlangt, dass die Zählplattform ein Client-Zertifikat zusätzlich zum Bearer-Token vorlegt. Für die meisten Einzelhandelsbereitstellungen ist es überdimensioniert und für Krankenhausbetriebe Standard.

Identität: Filialen, Zonen und Schichten

Bevor ein Fluss läuft, brauchen die beiden Systeme eine gemeinsame Karte der Welt. Eine Filiale in der WFM ist eine numerische oder alphanumerische Standort-ID. Eine Filiale in der Zählplattform ist ein Gebäude mit Sensoren. Beide müssen aufeinander zeigen, sonst ist jede spätere Anfrage mehrdeutig.

Ein sauberes Identitätsmodell hat drei Ebenen. Die Standort-ID ist das Gebäude. Die Zonen-ID ist eine Untergliederung innerhalb des Gebäudes (Verkaufsfläche, Anproben, Backoffice, eine Abteilung). Die Schicht-ID ist die Arbeitseinheit, die der WFM gehört. Beide Systeme behalten ihre eigenen Primärschlüssel und exponieren eine Mapping-Tabelle: WFM_site_id <-> counting_site_id, WFM_zone_id <-> counting_zone_id. Das Mapping wird auf einer Seite gehalten, von der anderen abfragbar, und wird auditiert, wenn Filialen eröffnen, schließen oder umnummeriert werden.

Zwei Fehlermuster sind nennenswert. Das erste ist die stille Umbenennung: Eine Filiale wird auf der WFM-Seite umnummeriert, ohne dass das Mapping aktualisiert wird, und die Prognose veröffentlicht weiterhin auf eine veraltete ID. Das empfangende System weist das Payload entweder zurück (gut) oder akzeptiert es und die Prognose erscheint schlicht nicht im Dashboard der neuen Filiale (schlecht). Der Fix ist ein täglicher Abgleichsjob, der die Filiallisten beider Systeme vergleicht und Abweichungen sichtbar macht. Das zweite ist die Zonen-Gabelung: Jemand splittet eine Abteilung in der WFM, ohne es der Zählseite zu sagen, und Pro-Zonen-Prognosen veröffentlichen in eine Zone, die im WFM-Baum nicht mehr existiert. Die Zonen-Identität braucht ein Versionsfeld, das beide Seiten inkrementieren.

Fluss 1: Schichtplan-Synchronisation (WFM zu Zählung)

Die Schichtplan-Synchronisation ist der einfachere der beiden ausgehenden Flüsse. Die WFM veröffentlicht den aktuellen Dienstplan: wer arbeitet, in welcher Rolle, in welcher Zone, für welche Intervalle. Die Zählplattform speichert ihn als Personalabdeckung und zeigt ihn neben der Nachfragereihe.

Die minimal nützliche Payload ist eine Liste von Schichten, jede mit einer Schicht-ID, einer Standort-ID, einer Zonen-ID (optional, Standard ist die gesamte Filiale), einem Startzeitstempel in ISO 8601 mit Offset, einem Endzeitstempel, einer Kopfzahl für die Schicht und einem Rollen-Tag. Personenbezogene Daten (Mitarbeitername, Mitarbeiter-ID) sind für die Berichterstattung Nachfrage gegen Abdeckung nicht erforderlich und sollten aus diesem Fluss weggelassen werden, sofern nicht eine konkrete Funktion auf der Zählseite sie verlangt. Die Zählseite berichtet eine Abdeckungskurve, sie baut kein Personalregister.

Die Form funktioniert gut als täglicher inkrementeller Push plus wöchentlicher Voll-Snapshot. Inkrementelle Pushes tragen nur die Schichten, die sich seit dem letzten Cursor geändert haben; der wöchentliche Snapshot ist der Abgleichspunkt, der alles auffängt, was die Inkrementellen verpasst haben. Beide Endpunkte akzeptieren dieselbe Payload-Form und unterscheiden sich nur in der Semantik, was den WFM-Client einfach hält.

Fluss 2: Prognose-Veröffentlichung (Zählung zu WFM)

Der Prognose-Fluss ist derjenige, der die Integration rechtfertigt. Die Zählplattform besitzt das Nachfragemodell, berechnet eine zukunftsgerichtete Besucherprognose und veröffentlicht sie an die WFM als Zeitreihe, auf die der Planer reagieren kann.

Die Payload ist eine Liste von Prognosepunkten. Jeder Punkt trägt eine Standort-ID, eine optionale Zonen-ID, ein Prognoseintervall (üblicherweise eine Stunde, manchmal fünfzehn Minuten bei schnellen Formaten), einen Startzeitstempel, eine vorhergesagte Besucherzahl und ein Konfidenzband. Ein Versionsfeld auf der Payload unterscheidet die veröffentlichte mittelfristige Prognose von späteren Verfeinerungen. Eine Modell-ID und ein generated-at-Zeitstempel werden mitgeführt, damit die WFM auditieren kann, welches Modell die Zahlen produziert hat.

Die Veröffentlichungsfrequenz hängt vom Dienstplanzyklus der WFM ab. Ein zweiwöchiger Dienstplanhorizont bedeutet, dass die mittelfristige Prognose einmal wöchentlich vierzehn Tage im Voraus veröffentlicht wird und die vorherige Veröffentlichung für dieses Fenster ersetzt. Eine tägliche Verfeinerung veröffentlicht sieben Tage im Voraus und überschreibt die Tagesscheibe. Der Vertrag sollte explizit machen, welche Veröffentlichung welche ablöst: Die richtige Regel ist last-write-wins nach Version und generated-at, gebunden an (site, zone, interval). Ohne diese Regel können zwei gleichzeitige Veröffentlichungen die WFM in einen inkonsistenten Zustand bringen.

Fluss 3: Intraday-Kapazitätsereignisse

Der dritte Fluss unterscheidet eine ernsthafte Integration von einem nächtlichen Batch. Die Realität weicht innerhalb des Tages von der Prognose ab, und die WFM muss rechtzeitig davon erfahren, um etwas tun zu können. Zwei Muster funktionieren:

• Webhook-Push. Die Zählplattform sendet einen HTTPS-POST an einen WFM-seitigen Endpunkt, wenn eine definierte Bedingung erfüllt ist: Eine Stunde liegt um mehr als einen konfigurierten Prozentsatz über oder unter Prognose im Trend, eine Zone hat einen Kapazitätsschwellenwert überschritten, die Projektion für die nächste Stunde hat sich um mehr als eine konfigurierte Toleranz verschoben. Der Webhook trägt dieselben Identitätsfelder wie die Prognose-Veröffentlichung sowie den Auslösegrund und die vorgeschlagene Aktion. Die WFM legt ihre eigene Logik darüber.
• Pollbarer Nowcast. Die Zählplattform stellt einen latenzarmen Endpunkt bereit, der die aktuelle kurzfristige Prognose zurückgibt. Die WFM pollt alle fünf oder zehn Minuten und wendet dieselbe Bedingungslogik auf ihrer eigenen Seite an.

Webhooks sind einfacher, wenn sie funktionieren, und schwerer, wenn der Empfänger ausgefallen ist. Polling ist schwerer, wenn das Netz belegt ist, und einfacher, wenn es nur lückenhaft funktioniert. Eine robuste Integration unterstützt üblicherweise beides und lässt den WFM-Betreiber wählen. Die Webhook-Seite braucht eine dokumentierte Wiederholungsrichtlinie: Eine sinnvolle Voreinstellung sind drei Wiederholungen mit exponentiellem Backoff (Start eine Sekunde, Faktor zwei, Maximum dreißig), mit einem Circuit Breaker, der den Kanal nach einem anhaltenden 5xx-Muster für fünfzehn Minuten anhält und den Betreiber alarmiert.

Fluss 4: Rückschreibung der realisierten Arbeitszeit

Der letzte Fluss schließt die Schleife. Nachdem eine Handelsperiode endet (ein Tag, eine Woche, vierzehn Tage), meldet die WFM, was tatsächlich gearbeitet wurde: geplante Stunden, geleistete Stunden, Lücken, Überhänge, Tausche, Nichterscheinen. Die Zählplattform speichert das gegen dieselbe Identität aus Filiale, Zone und Intervall und nutzt es, um den Bericht Nachfrage gegen Abdeckung abzugleichen.

Die Payload ist als geschlossene Zeitreihe geformt. Jede Zeile trägt Filiale, Zone, Intervallstart, geplante Stunden, geleistete Stunden, geplante Kopfzahl, tatsächliche Kopfzahl und einen Ausnahme-Flag für alles, was einen Eingriff der Führung erforderte. Der Fluss läuft üblicherweise täglich, gepostet kurz nach Filialschluss. Ein wöchentliches Nachsenden ist ein nützliches Sicherheitsnetz, weil Arbeitszeitanpassungen (Korrekturen, späte Freigaben) ein bis zwei Tage nach der ursprünglichen Schreibung eintreffen können.

Die abgeglichene Sicht, die das ermöglicht, ist das wertvollste Artefakt der Integration: eine Nachfragekurve, eine geplante-Abdeckungs-Kurve und eine tatsächliche-Abdeckungs-Kurve, übereinandergelegt, Periode für Periode, Filiale für Filiale. Das ist der Bericht, gegen den eine Regionalleitung Personalentscheidungen verteidigt, und die WFM kann ihn ohne die Nachfragereihe nicht zeichnen, und die Zählplattform kann ihn ohne die Rückschreibung der realisierten Arbeitszeit nicht zeichnen.

Idempotenz und Fehlerbehandlung

Produktive Integrationen scheitern. Der Fehlermodus, der Wochenend-Schichtpläne zerlegt, ist nicht ein einzelner Fehler; es ist ein Duplikat. Ein Wiederholungsversuch passiert, weil das Netz ein Timeout hatte, der Empfänger die ursprüngliche Anfrage bereits angenommen hat, und ein doppelter Schichteintrag oder ein doppelter Prognosepunkt in der WFM landet. Idempotenz ist die Vertragseigenschaft, die das verhindert, und sie muss eingebaut werden, nicht nachgerüstet.

Das Muster, das funktioniert, ist ein Idempotenzschlüssel auf jeder verändernden Anfrage. Der Absender erzeugt eine UUID im Moment, in dem die Anfrage gebaut wird, und legt sie in einen Idempotency-Key-Header. Der Empfänger speichert den Schlüssel (und die Antwort) für mindestens 24 Stunden. Eine zweite Anfrage mit demselben Schlüssel gibt die ursprüngliche Antwort unverändert zurück. Stripe hat das Muster populär gemacht; es funktioniert genauso gut für WFM-Payloads, weil der Empfänger nicht wissen muss, ob das Duplikat von einem Netz-Retry, einer Webhook-Wiederzustellung oder einem Betreiber kam, der ein Backfill zweimal gestartet hat.

Fehler fallen in drei Eimer, jeder mit einer anderen Antwortform. 4xx-Fehler sind Payload-Probleme (falsche Identität, fehlerhafter Zeitstempel, fehlendes Pflichtfeld). Der Antwortkörper listet das beanstandete Feld auf, und der Absender wiederholt nicht, sondern korrigiert und reicht neu ein. 5xx-Fehler sind Empfänger-Probleme. Der Absender wiederholt mit exponentiellem Backoff und respektiert einen etwaigen Retry-After-Header. 409-Konflikte sind Versionsprobleme (zwei Schreiber, last-write-wins verletzt). Die Antwort trägt die aktuelle Serverversion, und der Absender wiederholt entweder mit der neuesten Version oder hebt den Konflikt an einen Betreiber.

Sicherheit und Betriebshygiene

Die Integration überschreitet eine Grenze zwischen zwei Produktivsystemen und häufig zwischen zwei Organisationen. Das Sicherheitsmodell muss an sechs Punkten explizit sein:

• Transport. TLS 1.2 oder höher, moderne Cipher-Suites und HSTS auf dem Empfänger. Klartext-HTTP ist für keinen Fluss eine Option.
• Authentifizierung. OAuth 2.0 Client Credentials als Voreinstellung, mit dokumentierter Secret-Rotationsfrequenz und einem Widerrufspfad, der innerhalb von Minuten wirkt.
• Autorisierung. Scopes, die auf Flüsse abbilden. Ein Schichtplan-Synchronisations-Client kann keine Prognosen veröffentlichen; ein Prognose-Veröffentlichungs-Client kann keine realisierte Arbeitszeit schreiben. Das Least-Privilege-Prinzip gilt wie in jedem anderen System.
• Rate Limits. Pro Endpunkt dokumentiert, mit 429-Antworten, die einen Retry-After-Header tragen. Die Webhook-Seite sollte ebenfalls abgesichert sein, damit ein fehlerhafter Absender die WFM nicht überfluten kann.
• Audit-Logging. Jede Anfrage mit ihrem Idempotenzschlüssel, Absender-ID und Antwortcode, lange genug aufbewahrt, um eine strittige Lohnperiode aufklären zu können. Die meisten Einzelhändler legen sich auf zwölf Monate fest.
• Datenminimierung. Personenbezogene Daten überqueren die Grenze nur, wo es nötig ist. Berichterstattung zu Nachfrage gegen Abdeckung braucht keine Mitarbeiternamen; ein Lohnabgleich vielleicht schon. Zwei Clients, zwei Scopes, zwei Payload-Formen sind sauberer als ein fetter Client, der alles sieht.

Wie Ariadne hineinpasst

Ariadne sitzt auf der Zählseite der Integration. Die Personenzählung-Plattform produziert die Nachfragereihe, die die WFM konsumiert: Besucher pro Stunde je Filiale, optional je Zone, mit einer Prognose und einem Intraday-Aktualisierungskanal. Dieselben Zahlen speisen Ariadnes eigenen Employees Planner für Teams, die ein Produkt durchgängig wollen, oder sie werden über dieselbe Vertragsform an eine separat lizenzierte WFM exportiert.

Ariadne misst dies mit Hybrid Fusion, der patentierten kamerafreien Methode. Time-of-Flight-Tiefensensorik zählt an den Eingängen jeden Besucher und erfasst Geometrie statt Bilder, während die patentierte Signalerfassung die Bewegung im Innenraum verfolgt und die Signale erkennt, die ein Telefon aussendet, selbst im Flugmodus. Der Sensor streamt beide Datenströme an Ariadne, wo Hybrid Fusion sie zu einer Trajektorie pro Besuch zusammenführt und Zählwerte, Verweildauer und Wege berechnet. Die Datenströme tragen keine Identifikatoren: keine MAC-Adresse, keine Geräte-ID, keine biometrischen Daten, und es ist keine Kamera beteiligt. Identifikatoren werden nur gespeichert, wenn ein Besucher ausdrücklich zustimmt, was die Methode datenschutzfreundlich und außerhalb des biometrischen Bereichs hält.

Zwei Integritätspunkte sind für die Beschaffung auf der WFM-Seite wichtig. Erstens: Das Nachfragesignal, das Ariadne veröffentlicht, ist eine Zahl, kein Strom erkannter Personen. Die WFM empfängt eine Ganzzahl pro Intervall, keinen Ereignisstrom identifizierbarer Besuche. Das hält die Integration außerhalb des Bereichs biometrischer Daten und außerhalb der meisten der schwersten DSGVO-Pflichten, die die WFM treffen könnten, wenn ein Anbieter kameragewonnene Daten in ihre Grenze schieben würde. Zweitens: Die Zählung selbst ist unabhängig von der Conversion am Point of Sale: Eine geschäftige, aber nicht konvertierende Stunde ist in der Prognose sichtbar, wo eine reine Transaktionsprognose sie übersehen würde. Die oben beschriebene Vertragsform ist in beiden Fällen dieselbe; die vorgelagerte Messung ist das, was das Nachfragesignal überhaupt erst integrierenswert macht. Die Datenverarbeitung ist in der Datenschutzerklärung dargelegt.

Für ein Team, das die Integration vor der Verpflichtung prüft, ist der Test, ob jeder der vier Flüsse durchgängig gegen eine Staging-Umgebung ausgeführt werden kann, mit einem Idempotenzschlüssel, mit einem absichtlichen Wiederholungsversuch und mit einem absichtlichen Fehler. Eine Integration, die diese Übung im Staging nicht übersteht, übersteht auch kein beschäftigtes Wochenende in der Produktion.

FAQ

Erfordert die Integration irgendwo im Pfad Kameras?

Nein. Ariadne zählt mit Hybrid Fusion: Time-of-Flight-Tiefensensorik plus patentierte Signalerfassung, nie mit Kameras. Time-of-Flight erfasst Geometrie statt Bilder, und die Signalerfassung erfasst standardmäßig keine MAC-Adresse, sodass die Messung ohne Video, ohne Gesichter und ohne biometrische Daten auskommt.

Ist die Nachfragereihe Echtzeit oder Batch?

Beides. Die mittelfristige Prognose ist eine Batch-Veröffentlichung im Dienstplanzyklus (üblicherweise wöchentlich, mit einer täglichen Auffrischung). Der Intraday-Kapazitätsfluss ist ereignisgesteuert: Ein Webhook feuert, wenn die Bedingungen einen konfigurierten Schwellenwert überschreiten, oder die WFM pollt einen latenzarmen Nowcast-Endpunkt alle paar Minuten. Die meisten produktiven Bereitstellungen nutzen die Batch-Veröffentlichung für die Planung und den Ereigniskanal für Anpassungen im Tagesverlauf.

Was, wenn die von uns genutzte WFM-Plattform heute nicht auf der Integrationsseite steht?

Die in diesem Beitrag beschriebene Vertragsform ist plattformneutral: Jede WFM, die einen authentifizierten POST einer Zeitreihe annehmen, einen Schichtplan-Endpunkt bereitstellen und einen Webhook konsumieren kann, ist kompatibel. Die hier genannten Plattformen sind illustrative Beispiele für WFM-Werkzeuge, die ein Einzelhändler oder eine Veranstaltungsstätte bereits führen kann. Konkrete Konnektoren entwickeln sich über die Zeit; der Integrationsknotenpunkt ist die aktuelle Quelle der Wahrheit für das, was dokumentiert und unterstützt ist.