Erste Schritte

Von null auf einen ersten erfolgreichen Aufruf: zwei Zugangsdaten, eine Fähigkeiten-Erklärung, ein Testsystem.

Die zwei Zugangsdaten

Sie halten zwei verschiedene Dinge, mit zwei verschiedenen Lebensdauern.

Was	Gilt für	Lebensdauer
Partner-Zugangsdaten	Sie als Hersteller — einmalig, für alle Praxen	langlebig, rotierbar
Verbindungs-Token	Genau eine Praxis ↔ genau ein Mandant in Ihrem System	bis eine der beiden Seiten sie beendet

Nicht tun

Eine Verbindung gehört der PRAXIS, nie einer einzelnen Tierärztin. Kalender und Kundendaten gehören der Praxis; wer sie verlässt, darf die Verbindung nicht mitnehmen.

Eine Praxis verbinden

Die Praxis wählt in Ihrer Software „Mit Petla verbinden“.
Ihr System holt mit den Partner-Zugangsdaten einen kurzlebigen Kopplungscode über POST /connections/pairing-codes und zeigt ihn der Praxis an.
Die Praxis gibt diesen Code bei Petla ein. Hat sie noch kein Petla-Konto, führt derselbe Ablauf sie durch Eintrag übernehmen und verbinden (siehe unten).
Petla gibt Ihnen ein Verbindungs-Token zurück, das für genau diese eine Praxis gilt.

Achtung

Das Token wird genau einmal angezeigt. Petla speichert nur dessen Hash. Wird es neu erzeugt, verliert das vorherige sofort seine Gültigkeit.

Jeder weitere Aufruf

Authorization: Bearer <Verbindungs-Token>
Petla-Clinic-Id: <clinicId>

Ein Verbindungs-Token gilt für genau eine clinicId. Passen die beiden nicht zusammen, antwortet Petla mit CONNECTION_CLINIC_MISMATCH (403) — nie mit einer stillschweigend erweiterten Berechtigung.

Eintrag übernehmen und verbinden

Rund 12.000 deutsche Praxen existieren bei Petla bereits als nicht beanspruchter Tierarztfinder-Eintrag. Kommt eine Praxis über Ihre Software, gleicht Petla sie gegen dieses Verzeichnis ab und bietet Übernahme und Verbindung als einen Vorgang an — die Praxis verlässt ihn mit übernommenem Eintrag und aktiver Buchung.

Kennen Sie die canonicalId der Praxis im Petla-Verzeichnis, können Sie sie beim Kopplungscode mitgeben und der Suchschritt entfällt.

Ihre Fähigkeiten erklären

Sie erklären Petla, was Sie können — Petla fragt Sie nicht ab. Das ist Absicht: ein System, das nur Polling beherrscht, könnte eine Abfrage gar nicht beantworten.

PUT /capabilities

{
  "specVersion": "1.0",
  "capabilities": [
    "availability.publish",
    "appointments.receive",
    "appointments.acknowledge",
    "clients.match"
  ],
  "transport": "poll",
  "resources": { "selectable": true },
  "appointmentTypes": { "mapped": true }
}

Achtung

capabilities ist eine offene Liste. Ihr System muss Werte ignorieren, die es nicht kennt, und Petla tut dasselbe. Eine neue Fähigkeit ist deshalb keine brechende Änderung — kompilieren Sie diese Liste nicht in ein switch, das bei Unbekanntem eine Ausnahme wirft.

Die Reihenfolge, in der Sie bauen sollten

Verbindung herstellen und GET /capabilities zurücklesen. Damit steht die Authentifizierung.
Verfügbarkeit veröffentlichen, und zwar im Format busy. Es trägt keinerlei Patientendaten und ist das Leichteste, was Doppelbuchungen verhindert.
Ereignisse abrufen und einen Termin schreiben.
Bestätigen — POST /appointments/{id}/ack. Erst damit ist der Kreis geschlossen; ohne Bestätigung wartet der Tierhalter.
Danach alles Weitere: Zuordnung von Kunden, Verschiebungen, Reservierungen.

Hinweis

Sie bekommen für die gesamte Entwicklung eine eigene Testpraxis auf der Petla-Staging-Umgebung — mit echten Kunden, Tieren und Terminen, jederzeit zurücksetzbar. Kein Mock: Sie bekommen echte Konflikte und echte Fehler.