API docs by Redocly

coderis Vermittlungsprofil (CVP) Krankenbefoerderung API (0.5.0-draft.1)

Download OpenAPI specification:

License: Proprietary

Normativer Besteller-/Betreibervertrag fuer unqualifizierte Krankenfahrten und qualifizierte KTW-Transporte

Diese Datei ist die normative Vertragsquelle fuer CVP 0.5. Der Draft 0.5.0-draft.1 erweitert 0.4.0-draft.3 additiv um den Infektionsstammdaten-Katalog und verschaerft vorproduktiv die Booking-Validierung auf aktive Katalogcodes. Der zugrunde liegende Clean Cut erfolgt unter /v1 ohne Kompatibilitaetsschicht. Organisation und Mandant werden ausschliesslich aus der verifizierten Systemidentitaet bestimmt; gleichnamige Body-, Query- oder Headerwerte sind unzulaessig.

Der Vertrag verwendet OAuth 2.0 Client Credentials nach RFC 6749, gehaertet nach RFC 9700. Er behauptet keine normative OAuth-2.1-Verfuegbarkeit.

Buchungen bestehen aus einem gemeinsamen journeyRef und mindestens einem unabhaengig disponierbaren Leg mit stabilem legRef. Verordnung, Genehmigung und Eligibility referenzieren ihren Umfang explizit ueber legRefs; Outbound-Evidenz gilt nie automatisch fuer Return. Proposal- Schemas sind datensparsame Whitelists, waehrend die Detailansicht erst dem Gewinner zusteht. Das unveraenderlich referenzierte Regelprofil ist DE-GKV-KT-RL-2025-08-06 in Version 2026-07-24.

Kompatibilitaetspolicy: Commands (Request-Bodies) sind strikt und lehnen unbekannte Felder ab. Ressourcen- und Ereignisantworten der Plattform duerfen additiv um Felder erweitert werden; Clients muessen unbekannte Antwortfelder ignorieren (tolerant reader). Ausgenommen sind die datensparsamen Proposal-Whitelists, die absichtlich geschlossen bleiben.

Server-Defaults: Fehlt ruleProfile im Create-Command, pinnt die Plattform bei Admission das einzige veroeffentlichte Regelprofil unveraenderlich in das Booking. Fehlt coverage.settlement bei SELF_PAY, gilt PATIENT_UPFRONT_WITHOUT_REIMBURSEMENT mit acceptanceStatus NOT_APPLICABLE. Antworten enthalten die materialisierten Werte immer explizit.

Strukturierte Pickup-Zeitfenster-Gegenvorschlaege sind ausschliesslich innerhalb des vorhandenen Proposal-Rejects zulaessig. Sie reservieren weder Fahrzeug noch Kapazitaet. Nach Auswahl einer aktiven Alternative disponiert die Plattform das Leg genau einmal erneut; der Betreiber prueft den Zeitpunkt in dieser Bestaetigungsrunde erneut.

Die Vorabpruefung ueber availability-checks ist eine kurzlebige, unverbindliche und PII-minimierte Momentaufnahme vor createBooking. Sie erzeugt weder Booking, Proposal, Transport noch Capacity-Hold. Alle geeigneten availability-faehigen Betreiber werden unabhaengig von der spaeteren Dispatchstrategie parallel geprueft; die normale Disposition bewertet die Verfuegbarkeit nach der Transportanlage erneut.

Der Infektionsstammdaten-Katalog unter master-data/infections ist die alleinige Quelle fuer oeffentliche MIND-Infektionscodes. Neue Booking- Eingaben duerfen nur aktive Katalogcodes verwenden; der geschuetzte Freitext displayName ist ausschliesslich fuer Code 1998 zulaessig und dort verpflichtend.

master-data

Gemeinsame Stammdaten fuer Besteller und Betreiber

Infektionsstammdaten-Katalog

Liefert den aktiven und historischen Infektionskatalog mit Code, Anzeigename, Aktivstatus und Freitext-Kennzeichen.

Authorizations:
OAuth2ClientCredentials(OAuth2ClientCredentialsMutualTLS)
query Parameters
active
boolean

Nur aktive Eintraege liefern (Default ist alle).

header Parameters
X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Responses

Response samples

Content type
application/json
{
  • "source": "MIND4.0VMBW",
  • "sourceVersion": "1.0",
  • "sourceAsOf": "2023-09-19",
  • "catalogRevision": 1,
  • "entries": [
    ]
}

Bookings

Organisationsbegrenzte Bestelleroperationen

Unqualifizierte Krankenfahrt mit einem oder mehreren Legs anlegen

