Termine empfangen
Drei Schritte. Der dritte darf ablehnen — und das ist der Entwurf, kein Fehlerfall.
1 · Anbieten Core
Petla berechnet die möglichen Zeiten selbst — aus der Verfügbarkeit, die Sie veröffentlicht haben, plus den eigenen Regeln: Dauer je Anliegen, Mindestvorlauf, Buchungshorizont, Mehrtier-Regeln, Fahrzeit bei Hausbesuchen.
Ihr System muss keine Slot-Suche implementieren. Das ist der Grund, warum Format busy ausreicht.
2 · Reservieren Extended
Deshalb ist sie Extended. Alles andere in dieser Schnittstelle ist ein Aufruf von Ihnen an Petla, und genau das lässt einen Praxisrechner hinter einem Router die volle Integration betreiben. Eine Reservierung kann so nicht funktionieren: Damit die Praxis am Tresen nicht 10:20 vergibt, während ein Halter noch das Formular ausfüllt, muss die Sperre jetzt im echten Kalender erscheinen.
Wenn Ihr System keinen eingehenden HTTPS-Endpunkt bereitstellen kann, dürfen Sie appointments.hold nicht erklären.
Wer es kann, stellt zwei Operationen bereit — hold.create und hold.release:
- Ihr System bestimmt die Haltedauer und gibt sie zurück. Petla nimmt keinen Wert an.
- Eine Reservierung muss nach Ablauf automatisch verfallen.
hold.releasemuss idempotent sein.- Eine Reservierung sollte sich in der Oberfläche der Praxis von einem bestätigten Termin unterscheiden lassen.
Ohne Reservierung bucht Petla direkt, und ein verlorenes Rennen erreicht den Tierhalter als fehlgeschlagene Buchung, nachdem er das Formular ausgefüllt hat. Das ist eine schlechtere Erfahrung, keine kaputte — und für Systeme, die vor Ort beim Kunden laufen, der Normalfall.
3 · Buchen und bestätigen Core
Ihr System empfängt den Termin (über den Ereignis-Strom), schreibt ihn in den Kalender und bestätigt:
POST /appointments/{id}/ack
{ "accepted": true, "externalId": "PMS-2026-0091" }Oder Sie lehnen ab — mit maschinenlesbarem Grund
{ "accepted": false, "reason": "SLOT_TAKEN", "message": "…" }| Grund | Bedeutung |
|---|---|
SLOT_TAKEN | Die Zeit wurde zwischen Veröffentlichung und Buchung in Ihrem System vergeben. |
RESOURCE_UNAVAILABLE | Der genannte Behandler arbeitet dann nicht. |
CLIENT_BLOCKED | Die Praxis nimmt diesen Kunden nicht an. |
OUT_OF_HOURS | Außerhalb der tatsächlichen Öffnungszeiten. |
REJECTED_BY_PRACTICE | Ein Mensch hat abgelehnt. |
Weil der Tierhalter wartet. Petla hält die Bestätigungs-E-Mail zurück, bis Ihre Rückmeldung da ist oder das Fenster abläuft.
Danach bestätigt Petla dem Halter trotzdem — und eine später eintreffende Ablehnung wird zu einer Absage, die dem Halter mitgeteilt werden muss. Das ist für alle Beteiligten schlechter, und genau deshalb zählt das Fenster.
externalId ist die Kennung des Termins in Ihrem System. Petla speichert sie und nennt sie in jeder späteren Nachricht zu diesem Termin — auch im Support.
Kunden und Patienten zuordnen Extended
Petla schickt Halter und Tiere so mit, wie Petla sie führt. Ihr System entscheidet, ob das ein bestehender Kunde ist, und sagt es in der Bestätigung:
{ "clientMatch": { "outcome": "matched", "externalClientId": "K-4711" } }outcome ist matched, created oder ambiguous.
ambiguous ist eine echte Antwort und muss benutzt werden. Es bedeutet: Ihr System hat mehr als einen plausiblen Kunden gefunden und sich nicht entschieden. Petla legt das der Praxis vor, statt eine Buchung an die falsche Akte zu hängen.
Petla führt vorher eine eigene Zuordnung durch — exakte E-Mail zuerst, dann Telefon (letzte 9 Ziffern) und Nachname plus Geburtsdatum — und schickt maskierte Beinahe-Treffer mit. Benutzen Sie client.petlaBookerId als stabilen Schlüssel über Buchungen hinweg, statt jedes Mal neu zuzuordnen.
Ein Kunde ohne E-Mail-Adresse wird mit einer synthetischen Adresse unter einer reservierten Domain übergeben (…@petla.internal). Diese Adresse darf nicht angezeigt und niemals angeschrieben werden.
Änderungen aus Ihrem System Extended
Eine Verschiebung oder Absage, die am Tresen passiert, muss gemeldet werden: POST /appointments/{id}/reschedule beziehungsweise /cancel.
Ohne diese Meldung beschreiben Petlas Erinnerungen und die App des Tierhalters weiterhin einen Termin, den es nicht mehr gibt.
Die Versionsnummer je Termin
Jeder Termin trägt version, eine je Termin monoton steigende Ganzzahl. Sie ist die einzige Antwort auf Reihenfolge, Dopplung und Veralten: Wer Version 3 bereits angewendet hat, muss Version 2 ignorieren, wenn sie verspätet eintrifft.
Sortieren Sie nach version, nie nach einem Zeitstempel.