>

Check-in- und Check-out-API

Check-in und Check-out per API mit deinen Systemen verbinden

Mit der Yoffix Open API können andere Systeme Check-ins in Yoffix bestätigen und Check-outs auslösen. Ein Ausweisleser am Büroeingang bestätigt zum Beispiel die Arbeitsplatzbuchung, sobald jemand das Gebäude betritt. Niemand muss dann noch separat in der App einchecken.

Was du einchecken kannst

Die API funktioniert mit Buchungen von Arbeitsplätzen und Zonen, Raumbuchungen, Besuchern und Parkplätzen. Ein zusammen mit dem Arbeitsplatz gebuchter Parkplatz folgt dem Arbeitsplatz: Wird der Arbeitsplatz bestätigt oder ausgecheckt, gilt das auch für den Parkplatz.

API-Key erstellen

Admins erstellen den API-Key unter Einstellungen → Integrationen → Open API. Ein Key gilt für deine ganze Firma. Schick ihn bei jeder Anfrage im Header X-Api-Key mit und bewahre ihn wie ein Passwort im Secret-Speicher deiner Integration auf.

Basis-URL und Endpunkte

Alle Anfragen gehen an https://api.app.yoffix.com/open-api.

POST /v1/check-ins/confirm bestätigt einen Check-in.
POST /v1/check-ins/check-out checkt einen bestätigten Check-in aus.
POST /v1/check-ins/lookup findet die Check-ins, die zu einem Ausweis-Scan passen.
GET /v1/check-ins/{id} liefert einen einzelnen Check-in.

Zwei Wege, eine Buchung anzusprechen

Kennt dein System die Yoffix-ID, schickst du sie direkt mit: die Buchungs-ID für einen Arbeitsplatz, die Kalenderereignis-ID für einen Raum, die Gast-ID für Besucher oder die Parkplatzbuchungs-ID. Weiß dein System nur, wer wo gescannt hat, schickst du stattdessen das Zutrittsereignis mit Ausweis-ID, Leser, Tor oder Tür und Richtung (rein oder raus). Yoffix findet die passende Buchung dann selbst.

Schick in occurredAt den Zeitpunkt des Scans mit. Yoffix prüft ihn gegen das Check-in-Zeitfenster. Ohne diese Angabe zählt der Zeitpunkt, zu dem die Anfrage eingeht.

Check-in per Ausweisleser

Dein Zutrittssystem schickt Ausweis-ID, Leser und Zugangspunkt an den Lookup-Endpunkt.
Yoffix liefert die passenden Check-ins und eine empfohlene Aktion: bestätigen, auschecken oder keine.
Dein System sendet diesen Befehl mit demselben Idempotency-Key und denselben Zutrittsdaten.

Doppelte Check-ins vermeiden

Schick bei jedem Bestätigen und Auschecken einen Idempotency-Key mit, im Header oder im Request-Body. Zutrittssysteme nutzen dafür am besten die Ereignis-ID des Geräts. Kommt derselbe Key zweimal für denselben Befehl, liefert Yoffix die ursprüngliche Antwort und ändert nichts. Wird ein Key für einen anderen Befehl wiederverwendet, schlägt die Anfrage mit DUPLICATE fehl. Einen bereits bestätigten Check-in erneut zu bestätigen, gilt ebenfalls als Erfolg.

Fehler

Jeder Fehler liefert success: false, eine lesbare Meldung und einen Fehlercode, auf den deine Integration reagieren kann. Ein fehlender oder falscher Key ergibt INVALID_API_KEY. Ein Ausweis, den Yoffix niemandem in deiner Firma zuordnen kann, ergibt UNKNOWN_MEDIA, eine unbekannte Buchung SUBJECT_NOT_FOUND. Ein Scan außerhalb des Check-in-Zeitfensters ergibt OUTSIDE_WINDOW. Ist ein Check-in bereits ausgecheckt, abgelaufen oder storniert, kommt ALREADY_CHECKED_OUT, EXPIRED oder CANCELLED zurück.

API-Referenz

Die vollständige Referenz mit Beispielen für Anfragen und Antworten zu jedem Endpunkt findest du unter openapi-docs.yoffix.com. Bei Fragen schreib an support@yoffix.com.