Legt ein Booking idempotent im Zustand REQUESTED an. Vermittlung und Proposal-Erzeugung erfolgen asynchron. Vor dem 201 muss genau ein freigegebenes Intake-Service-Level bestimmt sein; andernfalls folgt 503 INTAKE_SERVICE_LEVEL_UNAVAILABLE ohne angelegtes Booking. Ist mit den eindeutig gepinnten Published-Inputs und der autoritativen Plattformzeit innerhalb der idempotenten Admission-Transaktion sicher belegt, dass das Policy-Zeitfenster bereits erschoepft ist, und greift kein Published-Short-Notice-Profil, folgt 412 POLICY_WINDOW_EXHAUSTED ohne Booking. Ein identischer Command mit demselben Idempotency-Key replayt diese gespeicherte Antwort ohne erneute Admission-Pruefung. Wird das Fenster erst nach einem erfolgreichen 201 erschoepft, bleibt das Booking angenommen und endet gegebenenfalls als NOT_SERVED mit reason POLICY_WINDOW_EXHAUSTED. Serien und Rueckfahrten werden als separat adressierbare Legs derselben Journey erfasst; Verordnungs- und Genehmigungsevidenz referenziert diese Legs explizit.

Authorizations:
OAuth2ClientCredentials
header Parameters
Idempotency-Key
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4. Der Schluesselraum besteht aus Organisation, Client, Methode, Pfadtemplate und Key. Gleicher effektiver Command liefert die urspruengliche Antwort; abweichender Command liefert 409 CONFLICT_IDEMPOTENCY.

X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Request Body schema: application/json
required
transportClass
required
string (TransportClass)
Enum: "UNQUALIFIED_KRANKENFAHRT" "QUALIFIED_KTW"

Exakte nationale Transportklasse. Klasse und operativer ServiceMode muessen semantisch zusammenpassen; es gibt keinen stillen Fallback.

journeyRef
required
string (ExternalRef) [ 1 .. 50 ] characters ^[A-Za-z0-9:._-]+$
required
object (PatientV3)
required
Array of objects (JourneyLegInput) [ 1 .. 100 ] items unique
required
object (Coverage)

settlement darf im Command nur bei type SELF_PAY entfallen; die Plattform materialisiert dann PATIENT_UPFRONT_WITHOUT_REIMBURSEMENT mit acceptanceStatus NOT_APPLICABLE. Jeder andere Coverage-Typ ohne explizites Settlement ergibt COVERAGE_UNRESOLVED. Antworten enthalten settlement immer.

required
object (OrdererCommand)

organizationRef ist absichtlich nicht schreibbar; die Organisation stammt nur aus dem Token.

object (RuleProfileRef)

Optional; fehlt es, pinnt die Plattform bei Admission das einzige veroeffentlichte Regelprofil unveraenderlich. Wird es gesendet, muss es exakt matchen, sonst UNSUPPORTED_PROFILE.

Array of objects (Extension)

Responses

Request samples

Content type
application/json
{
  • "transportClass": "UNQUALIFIED_KRANKENFAHRT",
  • "journeyRef": "JOURNEY-SELF-001",
  • "patient": {
    },
  • "legs": [
    ],
  • "coverage": {
    },
  • "orderer": {
    }
}

Response samples

Content type
application/json
{
  • "bookingId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "reference": "K-2527",
  • "state": "REQUESTED",
  • "transportClass": "UNQUALIFIED_KRANKENFAHRT",
  • "journeyRef": "JOURNEY-SELF-001",
  • "patient": {
    },
  • "legs": [
    ],
  • "coverage": {
    },
  • "orderer": {
    },
  • "ruleProfile": {
    },
  • "claimReadiness": {
    },
  • "createdAt": "2026-07-12T16:00:00+02:00",
  • "updatedAt": "2026-07-12T16:00:00+02:00"
}

Eigene Bookings cursorbasiert auflisten

Listet ausschliesslich Bookings der Organisation aus dem verifizierten Tokenkontext.

Authorizations:
OAuth2ClientCredentials
query Parameters
cursor
string [ 1 .. 1024 ] characters

Opaker, kurzlebiger Cursor; Clients duerfen Inhalt oder Sortierschluessel nicht interpretieren.

limit
integer [ 1 .. 100 ]
Default: 50

Maximale Elementzahl; Listen ohne wirksames Limit sind unzulaessig.

state
string (BookingState)
Enum: "REQUESTED" "DISPATCHING" "CONFIRMED" "ASSIGNED" "ENROUTE" "ARRIVED" "IN_PROGRESS" "COMPLETED" "CANCELLED" "NOT_SERVED"

Technische Dispatchfehler werden in processing sichtbar und enden vor CONFIRMED fristgerecht fachlich als NOT_SERVED; nach CONFIRMED gilt der Exception-/Cancel-Pfad. Historische Legacy-Rows sind kein Bestandteil dieses oeffentlichen 0.3-Serialisierers.

from
string <date-time> (DateTimeWithOffset) (?:Z|[+-][0-9]{2}:[0-9]{2})$
Examples: from=2026-07-13T07:50:00+02:00

Inklusiver Filter auf den effektiven Zeitanker des fruehesten Legs: pickupWindow.earliest, sonst arrivalBy, sonst treatmentAppointmentAt. Legs ohne jeden Zeitanker werden von from/to nicht ausgeschlossen.

to
string <date-time> (DateTimeWithOffset) (?:Z|[+-][0-9]{2}:[0-9]{2})$
Examples: to=2026-07-13T07:50:00+02:00

Exklusiver Filter auf denselben effektiven Zeitanker wie from.

header Parameters
X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Responses

Response samples

