Testsystem & Go-live

Sie entwickeln gegen eine eigene Testpraxis auf der Petla-Staging-Umgebung, und Sie gehen gegen eine Checkliste live.

Ihre eigene Testpraxis

Jeder Partner bekommt eine eigene Testpraxis mit angelegten Kunden, Tieren und Terminen — partner-sandbox-<ihr-vendor-key>, aufgelöst aus Ihrem Zugangsschlüssel. Sie steuern sie selbst; wir müssen dafür nichts tun.

Hinweis

Es ist ein echtes System, kein Mock. Es schreibt echte Datensätze, liefert echte Konflikte und echte Fehler. Ein Mock würde genau die Fälle nicht zeigen, die Sie testen müssen — den vergebenen Slot, die uneindeutige Kundenzuordnung, den abgelaufenen Cursor.

Die Steuerungsendpunkte

Alle fünf laufen unter Ihrem Partner-Zugangsschlüssel, nicht unter einem Verbindungs-Token, und alle fünf arbeiten ausschließlich auf Ihrer eigenen Sandbox-Praxis: die Praxis wird aus dem Vendor-Key abgeleitet und niemals aus der Anfrage gelesen.

Aufruf	Wofür
`POST /sandbox/reset`	Setzt Kunden, Tiere, Termine, Zuordnungen und den Ereignisstrom zurück und legt die Ausgangsdaten neu an. Alle bestehenden Cursor werden ungültig — genau wie nach einer Neukopplung. ⚠️ Zwei Dinge überleben ihn: ein von Ihnen freigegebenes Dokument und ein Tier, für das Sie eine Impfung gemeldet haben. Eine Impfung ist ein klinischer Eintrag und in der Datenbank nur anfügbar, also bleibt auch das Tier bestehen — es wird beim Neuanlegen wiederverwendet, nicht verdoppelt.
`POST /sandbox/redeem`	Löst einen Kopplungscode ein, so wie es sonst eine Praxis im Petla-Konto tut. Damit können Sie die Kopplung allein durchspielen.
`POST /sandbox/bookings`	Schreibt einen echten Termin und öffnet ein echtes 60-Sekunden-Fenster.`persona` ist `known`, `new` oder `ambiguous`.
`GET /sandbox/stale-cursor`	Liefert einen Cursor, den der echte Ereignisstrom mit `410` zurückweist. Sonst müssten Sie 30 Tage warten.
`DELETE /sandbox/connection`	Trennt die Verbindung so, wie die Praxis es täte — die Richtung, die Sie von sich aus nicht auslösen können.

Achtung

/sandbox/redeem ist eine Probe, kein Beweis. Es durchläuft dieselbe Einlöse-Logik wie das Praxis-Konto, aber nicht die Anmeldung der Praxis, nicht die Berechtigung clinic:manage und nicht den Menschen, der einen Code von einem Bildschirm abliest und in einen anderen tippt. Wenn Sie damit durch sind, haben Sie die Kopplung gegen die Sandbox geprobt — nicht mit einer Praxis durchlaufen.

Checkliste vor dem Go-live

