Verfügbarkeit veröffentlichen Core
Ihr System veröffentlicht, wann die Praxis buchbar ist. Ohne diesen Fluss kann Petla nur Zeiten anbieten, die es sich ausgedacht hat.
Zwei Formate. Sie wählen genau eines.
Beide sind gleichwertig zulässig. Sie implementieren eines und erklären in PUT /capabilities, welches.
busy — was belegt ist
Das günstigere Format und der empfohlene Einstieg. Sie veröffentlichen die Intervalle, in denen eine Ressource nicht verfügbar ist. Petla zieht sie von den Öffnungszeiten ab, welche die Praxis bei Petla hinterlegt hat.
PUT /availability
{
"resourceId": "kal-1",
"from": "2026-09-07",
"to": "2026-11-02",
"timeZone": "Europe/Berlin",
"busy": [
{ "start": "2026-09-07T09:00:00", "end": "2026-09-07T09:30:00" },
{ "start": "2026-09-07T14:00:00", "end": "2026-09-07T18:00:00" }
]
}Beide Formate gehen an denselben Endpunkt. Petla antwortet mit 202 Accepted — nicht mit 200: Die Neuberechnung der Slots läuft asynchron, die Antwort bestätigt also die Annahme und nicht das fertige Ergebnis.
202 Accepted
{
"resourceId": "kal-1",
"from": "2026-09-07",
"to": "2026-11-02",
"receivedAt": "2026-09-03T16:02:11Z",
"accepted": 118,
"dropped": 0
}Ein Zeitraum, der [from, to] verlässt, wird verworfen statt Ihre Abdeckung zu erweitern — ein busy-Intervall über to hinaus würde einen Tag sperren, den Sie nicht veröffentlicht haben, und ein offenes windows-Ende würde einen verkaufen. Bis zum 04.09.2026 geschah das stumm: 400 Intervalle, von denen 12 über den Rand liefen, ergaben dieselbe 202 wie 400, die alle ankamen.
⛔ Die Einheit ist ein Zeitraum nach dem Schnitt um Mitternacht, nicht ein Eintrag, den Sie gesendet haben: ein Fenster von 22:00–02:00 sind zwei. Wer accepted gegen die eigene Array-Länge rechnet, liest eine korrekte Veröffentlichung als gewachsen.
⚠️ Ein kleines dropped ist oft normal — ein Fenster über die letzte veröffentlichte Mitternacht verliert sein Ende. Auffällig ist ein dropped, das Sie sich nicht erklären können.
Ein Eintrag, von dem kein Stück im Zeitraum liegt, ist ein 400 validation_failed mit fields["busy.3"] = "outside_published_range". Er hat keine Wirkung, und stillschweigend angenommen hielten Sie etwas für veröffentlicht, das nicht existiert.
⚠️ Die naheliegende Regel — alles außerhalb ablehnen — wurde geprüft und verworfen: sie lehnt ein Fenster über die letzte Mitternacht ab und ein busy-Intervall, das in die frühen Stunden von from hineinlief. Beides ist der echte Kalender einer Praxis.
Eine Veröffentlichung ist ein Schreibvorgang und trägt deshalb die Kopfzeile Idempotency-Key. Wiederholen Sie nach einer Zeitüberschreitung mit demselben Schlüssel — sonst kann Ihr eigener Wiederholungsversuch einen Zeitraum ein zweites Mal ersetzen. Dieselbe Kopfzeile gilt für /reschedule und /cancel.
Dieses Format trägt überhaupt keine Patientendaten — nur Zeitintervalle. Deshalb ist es der empfohlene erste Schritt: Es verhindert Doppelbuchungen und wirft datenschutzrechtlich keine einzige Frage auf.
windows — wann geöffnet ist
Sie veröffentlichen die buchbaren Fenster selbst, abgeleitet aus Ihrem eigenen Dienstplan. Petla benutzt dann diese statt der eigenen Konfiguration.
PUT /availability
{
"resourceId": "kal-1",
"from": "2026-09-07",
"to": "2026-11-02",
"timeZone": "Europe/Berlin",
"windows": [
{ "date": "2026-09-07", "start": "08:00", "end": "12:00", "modalities": ["PRAXIS"] },
{ "date": "2026-09-07", "start": "14:00", "end": "18:00", "modalities": ["PRAXIS", "HOME_VISIT"] }
]
}Jedes Fenster trägt sein eigenes date, weil eine Veröffentlichung einen Zeitraum angibt. Ein Fenster, dessen end vor seinem start liegt, geht über Mitternacht. Ohne modalities gilt ausschließlich PRAXIS.
Regeln, die für beide Formate gelten
Was Sie senden, ersetzt den genannten Zeitraum für die genannte Ressource vollständig. Es ist kein Delta: Was diese Ressource vorher über diese Tage gesagt hat, ist danach weg.
Ein leeres Array bedeutet aber nicht in beiden Formaten dasselbe. Die beiden Arrays enthalten Gegenteiliges. "windows": [] ist ein Tag ohne buchbares Fenster — also geschlossen. "busy": [] ist ein Tag, an dem nichts belegt ist — also vollständig offen, mit den unveränderten Öffnungszeiten der Praxis. Sagen Sie „geschlossen“ so, wie Ihr Format es sagt.
Ein Rumpf ohne busy und ohne windows ist ein 400. ⚠️ Viele JSON-Bibliotheken lassen leere Arrays beim Serialisieren weg — prüfen Sie, dass Ihre das nicht tut, sonst ist „heute nichts“ von einer unvollständigen Anfrage nicht zu unterscheiden.
- Ein Zeitraum umfasst höchstens 380 Tage.
- Der Horizont sollte mindestens 8 Wochen betragen — und wenn Ihr Dienstplan kürzer reicht, sagen Sie uns Ihren. Die Zahl ist kein Grenzwert, den etwas prüft: sie sagt, wie weit im Voraus ein Tierhalter buchen kann, und ein kürzerer Horizont ist eine Eigenschaft der Praxis, keine Nichteinhaltung. Was wir wissen müssen, ist welcher es ist.
- Veröffentlichen Sie möglichst innerhalb von 5 Minuten nach einer Änderung. Wenn Ihr System das nicht kann, veröffentlichen Sie mindestens einmal pro Öffnungstag und geben Sie Ihr Intervall an — Petla bemisst danach, wie lange eine Reservierung gehalten wird und mit welcher Ablehnungsquote zu rechnen ist.
resourceIdist Ihre eigene Kennung und muss stabil sein. Petla ordnet sie bei der Einrichtung einem Petla-Kalender zu — und legt diese Zuordnung niemals selbst an, auch dann nicht, wenn die Praxis nur einen Kalender hat. Eine unbekannteresourceIdist dauerhaft404 resource_not_mapped, bis ein Mensch sie zuordnet.
Zeiten: lokale Uhrzeit plus Zeitzone
Immer lokale Wanduhrzeit plus IANA-Zeitzone. Nie ein blanker Zeitpunkt, nie ein fester Offset.
Ein Termin ist etwas, das ein Mensch plant, und er übersteht die Zeitumstellung nur als lokale Zeit in einer benannten Zone. Europe/Berlin ist nicht +02:00 — es ist +02:00 im August und +01:00 im Januar. Ein im September gebuchter Dezember-Termin darf sich nicht verschieben.
Jede Nutzlast, die eine Zeit trägt, trägt deshalb auch timeZone — und zwar die Zone der Praxis. Eine Veröffentlichung mit einer anderen Zone ist ein 400: Da gibt es nichts zusammenzuführen, denn dann ist jedes Intervall darin still verschoben, und die Verschiebung ändert sich zweimal im Jahr.
Veralten und Schweigen
Petla verfolgt das Alter der letzten Veröffentlichung je Ressource. Ab einer pro Partner vereinbarten Schwelle hört Petla auf, Zeiten dieser Ressource anzubieten, und teilt der Praxis den Grund mit.
Eine leere Veröffentlichung und eine ausgebliebene Veröffentlichung sind verschiedene Zustände und dürfen nie zusammengeworfen werden. „Heute wurde nichts veröffentlicht“ ist eine Störung. „Heute ist nichts frei“ ist eine Tatsache. Wenn die Praxis heute geschlossen hat, senden Sie ein leeres Array — senden Sie nicht einfach nichts.
Das ist dieselbe Regel, keine zusätzliche: Petla kann dort nicht sehen, was Ihr System bereits belegt hat, und verkauft es deshalb nicht. Eine Ressource, die acht Wochen veröffentlicht, macht Woche neun auf diesem Kalender unbuchbar, bis die nächste Veröffentlichung sie erreicht. Darum ist der Horizont oben eine Untergrenze — und darum sieht die Praxis, wie weit ihre eigene Abdeckung reicht.
Ein Praxisrechner ist nachts und am Wochenende aus. Vierzehn Stunden Stille an einem Freitagabend sind deshalb der gesunde Zustand einer funktionierenden Anbindung und keine Störung — Petla beantwortet die Frage anhand der Öffnungszeiten dieser Praxis, nicht anhand einer Uhr. Bewusst kein Totmannschalter: Ein Alarm, der jedes Wochenende losgeht, wird abgeschaltet, und ein abgeschalteter Alarm ist schlimmer als gar keiner.
Vier Zustände, weil die Praxis für jeden einen anderen Satz verdient: nie veröffentlicht (eingerichtet, hat nie etwas gesendet — jemand muss sich den Praxisrechner ansehen), aktuell, veraltet (es lief und hat während der Öffnungszeit aufgehört) und ruhend (still, und die Praxis ist zu).
Modalität
Petla unterscheidet PRAXIS, HOME_VISIT und VIDEO.
Die meisten Praxissysteme haben dafür kein Feld. Wenn Ihres die Modalität nicht abbilden kann, bilden Sie sie auf das ab, was Sie haben — eine Terminart, eine Farbe, eine Notiz — aber lassen Sie sie nicht fallen. Ein Hausbesuch, der als gewöhnliche Sprechstunde im Kalender steht, schickt eine Tierärztin an die falsche Adresse.