Content type
application/json
{
  • "items": [ ]
}

Eigenes Booking lesen

Liefert ein organisationsbegrenztes Booking einschliesslich Assignment, soweit vorhanden.

Authorizations:
OAuth2ClientCredentials
path Parameters
id
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

Plattformvergebene Booking-ID.

header Parameters
X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Responses

Response samples

Content type
application/json
{
  • "bookingId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "reference": "K-2527",
  • "state": "REQUESTED",
  • "transportClass": "UNQUALIFIED_KRANKENFAHRT",
  • "journeyRef": "JOURNEY-SELF-001",
  • "patient": {
    },
  • "legs": [
    ],
  • "coverage": {
    },
  • "orderer": {
    },
  • "ruleProfile": {
    },
  • "claimReadiness": {
    },
  • "createdAt": "2026-07-12T16:00:00+02:00",
  • "updatedAt": "2026-07-12T16:00:00+02:00"
}

Eigenes Booking idempotent stornieren

Storniert nach der Booking-Zustandsregel. Ab IN_PROGRESS ist ein normales Bestellerstorno unzulaessig. Quelle und Organisation werden aus der verifizierten Identitaet bestimmt und stehen nicht im Command.

Authorizations:
OAuth2ClientCredentials
path Parameters
id
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

Plattformvergebene Booking-ID.

header Parameters
Idempotency-Key
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4. Der Schluesselraum besteht aus Organisation, Client, Methode, Pfadtemplate und Key. Gleicher effektiver Command liefert die urspruengliche Antwort; abweichender Command liefert 409 CONFLICT_IDEMPOTENCY.

X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Request Body schema: application/json
required
reason
required
string
Enum: "ORDERER_REQUEST" "DUPLICATE" "OTHER_CODED"
note
string (Note) [ 1 .. 255 ] characters

Logistik-/Zugangshinweis ohne Diagnose oder medizinischen Freitext; erkannte Gesundheitsdaten ergeben HEALTH_DATA_REJECTED.

Responses

Request samples

Content type
application/json
{
  • "reason": "ORDERER_REQUEST",
  • "note": "Fahrt wird nicht mehr benoetigt."
}

Response samples

Content type
application/json
{
  • "bookingId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "reference": "K-2527",
  • "state": "REQUESTED",
  • "transportClass": "UNQUALIFIED_KRANKENFAHRT",
  • "journeyRef": "JOURNEY-SELF-001",
  • "patient": {
    },
  • "legs": [
    ],
  • "coverage": {
    },
  • "orderer": {
    },
  • "ruleProfile": {
    },
  • "claimReadiness": {
    },
  • "createdAt": "2026-07-12T16:00:00+02:00",
  • "updatedAt": "2026-07-12T16:00:00+02:00"
}

Offenes Timing ergaenzen oder angebotene Zeit-Alternative auswaehlen

Aktualisiert ausschliesslich das adressierte Leg. Entweder wird das vorhandene direkte timing fuer ein noch nicht disponierbares Leg gesetzt oder genau eine aktive selectedTimeAlternativeId ausgewaehlt. Die Auswahl ersetzt nur das Pickup-Fenster, behaelt andere vorhandene Zeitanker bei und startet genau eine erneute Disposition. Eine Alternative ist keine Reservierung oder Zusage; Verfuegbarkeit wird in der neuen Bestaetigungsrunde erneut geprueft. Eine fehlende Return-Zeit wird nie durch einen Ersatzwert ergaenzt.

Authorizations:
OAuth2ClientCredentials
path Parameters
id
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

Plattformvergebene Booking-ID.

legRef
required
string (ExternalRef) [ 1 .. 50 ] characters ^[A-Za-z0-9:._-]+$
Examples: ORG-4711-P-0032

Stabile, innerhalb des Bookings eindeutige Abschnittsreferenz.

header Parameters
Idempotency-Key
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4. Der Schluesselraum besteht aus Organisation, Client, Methode, Pfadtemplate und Key. Gleicher effektiver Command liefert die urspruengliche Antwort; abweichender Command liefert 409 CONFLICT_IDEMPOTENCY.

If-Match
string <= 128 characters ^"[^"]+"$

Optionale Precondition mit dem zuletzt gelesenen starken ETag. Weicht die aktuelle Ressourcenversion ab, folgt 412 PRECONDITION_FAILED ohne Wirkung. Ohne If-Match gilt Last-Write-Wins innerhalb der Idempotenzregeln.

X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Request Body schema: application/json
required
One of
required
object (LegTiming) non-empty

Mindestens ein Zeitanker; Kombinationen muessen plausibel sein.

Responses

Request samples

Content type
application/json
Example
{
  • "timing": {
    }
}

Response samples

Content type
application/json
{
  • "bookingId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "reference": "K-2527",
  • "state": "REQUESTED",
  • "transportClass": "UNQUALIFIED_KRANKENFAHRT",
  • "journeyRef": "JOURNEY-SELF-001",
  • "patient": {
    },
  • "legs": [
    ],
  • "coverage": {
    },
  • "orderer": {
    },
  • "ruleProfile": {
    },
  • "claimReadiness": {
    },
  • "createdAt": "2026-07-12T16:00:00+02:00",
  • "updatedAt": "2026-07-12T16:00:00+02:00"
}