GET /capabilities liefert genau die vorgesehenen Fähigkeiten.
Verfügbarkeit wird im vereinbarten Intervall veröffentlicht — einschließlich eines geschlossenen Tages.
Der geschlossene Tag ist der Test, den fast alle auslassen: Er unterscheidet ein leeres Array von einer ausgebliebenen Veröffentlichung.
Ein Termin wird empfangen, geschrieben und bestätigt — binnen 60 Sekunden, wenn Sie einen Webhook betreiben oder deutlich häufiger abrufen als das Mindestintervall; sonst schlicht bestätigt, und Petla hat dem Tierhalter vorher zugesagt.
Ein reines Polling-System kann die 60 Sekunden auf dem Mindestintervall nicht einhalten — das ist der Normalfall, kein Fehler.
Eine wiederholte Bestätigung wird durchgespielt: identisch → 200, widersprechend → 409.
Der Wiederholungsversuch nach einem Timeout ist genau der Fall, den jeder HTTP-Client von selbst schickt.
Eine Ablehnung wird durchgespielt, mit Grund.
Ein Cursor wird nach einem absichtlichen Ausfall fortgesetzt.
Ein abgelaufener Cursor wird behandelt: 410 führt zur vollständigen Neusynchronisierung.
Ein doppelt zugestelltes Ereignis wird ignoriert.
Petla → Ihr System: Eine in Petla verschobene oder abgesagte Buchung erreicht Sie als appointment.rescheduled beziehungsweise appointment.cancelled über GET /events. Nicht appointment.updated — dieser Typ meldet eine sichtbare Änderung, die weder Verschiebung noch Absage ist.
Ihr System → Petla: Änderungen am Tresen werden gemeldet — nur wenn Sie appointments.rescheduleInbound / appointments.cancelInbound deklariert haben. Beides ist auf dem Testsystem und auf der Produktion live.
Diese Richtung ist Extended: eine reine Core-Integration ist auch ohne sie konform. Der Schutz ist die Fähigkeit, nicht die Auslieferung — ohne Deklaration antworten beide Endpunkte mit 400 capability_not_declared.
Ein Dokument wird freigegeben und widerrufen — nur wenn Sie documents.push deklariert haben. Den Widerruf zweimal ausführen, und einmal für eine documentId, die Sie nie gesendet haben.
§12.1 ist Extended: eine reine Core-Integration ist auch ohne konform, und der Schutz ist die Fähigkeit — ohne Deklaration antworten beide Endpunkte mit 400 capability_not_declared. Die zwei Wiederholungen sind die Eigenschaften, auf die man nicht zufällig stößt und die eine echte Störung erzeugt: ein zweiter Widerruf muss 200 mit dem ERSTEN Zeitstempel liefern, und ein Widerruf für ein nie empfangenes Dokument 200 mit status not_held statt 404. Wer eines von beidem als Fehlschlag liest, wiederholt eine Anweisung, die längst ausgeführt ist.
Ein bestätigter Anamnesebogen wird gelesen und sein PDF geladen — nur wenn Sie forms.receive deklariert haben. Lesen Sie einen Termin vor der Deklaration (kein forms-Schlüssel) und einen danach auf einer Buchung ohne Bogen ("forms": []).
§7.1b ist Extended: eine reine Core-Integration ist auch ohne konform, und der Schutz ist die Fähigkeit — ohne Deklaration antwortet GET /forms/{submissionId}/pdf mit 400 capability_not_declared, und das Feld fehlt auf jedem Termin. Die zwei Lesevorgänge sind der Punkt: ein fehlender Schlüssel und ein leeres Array bedeuten das Gegenteil voneinander — „wir senden Ihnen keine Bögen“ gegen „der Halter hat nichts ausgefüllt“. Wer beides zusammenwirft, meldet das erste als das zweite, und zwar bei jedem Termin. Laden Sie pdfUrl außerdem mit Ihrem gewöhnlichen Verbindungs-Token: Die URL ist nicht signiert, und wer sie für vorab authentifiziert hält, bekommt einen 401 und liest ihn als kaputten Link.
Eine Kundenzuordnung liefert mindestens je einmal matched, created und ambiguous — POST /sandbox/bookings mit der passenden persona.
Die Sandbox führt dafür zwei Kundinnen mit gleichem Namen und gleichen letzten neun Telefonziffern, ohne jedes Unterscheidungsmerkmal. Ohne ein solches Paar kann Ihr Abgleich nie mehr als einen Treffer haben, und der Zweig bleibt ungetestet.
Die Praxis kann trennen, und Aufrufe danach scheitern sauber — DELETE /sandbox/connection.
Der 401 connection_revoked IST die Zustellung von connection.revoked auf dem Poll-Transport. Wer ihn als vorübergehenden Anmeldefehler behandelt, wiederholt endlos.
Der Auftragsverarbeitungsvertrag ist unterzeichnet — SPEC §16 nennt, was er abdecken muss.
In der Sandbox lagen zu keinem Zeitpunkt echte Patientendaten. Sie ist eine Testumgebung mit erfundenen Tierhaltern und erfundenen Terminen — und Sie selbst können sie jederzeit leeren und neu befüllen.

Versionierung und was wir zusichern

Die Hauptversion steht im Pfad: /partner/v1/….

Ohne neue Version darf Petla

einen Endpunkt ergänzen,
ein optionales Feld in einer Anfrage ergänzen,
ein Feld in einer Antwort ergänzen,
einen Wert zu einer offenen Aufzählung hinzufügen,
einen Ereignistyp ergänzen,
eine Prüfregel lockern.

Ohne neue Version darf Petla nicht

irgendetwas entfernen oder umbenennen,
den Typ eines Feldes ändern,
ein optionales Feld verpflichtend machen,
einen Wert zu einer eingefrorenen Aufzählung hinzufügen,
einen Standardwert ändern,
aufhören, ein Feld zu befüllen.

Achtung

Eine abgekündigte Version wird ab der Ankündigung noch 12 Monate unterstützt, signalisiert über die Kopfzeilen Deprecation und Sunset. Keine Version wird abgeschaltet ohne schriftliches Einverständnis jedes Partners, der sie noch aufruft.

Rechtlicher Rahmen

Grundlage der Zusammenarbeit ist eine Schnittstellenvereinbarung zwischen Ihnen und Petla, begleitet von einem Auftragsverarbeitungsvertrag nach Art. 28 DSGVO.

Weil in der Tiermedizin § 203 StGB berührt sein kann, stellt Petla auf Anfrage ein vollständiges Unterlagenpaket bereit: AVV, Verpflichtungserklärung auf das Datengeheimnis, technische und organisatorische Maßnahmen, Liste der Unterauftragsverarbeiter und eine verständliche Beschreibung, welche Daten der Konnektor überhaupt bewegt.

Hinweis

Diese Unterlagen richten sich auch an Ihre Kunden: Die Praxis wählt den Auftragsverarbeiter aus und trägt dafür Verantwortung. Das Paket ist so gebaut, dass Sie es weiterreichen können.

Support

Je eine benannte Ansprechperson auf beiden Seiten, bei Vertragsschluss vereinbart. Nennen Sie die requestId in jeder Meldung — damit finden wir den Aufruf in unseren Protokollen.

Petla veröffentlicht ein Änderungsprotokoll zu dieser Spezifikation. Brechende Änderungen werden dort zuerst angekündigt und treten nie in kürzerer Frist in Kraft als oben zugesichert. Bisher war keine Änderung brechend.