Für Entwickler · Release 1.0

Die offene CVP-API

CVP ist der offene API-Vertrag des coderis-Vermittlers – eine gemeinsame Sprache für Besteller und Fahrdienste: 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

Stabilität & Versionierung

Produktiver Release 1.5.0

Die CVP-API ist als Release 1.5.0 veröffentlicht – dieselbe Versionskennung, die in der Referenz steht. Alle 40 HTTP-Operationen und beide Webhook-Ereignisfamilien sind implementiert, getestet und abgenommen: Krankenfahrt, qualifizierter Krankentransport, allgemeiner Personentransport und der Infektionsstammdaten-Katalog.

Was Sie sich darauf verlassen können

Semantic Versioning innerhalb /v1: Es erscheinen nur additive, abwärtskompatible Änderungen.
Inkompatible Änderungen gibt es ausschließlich unter einem neuen API-Major; die Übergangsfrist vereinbaren wir mit den angebundenen Organisationen.
Maschinell geprüft: Jede Vertragsänderung läuft gegen eine veröffentlichte Baseline, Breaking Changes schlagen im Build fehl.

Wie Sie anbinden

Tolerant Reader: Requests sind strikt und lehnen unbekannte Felder ab; Antworten dürfen additiv um Felder wachsen – unbekannte Felder ignorieren Sie.
Proposal-Whitelists sind bewusst geschlossen; Änderungen daran gelten ausdrücklich als breaking.
Eine additive Erweiterung erzwingt weder Neuanbindung noch neue Zugangsdaten.

Umgebungen

Entwicklung und Test: Diese Dokumentation beschreibt die Entwicklungsumgebung cvp-dev mit synthetischen Daten – ohne echte Fahrten und ohne Personendaten.
Produktive Zugänge und -endpunkte erhalten Sie auf Anfrage, nach gemeinsamem Integrationstest.

Erste Schritte Testzugang anfordern

Ü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

Fahrdienst: 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
POST /v1/person-transport-webhooks

Anbindungswege

Eine API – drei Wege hinein

Aufträge werden digital übernommen, ohne manuelles Abtippen. Ob Ihr System direkt spricht, über einen Adapter andockt oder aus einer Leitstelle kommt: Am Ende steht dieselbe, versionierte und vollständig dokumentierte Schnittstelle.

Direkt per REST

Besteller- und Fahrdienstsysteme sprechen die CVP-API unmittelbar: OpenAPI 3.1, OAuth2 mit mandantengebundenen Token, idempotente Auftragsübernahme, unverbindliche Verfügbarkeitsprüfung und signierte Webhooks.

Zu den ersten Schritten

Über den Auftragsadapter

Bestehende Buchungs- und Dispositionsplattformen docken über den generischen Auftragsadapter an. Er übersetzt deren Aufträge auf dieselben Operationen; das Mapping stimmen wir gemeinsam mit dem jeweiligen Hersteller ab.

Anbindung besprechen

Leitstellen und Bereitschaftsdienste

Die Kopplung von Leitstellen und Bereitschaftsdiensten (z. B. Kassenärztliche Vereinigung und Ärztlicher Bereitschaftsdienst) erfolgt über den herstellerneutralen Standard UCRI 2.0. Die Abbildung auf die CVP-Operationen stimmen wir je Gegenstelle ab.

Auf Anfrage

Vertragsprinzipien

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

Sicherheit

OAuth2 Client Credentials für alle Operationen; Fahrdienst-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 · Release 1.5.0 · 40 HTTP-Operationen + 2 Webhook-Ereignisfamilien · generiert aus dem normativen Vertrag