Coverage und Settlement nach expliziter Bestellerentscheidung aktualisieren

Ein REJECTED-Abrechnungsweg wird nie still ersetzt; jede Alternative startet erst nach dieser idempotenten Bestellerentscheidung eine neue Vermittlungsrunde.

Authorizations:
OAuth2ClientCredentials
path Parameters
id
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

Plattformvergebene Booking-ID.

header Parameters
Idempotency-Key
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4. Der Schluesselraum besteht aus Organisation, Client, Methode, Pfadtemplate und Key. Gleicher effektiver Command liefert die urspruengliche Antwort; abweichender Command liefert 409 CONFLICT_IDEMPOTENCY.

If-Match
string <= 128 characters ^"[^"]+"$

Optionale Precondition mit dem zuletzt gelesenen starken ETag. Weicht die aktuelle Ressourcenversion ab, folgt 412 PRECONDITION_FAILED ohne Wirkung. Ohne If-Match gilt Last-Write-Wins innerhalb der Idempotenzregeln.

X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Request Body schema: application/json
required
required
object (Coverage)

settlement darf im Command nur bei type SELF_PAY entfallen; die Plattform materialisiert dann PATIENT_UPFRONT_WITHOUT_REIMBURSEMENT mit acceptanceStatus NOT_APPLICABLE. Jeder andere Coverage-Typ ohne explizites Settlement ergibt COVERAGE_UNRESOLVED. Antworten enthalten settlement immer.

decision
required
string
Enum: "CLARIFY_COVERAGE" "SELECT_SELF_PAY" "SELECT_PATIENT_UPFRONT" "ACKNOWLEDGE_CONDITIONS"
acknowledgedConditionHash
string^[0-9a-f]{64}$

Responses

Request samples

Content type
application/json
{
  • "coverage": {
    },
  • "decision": "CLARIFY_COVERAGE",
  • "acknowledgedConditionHash": "string"
}

Response samples

Content type
application/json
{
  • "bookingId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "reference": "K-2527",
  • "state": "REQUESTED",
  • "transportClass": "UNQUALIFIED_KRANKENFAHRT",
  • "journeyRef": "JOURNEY-SELF-001",
  • "patient": {
    },
  • "legs": [
    ],
  • "coverage": {
    },
  • "orderer": {
    },
  • "ruleProfile": {
    },
  • "claimReadiness": {
    },
  • "createdAt": "2026-07-12T16:00:00+02:00",
  • "updatedAt": "2026-07-12T16:00:00+02:00"
}

Availability

Kurzlebige, owner-isolierte Vorabpruefung ohne Reservierung

Unverbindliche Live-Verfuegbarkeitspruefung starten

Persistiert idempotent eine kurzlebige, PII-minimierte Momentaufnahme und einen haltbaren Pruefauftrag. Vor der 202-Antwort finden keine Betreiberaufrufe statt. Der Check erzeugt weder Booking, Proposal, Transport noch Capacity-Hold und veraendert den spaeteren createBooking- und Dispatchfluss nicht. Ein identischer Command mit demselben Idempotency-Key replayt die urspruengliche PENDING-Ressource mit derselben Check-ID; ein abweichender Command liefert CONFLICT_IDEMPOTENCY.

Authorizations:
OAuth2ClientCredentials
header Parameters
Idempotency-Key
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4. Der Schluesselraum besteht aus Organisation, Client, Methode, Pfadtemplate und Key. Gleicher effektiver Command liefert die urspruengliche Antwort; abweichender Command liefert 409 CONFLICT_IDEMPOTENCY.

X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Request Body schema: application/json
required
required
Array of objects (AvailabilityCheckLegCommand) [ 1 .. 2 ] items unique

Responses

Request samples

Content type
application/json
{
  • "legs": [
    ]
}

Response samples

Content type
application/json
{
  • "availabilityCheckId": "4f5e9a8c-1b2d-4c6f-8a90-123456789abc",
  • "state": "PENDING",
  • "completeness": "PENDING",
  • "legs": [
    ],
  • "createdAt": "2026-07-26T10:00:00+02:00",
  • "softResultAt": "2026-07-26T10:00:08+02:00",
  • "updatedAt": "2026-07-26T10:00:00+02:00",
  • "expiresAt": "2026-07-26T10:01:00+02:00"
}

Eigene Live-Verfuegbarkeitspruefung lesen

Liefert den aktuellen Checkzustand ohne eine neue Pruefung oder andere Seiteneffekte zu starten. Nur dieselbe verifizierte Organisation und derselbe authentifizierte Client wie beim POST duerfen die Ressource lesen. Fremde und nicht vorhandene IDs sind als 404 ununterscheidbar.

Authorizations:
OAuth2ClientCredentials
path Parameters
id
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

Plattformvergebene, opake ID einer kurzlebigen Vorabpruefung.

header Parameters
X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Responses

Response samples

