Für Entwickler

Die offene CVP-API

CVP ist der offene API-Vertrag des coderis-Vermittlers – eine gemeinsame Sprache für Besteller und Betreiber: Bestellungen anlegen und verfolgen, Angebote empfangen und entscheiden, Statusereignisse melden. Ein Vertrag für alle drei Fahrtfamilien: Krankenfahrt, qualifizierter Krankentransport und allgemeiner Personentransport.

Erste Schritte: Anbindung starten Referenz öffnen Die Vermittlung verstehen – ohne Fachjargon

Reifegrad

Developer Preview

Der Vertrag ist öffentlich einsehbar und bis zur ersten Produktivregion mit der Versionskennung 0.5.0-draft.3 geführt – dieselbe, die auch in der Referenz steht. 23 der 41 veröffentlichten Operationen sind implementiert, getestet und auch formal abgenommen – darunter die vollständige Krankenfahrt- und KTW-Strecke. Den Stand der übrigen Operationen nennen wir einzeln, statt ihn hinter einer Sammelzahl zu verstecken.

13 weitere Operationen sind ebenfalls implementiert und getestet, stehen aber noch unter einem Freigabevorbehalt und gelten deshalb formal noch nicht als abgenommen: der Infektionsstammdaten-Katalog sowie der Kern des Personentransports – Anlegen, Verfolgen, Stornieren, Verfügbarkeitsprüfung, Angebots-Entscheidung und Statusereignisse.

GET /v1/master-data/infections
POST /v1/person-transports
GET /v1/person-transports
GET /v1/person-transports/{id}
POST /v1/person-transports/{id}:cancel
POST /v1/person-transport-availability-checks
GET /v1/dispatch/person-transport-proposals
GET /v1/dispatch/person-transport-proposals/{id}
POST /v1/dispatch/person-transport-proposals/{id}:accept
POST /v1/dispatch/person-transport-proposals/{id}:reject
GET /v1/dispatch/person-transports/{id}
POST /v1/dispatch/person-transports/{id}:cancel
POST /v1/person-transport-events

Die übrigen 5 Operationen sind vertraglich verbindlich definiert; ihr belegter Laufzeitnachweis steht noch aus. Das betrifft die eigene Webhook-Familie des Personentransports und den Einzelabruf der Verfügbarkeitsprüfung – wer heute anbindet, plant sie als vertraglich zugesagten, aber noch nicht nachgewiesenen Teil ein.

GET /v1/person-transport-availability-checks/{id}
POST /v1/person-transport-webhooks
GET /v1/person-transport-webhooks
DELETE /v1/person-transport-webhooks/{id}
POST webhook:personTransportEvent

Was das für eine Anbindung bedeutet: Commands sind strikt und lehnen unbekannte Felder ab. Ressourcen- und Ereignisantworten dürfen additiv um Felder erweitert werden – binden Sie deshalb als tolerant reader an und ignorieren Sie unbekannte Antwortfelder. Ausgenommen sind die datensparsamen Proposal-Whitelists: sie bleiben bewusst geschlossen, und Änderungen an ihnen gelten ausdrücklich als breaking.

Vorproduktiv behalten wir uns ausdrücklich angeordnete, dokumentierte Anpassungen am Vertrag vor; jede davon wird gegen eine veröffentlichte Baseline geführt. Wer jetzt anbindet, baut gegen dieselbe normative Quelle, aus der auch die produktive Fassung hervorgeht.

Überblick

Vier API-Flächen, ein Vertrag

Alle öffentlichen Operationen liegen unter /v1 und sind in der Referenz vollständig dokumentiert – mit Beispielen, Feldbeschreibungen und Fehlerkatalog.

Besteller: Bookings

Bestellungen anlegen, verfolgen, ändern und stornieren; Verfügbarkeit unverbindlich vorab prüfen.

POST /v1/bookings
GET /v1/bookings/{id}
POST /v1/availability-checks

Betreiber: Dispatch + Events

Angebote (Proposals) empfangen, annehmen oder mit Terminalternativen ablehnen; Statusereignisse idempotent melden.

GET /v1/dispatch/proposals
POST /v1/dispatch/proposals/{id}:accept
POST /v1/events

Zustellung: Webhooks

HMAC-signierte Ereignisse (X-CVP-Signature) über Zuschläge, Statuswechsel und Terminalternativen.

POST /v1/webhooks
proposal.offered
booking.confirmed

Personentransport: eigene Familie

Die dritte Fahrtfamilie als additiv eingeführte Ressourcenfamilie mit eigener Besteller-, Dispatch- und Webhook-Strecke – bestehende Booking-Anbindungen bleiben unberührt.

POST /v1/person-transports
GET /v1/dispatch/person-transport-proposals
POST /v1/person-transport-events

Vertragsprinzipien

Gebaut für den Betrieb, nicht für die Demo

Sicherheit

OAuth2 Client Credentials für alle Operationen; Betreiber-Operationen zusätzlich mit mTLS.
Datenschutzminimierte Proposals: Personendaten erst nach dem Zuschlag sichtbar.
Signierte Webhooks mit Schlüsselkennung und Zeitstempel gegen Replay.

Robustheit

Idempotency-Key auf allen Commands – Schutz vor Doppelbestellungen und Doppeltransporten.
ETag / If-Match auf Änderungen, X-Correlation-Id durchgängig.
Strukturierte Terminalternativen: Ablehnungen können 1–3 spätere Zeitfenster vorschlagen.

Evolution

Tolerant-Reader-Policy: Requests strikt, Responses additiv erweiterbar.
Versionierung über den Pfad (/v1), maschinell geprüfte Breaking-Change-Baselines.
Jedes Feld klassifiziert: Datenschutzklasse und Sichtbarkeit sind Teil des Vertrags.

Vollständige Referenz öffnen Anbindung besprechen

OpenAPI 3.1 · 39 Operationen + 2 Webhook-Ereignisfamilien · generiert aus dem normativen Vertrag