coderis-Vermittler
Anbindung besprechen Besteller-Portal

Für Entwickler

Erste Schritte

Von null zur ersten Testbuchung: So binden Sie Ihr System an den coderis-Vermittler an – als Besteller-System, das Fahrten anlegt, oder als Betreiber-System, das Angebote empfängt und entscheidet. Für den Anfang genügt ein Testzugang: synthetische Daten, keine echten Fahrten, keine Personendaten.

Testzugang anfordern Referenz öffnen Felder & Kataloge

Bevor Sie starten

Welche Rolle übernimmt Ihr System?

Die CVP-API hat zwei Seiten desselben Vertrags. Ihr System nutzt in der Regel genau eine davon – danach richten sich Zugangsdaten, Scopes und die ersten Aufrufe.

Besteller-System

Software für Kliniken, Heime, Praxen und andere Organisationen: legt Krankenfahrten, Krankentransporte und Personentransporte an, prüft Verfügbarkeit vorab und verfolgt den Status. Scopes: booking:read, booking:write, booking:cancel – als festes Berechtigungsprofil, das Ihre Organisation selbst wählt; sie gelten für Bookings und Personentransporte gleichermaßen.

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

Betreiber-System

Dispositionssoftware von Taxi- und Mietwagenbetreibern, Fahrdiensten und KTW-Unternehmen: empfängt Angebote, nimmt an oder lehnt ab und meldet Statusereignisse – für Krankenbeförderung und Personentransport. Scopes: dispatch:read, dispatch:write, event:write. Produktiv zusätzlich mit mTLS.

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

Der Weg zur Anbindung

In fünf Schritten zur ersten Testbuchung

  1. Testzugang anfordern

    Eine kurze Nachricht genügt: wer Sie sind, welche Rolle Ihr System übernimmt (Besteller oder Betreiber) und welches System Sie anbinden. Wir schalten Ihre Organisation für die Testumgebung frei und nennen Ihnen die dort gültigen Endpunkte. Besteller-Organisationen erzeugen ihre OAuth2-Zugangsdaten danach selbst im Bestellerportal – siehe Zugangsdaten selbst verwalten.

    Testzugang anfordern

  2. Access Token holen

    Die API nutzt OAuth 2.0 Client Credentials: Ihr System tauscht Client-ID und Secret gegen ein kurzlebiges Access Token (maximal zehn Minuten, kein Refresh Token) mit den Scopes Ihrer Rolle. 

    curl -X POST https://login.cvp-dev.coderis.de/realms/cvp-api/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id="IHRE_CLIENT_ID" \
  -d client_secret="IHR_SECRET"

    access_token · gültig ≤ 10 Minuten

  3. Der erste Aufruf: Verfügbarkeit prüfen

    Der ideale Einstieg für Besteller-Systeme ist die unverbindliche Verfügbarkeitsprüfung – sie braucht keine Personendaten und legt noch nichts an. Betreiber-Systeme starten stattdessen mit dem Abruf der offenen Angebote über GET /v1/dispatch/proposals. 

    curl -X POST https://api.cvp-dev.coderis.de/v1/availability-checks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @availability-check.json

    Der Idempotency-Key gehört auf jeden schreibenden Aufruf: Wiederholt Ihr System einen Request nach einem Timeout, entsteht garantiert keine zweite Buchung.

  4. Die erste Testbuchung

    Mit POST /v1/bookings legen Sie die erste Fahrt in der Testumgebung an. Den weiteren Verlauf verfolgen Sie per GET /v1/bookings/{id}. Wenn Sie statt Abfragen signierte Ereignisse in Echtzeit erhalten möchten, richten wir Webhooks auf Anfrage für Sie ein. Betreiber-Systeme nehmen ihr erstes Angebot an und melden über POST /v1/events die Statuskette bis „Fahrt abgeschlossen“.

    booking.requested → booking.confirmed

  5. Gemeinsam live gehen

    Läuft Ihr Ablauf in der Testumgebung rund, stimmen wir einen gemeinsamen Integrationstest ab und stellen produktive Zugangsdaten aus – Betreiber-Operationen zusätzlich mit mTLS abgesichert. Additive Erweiterungen des Vertrags brechen Ihre Anbindung nicht: Unbekannte Antwortfelder dürfen Sie ignorieren.

Beispiele zum Nachschlagen

Vollständige Request- und Response-Beispiele – vom Anlegen einer Buchung über das Annehmen eines Angebots bis zum Statusereignis – stehen in der technischen Referenz an jeder Operation, inklusive Fehlerkatalog und Datenschutzklasse je Feld.

Für Besteller-Organisationen

Zugangsdaten selbst verwalten

Sobald Ihre Organisation freigeschaltet ist, erzeugen und verwalten Ihre Administratorinnen und Administratoren die Zugangsdaten selbst – im Bestellerportal unter Administration → API-Zugang. Kein Ticket, kein Warten: anlegen, rotieren oder widerrufen wirkt sofort.

Bereich API-Zugang im Bestellerportal mit Client-ID, Token-URL, gewähltem Berechtigungsprofil und den Schaltflächen zum Rotieren und Widerrufen.
Der Bereich zeigt Client-ID, Token-URL und das aktive Berechtigungsprofil. Client-ID und Token-URL lassen sich direkt in die Konfiguration Ihres Systems kopieren.
Dialog zur Auswahl des Berechtigungsprofils mit den Optionen Lesen, Bestellen sowie Bestellen und Stornieren.
Berechtigungsprofil wählen. Drei feste Profile statt frei kombinierbarer Rechte: Lesen, Bestellen oder Bestellen + Stornieren.
Dialog mit den Zugangsdaten: Client-ID, einmalig angezeigtes Client-Secret und Token-URL, jeweils mit Kopier-Schaltfläche.
Secret einmalig sichern. Das Client-Secret wird genau einmal angezeigt – danach ist es nicht mehr abrufbar, sondern nur noch rotierbar.

Was das für Ihre Anbindung bedeutet

Eine Rotation macht das bisherige Secret sofort ungültig – hinterlegen Sie es in Ihrem System deshalb als Konfigurationswert, den Sie ohne Deployment wechseln können. Ein Widerruf sperrt den Zugang unmittelbar; ein späteres Neuanlegen erzeugt zwingend ein neues Secret. Betreiber-Systeme und Webhook-Verwaltung laufen weiterhin über uns – melden Sie sich einfach.

Nächster Schritt

Testzugang einrichten

Schreiben Sie uns kurz, welche Rolle Ihr System übernimmt – Sie erhalten die Zugangsdaten für die Testumgebung und einen direkten Draht ins Entwicklungsteam für Rückfragen während der Anbindung.

Testzugang anfordern Zur technischen Referenz