Content type
application/json
Example
{
  • "availabilityCheckId": "4f5e9a8c-1b2d-4c6f-8a90-123456789abc",
  • "state": "COMPLETED",
  • "completeness": "COMPLETE",
  • "legs": [
    ],
  • "createdAt": "2026-07-26T10:00:00+02:00",
  • "softResultAt": "2026-07-26T10:00:08+02:00",
  • "updatedAt": "2026-07-26T10:00:03+02:00",
  • "expiresAt": "2026-07-26T10:01:00+02:00"
}

Dispatch

Organisationsbegrenzte Betreiberoperationen

Eigene Dispatch-Proposals cursorbasiert auflisten

Polling-Fallback fuer dieselben PII-freien Proposal-Objekte wie im Proposal-Webhook.

Authorizations:
(OAuth2ClientCredentialsMutualTLS)
query Parameters
cursor
string [ 1 .. 1024 ] characters

Opaker, kurzlebiger Cursor; Clients duerfen Inhalt oder Sortierschluessel nicht interpretieren.

limit
integer [ 1 .. 100 ]
Default: 50

Maximale Elementzahl; Listen ohne wirksames Limit sind unzulaessig.

state
string (ProposalState)
Enum: "OFFERED" "ACCEPTED" "REJECTED" "COUNTERED" "EXPIRED" "WITHDRAWN"
Example: state=OFFERED

COUNTERED ist terminal und schliesst das urspruengliche Proposal wie ein Reject. Der Vermittler fuehrt die regulaere Suche im urspruenglichen Pickup-Fenster trotzdem vollstaendig fort.

header Parameters
X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Responses

Response samples

Content type
application/json
{
  • "items": [ ]
}

Eigenes Dispatch-Proposal lesen

Liefert ein Proposal ohne Patientenklardaten und ohne Bestellerkontaktdaten.

Authorizations:
(OAuth2ClientCredentialsMutualTLS)
path Parameters
id
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

Plattformvergebene Proposal-ID.

header Parameters
X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Responses

Response samples

Content type
application/json
Example
{
  • "proposalId": "7a99bdf5-77f0-4b57-8906-5f58230bc876",
  • "bookingId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "journeyRef": "JOURNEY-SELF-001",
  • "legRef": "LEG-SINGLE",
  • "state": "OFFERED",
  • "transportClass": "UNQUALIFIED_KRANKENFAHRT",
  • "service": {
    },
  • "pickupRegion": {
    },
  • "dropoffRegion": {
    },
  • "timing": {
    },
  • "coverageMatch": {
    },
  • "estimates": {
    },
  • "sla": {
    },
  • "counterOffersAllowed": true,
  • "correlationId": "ed0dc0ac-f5d5-4f97-9f55-6d2e8d675ef0"
}

Proposal atomar und verbindlich annehmen

Genau ein Proposal kann gewinnen. IMMEDIATE bindet Fahrzeug und ETA sofort. DEFERRED ist nur fuer ein freigegebenes Partnerprofil erlaubt; assignmentBy wird ausschliesslich von der Plattform bestimmt. Ein Accept ist nur gueltig, wenn die nach allen Locks gelesene DB-Zeit strikt vor decisionBy liegt. Ein wegen eines anderen Gewinners zurueckgezogenes Proposal liefert 409 ALREADY_ASSIGNED; andere Withdrawals liefern PROPOSAL_WITHDRAWN. Ein identischer Idempotenz-Replay liefert immer die urspruenglich gespeicherte Antwort.

Authorizations:
(OAuth2ClientCredentialsMutualTLS)
path Parameters
id
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

Plattformvergebene Proposal-ID.

header Parameters
Idempotency-Key
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4. Der Schluesselraum besteht aus Organisation, Client, Methode, Pfadtemplate und Key. Gleicher effektiver Command liefert die urspruengliche Antwort; abweichender Command liefert 409 CONFLICT_IDEMPOTENCY.

X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Request Body schema: application/json
required
One of
assignmentMode
required
any
Value: "IMMEDIATE"
vehicleRef
required
string (ExternalRef) [ 1 .. 50 ] characters ^[A-Za-z0-9:._-]+$
eta
required
string <date-time> (DateTimeWithOffset) (?:Z|[+-][0-9]{2}:[0-9]{2})$

Responses

Request samples

Content type
application/json
Example
{
  • "assignmentMode": "IMMEDIATE",
  • "vehicleRef": "OP-1:V-12",
  • "eta": "2026-07-13T07:58:00+02:00"
}

Response samples

Content type
application/json
{
  • "proposalId": "7a99bdf5-77f0-4b57-8906-5f58230bc876",
  • "bookingId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "proposalState": "ACCEPTED",
  • "bookingState": "CONFIRMED",
  • "assignmentMode": "DEFERRED",
  • "assignmentBy": "2026-07-12T18:10:00+02:00"
}

Proposal ablehnen oder mit spaeteren Pickup-Fenstern gegenbieten

Lehnt ein noch offenes Proposal idempotent ab; nach Frist oder Rueckzug gilt der jeweilige 409-Konflikt. Ausschliesslich bei TIME_CONSTRAINT und counterOffersAllowed: true darf der Betreiber ein bis drei eindeutige, vollstaendige und strikt spaetere Pickup-Fenster mitsenden. Ein solcher Request schliesst das Proposal terminal als COUNTERED. Er reserviert weder Fahrzeug noch Kapazitaet. TIME_CONSTRAINT ohne Alternativen bleibt ein normaler Reject.

Authorizations:
(OAuth2ClientCredentialsMutualTLS)
path Parameters
id
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

Plattformvergebene Proposal-ID.

header Parameters
Idempotency-Key
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4. Der Schluesselraum besteht aus Organisation, Client, Methode, Pfadtemplate und Key. Gleicher effektiver Command liefert die urspruengliche Antwort; abweichender Command liefert 409 CONFLICT_IDEMPOTENCY.

X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Request Body schema: application/json
required
One of
reason
required
string (RejectReason)
Enum: "NO_CAPACITY" "OUT_OF_AREA" "EQUIPMENT_MISMATCH" "TIME_CONSTRAINT" "TECHNICAL"

PRICE_REJECTED entfaellt, solange Proposals keinen Preis enthalten; es kehrt erst mit einem Preismodell zurueck.

note
string (Note) [ 1 .. 255 ] characters

Logistik-/Zugangshinweis ohne Diagnose oder medizinischen Freitext; erkannte Gesundheitsdaten ergeben HEALTH_DATA_REJECTED.

Responses

Request samples

Content type
application/json
Example
{
  • "reason": "NO_CAPACITY"
}

Response samples

Content type
application/json
Example
{
  • "proposalId": "7a99bdf5-77f0-4b57-8906-5f58230bc876",
  • "bookingId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "journeyRef": "JOURNEY-SELF-001",
  • "legRef": "LEG-SINGLE",
  • "state": "OFFERED",
  • "transportClass": "UNQUALIFIED_KRANKENFAHRT",
  • "service": {
    },
  • "pickupRegion": {
    },
  • "dropoffRegion": {
    },
  • "timing": {
    },
  • "coverageMatch": {
    },
  • "estimates": {
    },
  • "sla": {
    },
  • "counterOffersAllowed": true,
  • "correlationId": "ed0dc0ac-f5d5-4f97-9f55-6d2e8d675ef0"
}

Gewonnenes Booking mit Durchfuehrungsdaten lesen

Patientenklardaten sind erst nach atomar gewonnener Annahme und nur fuer den Gewinner sichtbar. Fremde und noch nicht gewonnene Ressourcen sind nicht von nicht existierenden Ressourcen unterscheidbar.

Authorizations:
(OAuth2ClientCredentialsMutualTLS)
path Parameters
id
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

Plattformvergebene Booking-ID.

header Parameters
X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Responses

Response samples

Content type
application/json
{
  • "bookingId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "reference": "K-2527",
  • "state": "REQUESTED",
  • "transportClass": "UNQUALIFIED_KRANKENFAHRT",
  • "journeyRef": "JOURNEY-SELF-001",
  • "patient": {
    },
  • "legs": [
    ],
  • "coverage": {
    },
  • "orderer": {
    },
  • "ruleProfile": {
    },
  • "claimReadiness": {
    },
  • "createdAt": "2026-07-12T16:00:00+02:00",
  • "updatedAt": "2026-07-12T16:00:00+02:00"
}

Gewonnenes Booking als Betreiber stornieren

Storniert idempotent nach der Zustandsregel. Eine laufende Fahrt ist kein normales Storno. Die Option-B-Connectorgrenze muss die KTW-Endlage anschliessend tenantbegrenzt bestaetigen. Nach CONFIRMED werden Import-, Kapazitaets- oder Assignmentfehler zuerst als booking.exception gemeldet und danach sichtbar mit OPERATOR_CANCELLED storniert. Es folgt kein automatischer Re-Dispatch und niemals NOT_SERVED.

Authorizations:
(OAuth2ClientCredentialsMutualTLS)
path Parameters
id
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

Plattformvergebene Booking-ID.

header Parameters
Idempotency-Key
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4. Der Schluesselraum besteht aus Organisation, Client, Methode, Pfadtemplate und Key. Gleicher effektiver Command liefert die urspruengliche Antwort; abweichender Command liefert 409 CONFLICT_IDEMPOTENCY.

X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Request Body schema: application/json
required
reason
required
string
Enum: "PATIENT_NOT_READY" "NO_SHOW" "OPERATOR_CANCELLED" "OTHER_CODED"
note
string (Note) [ 1 .. 255 ] characters

Logistik-/Zugangshinweis ohne Diagnose oder medizinischen Freitext; erkannte Gesundheitsdaten ergeben HEALTH_DATA_REJECTED.

Responses

Request samples

Content type
application/json
{
  • "reason": "OPERATOR_CANCELLED",
  • "note": "Fahrzeugbindung fehlgeschlagen; Eskalation wurde ausgeloest."
}

Response samples

Content type
application/json
{
  • "bookingId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "reference": "K-2527",
  • "state": "REQUESTED",
  • "transportClass": "UNQUALIFIED_KRANKENFAHRT",
  • "journeyRef": "JOURNEY-SELF-001",
  • "patient": {
    },
  • "legs": [
    ],
  • "coverage": {
    },
  • "orderer": {
    },
  • "ruleProfile": {
    },
  • "claimReadiness": {
    },
  • "createdAt": "2026-07-12T16:00:00+02:00",
  • "updatedAt": "2026-07-12T16:00:00+02:00"
}

Gewinner meldet zweckgebunden erfasste Versicherungsdaten

Nur der aktuelle Gewinner des adressierten Legs darf die spaet erfassten Fakten idempotent melden; Transportstatus und Claim-Readiness bleiben getrennt.

Authorizations:
(OAuth2ClientCredentialsMutualTLS)
path Parameters
id
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

Plattformvergebene Booking-ID.

legRef
required
string (ExternalRef) [ 1 .. 50 ] characters ^[A-Za-z0-9:._-]+$
Examples: ORG-4711-P-0032

Stabile, innerhalb des Bookings eindeutige Abschnittsreferenz.

header Parameters
Idempotency-Key
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4. Der Schluesselraum besteht aus Organisation, Client, Methode, Pfadtemplate und Key. Gleicher effektiver Command liefert die urspruengliche Antwort; abweichender Command liefert 409 CONFLICT_IDEMPOTENCY.

If-Match
string <= 128 characters ^"[^"]+"$

Optionale Precondition mit dem zuletzt gelesenen starken ETag. Weicht die aktuelle Ressourcenversion ab, folgt 412 PRECONDITION_FAILED ohne Wirkung. Ohne If-Match gilt Last-Write-Wins innerhalb der Idempotenzregeln.

X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Request Body schema: application/json
required
required
object (InsuredDataAcquisition)
required
object (InsuredPerson)
patientDateOfBirth
string <date>
object (Payer)

Responses

Request samples

Content type
application/json
{
  • "insuredDataAcquisition": {
    },
  • "insuredPerson": {
    },
  • "patientDateOfBirth": "2019-08-24",
  • "payer": {
    }
}

Response samples

Content type
application/json
{
  • "bookingId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "reference": "K-2527",
  • "state": "REQUESTED",
  • "transportClass": "UNQUALIFIED_KRANKENFAHRT",
  • "journeyRef": "JOURNEY-SELF-001",
  • "patient": {
    },
  • "legs": [
    ],
  • "coverage": {
    },
  • "orderer": {
    },
  • "ruleProfile": {
    },
  • "claimReadiness": {
    },
  • "createdAt": "2026-07-12T16:00:00+02:00",
  • "updatedAt": "2026-07-12T16:00:00+02:00"
}

Events

Idempotente Betreiber-Statusereignisse

Signiertes CVP-Ereignis empfangen Webhook

Die Plattform stellt mindestens einmal zu. Empfaenger deduplizieren per eventId. kid waehlt exakt das aktuelle oder ein noch gueltiges vorheriges Secret. Die Signatur ist HMAC-SHA-256 ueber t + "." + n + "." + body; kid gehoert nicht zum MAC-Input. Es gelten ein Zeitfenster von plus/minus fuenf Minuten und Nonce-Einmalverwendung.

Authorizations:
WebhookSignature
header Parameters
X-Correlation-Id
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

Von der Plattform durchgereichte UUIDv4.

X-CVP-Signature
required
string <= 300 characters ^kid=whk_[A-Za-z0-9_-]{43}, t=[0-9]{10,}, n=[...
Example: kid=whk_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA, t=1783872000, n=550e8400-e29b-41d4-a716-446655440000, v1=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=

Signatur mit versionierter Secret-Selektion; v1 signiert bytegenau <timestamp>.<nonce>.<rawBody> und bindet kid nicht erneut in den MAC-Input ein.

Request Body schema: application/json
required
One of
eventId
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
type
required
string
Enum: "booking.requested" "booking.dispatching" "booking.confirmed" "booking.time_alternatives_available" "proposal.offered" "proposal.withdrawn" "booking.assigned" "vehicle.enroute" "vehicle.arrived" "trip.started" "trip.completed" "booking.cancelled" "booking.not_served" "booking.exception" "booking.eta_updated"
occurredAt
required
string <date-time> (DateTimeWithOffset) (?:Z|[+-][0-9]{2}:[0-9]{2})$
bookingId
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
legRef
string (ExternalRef) [ 1 .. 50 ] characters ^[A-Za-z0-9:._-]+$
proposalId
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
sequence
required
integer >= 1
required
object
correlationId
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...

Responses

Request samples

Content type
application/json
Example
{
  • "eventId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "type": "booking.requested",
  • "occurredAt": "2026-07-13T07:50:00+02:00",
  • "bookingId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "legRef": "ORG-4711-P-0032",
  • "proposalId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e",
  • "sequence": 1,
  • "data": {
    },
  • "correlationId": "2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e"
}

Ein oder mehrere Betreiberereignisse idempotent melden

Der Betreiber liefert je Ereignis eine stabile sourceEventId und optional eine eigene sourceSequence. Nur die Plattform vergibt die kanonische, je Booking monotone sequence. Der Body ist immer ein Array mit 1 bis 100 Ereignissen und wird als ein idempotenter HTTP-Command behandelt. Fehlt legRef in einem Ereignis, ordnet die Plattform es dem eindeutig gewonnenen Leg des Bookings zu; ist die Zuordnung mehrdeutig, folgt 422 JOURNEY_SCOPE_CONFLICT.

Authorizations:
(OAuth2ClientCredentialsMutualTLS)
header Parameters
Idempotency-Key
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4. Der Schluesselraum besteht aus Organisation, Client, Methode, Pfadtemplate und Key. Gleicher effektiver Command liefert die urspruengliche Antwort; abweichender Command liefert 409 CONFLICT_IDEMPOTENCY.

X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Request Body schema: application/json
required
Array ([ 1 .. 100 ] items)
One of
sourceEventId
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
type
required
string
Value: "booking.assigned"
occurredAt
required
string <date-time> (DateTimeWithOffset) (?:Z|[+-][0-9]{2}:[0-9]{2})$
bookingId
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
legRef
string (ExternalRef) [ 1 .. 50 ] characters ^[A-Za-z0-9:._-]+$

Optional, wenn das Ereignis eindeutig genau einem gewonnenen Leg des Bookings zuzuordnen ist; die Plattform kanonisiert. Mehrdeutigkeit ergibt 422 JOURNEY_SCOPE_CONFLICT. Quittungen und Webhook-Envelopes tragen legRef immer.

proposalId
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
sourceSequence
integer >= 0

Optionale betreibereigene Sequenz; sie ist nie die kanonische CVP-Sequenz.

required
object
correlationId
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "receipts": [
    ]
}

Webhooks

Verwaltung eigener, vorab validierter Webhook-Ziele

Eigene Webhook-Subscription anlegen

Das Ziel muss vor Aktivierung gegen SSRF, DNS-Rebinding und die Onboarding-Allowlist validiert werden; das Secret wird genau einmal ausgegeben.

Authorizations:
OAuth2ClientCredentials
header Parameters
Idempotency-Key
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4. Der Schluesselraum besteht aus Organisation, Client, Methode, Pfadtemplate und Key. Gleicher effektiver Command liefert die urspruengliche Antwort; abweichender Command liefert 409 CONFLICT_IDEMPOTENCY.

X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Request Body schema: application/json
required
targetUrl
required
string <uri> <= 2048 characters ^https://

Vor Aktivierung gegen Onboarding-Allowlist, SSRF und DNS-Rebinding pruefen.

events
required
Array of strings (WebhookEventType) non-empty unique
Items Enum: "booking.requested" "booking.dispatching" "booking.time_alternatives_available" "proposal.offered" "proposal.withdrawn" "booking.confirmed" "booking.assigned" "vehicle.enroute" "vehicle.arrived" "trip.started" "trip.completed" "booking.cancelled" "booking.not_served" "booking.exception" "booking.eta_updated"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "webhookId": "fa39e286-7332-490c-b26d-13df5358e9c1",
  • "targetUrl": "https://partner.example.org/cvp/events",
  • "events": [
    ],
  • "createdAt": "2026-07-12T16:10:00+02:00",
  • "secret": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQ",
  • "secretKid": "whk_RqIZl4LIgn8KxW9QO-nTnv7pf0CnNrksx9fF-CXP2FE"
}

Eigene Webhook-Subscriptions cursorbasiert auflisten

Secrets werden niemals erneut ausgegeben; die Liste ist organisationsbegrenzt und limitiert.

Authorizations:
OAuth2ClientCredentials
query Parameters
cursor
string [ 1 .. 1024 ] characters

Opaker, kurzlebiger Cursor; Clients duerfen Inhalt oder Sortierschluessel nicht interpretieren.

limit
integer [ 1 .. 100 ]
Default: 50

Maximale Elementzahl; Listen ohne wirksames Limit sind unzulaessig.

header Parameters
X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Responses

Response samples

Content type
application/json
{
  • "items": [ ]
}

Eigene Webhook-Subscription loeschen

Loescht eine eigene Subscription idempotent innerhalb des Idempotency-Key-Raums; fremde IDs erscheinen als NOT_FOUND.

Authorizations:
OAuth2ClientCredentials
path Parameters
id
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

Plattformvergebene Subscription-ID.

header Parameters
Idempotency-Key
required
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4. Der Schluesselraum besteht aus Organisation, Client, Methode, Pfadtemplate und Key. Gleicher effektiver Command liefert die urspruengliche Antwort; abweichender Command liefert 409 CONFLICT_IDEMPOTENCY.

X-Correlation-Id
string <uuid> (UuidV4) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3...
Examples: 2e0fcfa3-54d8-4c47-8526-b5b8b3dcc75e

UUIDv4; fehlt sie, erzeugt die Plattform eine und gibt sie in jeder Antwort zurueck.

Responses

Response samples

Content type
application/json
{
  • "type": "https://api.coderis.de/errors/VALIDATION_ERROR",
  • "code": "VALIDATION_ERROR",
  • "message": "pickupWindow.latest liegt vor pickupWindow.earliest",
  • "field": "pickupWindow.latest",
  • "correlationId": "ed0dc0ac-f5d5-4f97-9f55-6d2e8d675ef0",
  • "retriable": false
}