{"openapi":"3.1.0","info":{"title":"White-Label Multi-Tenant Mobility Platform API","version":"0.1.0","description":"Brand-independent modular monolith API (PostgreSQL app_core + RLS, Drizzle ORM, statutory EU invoicing, OSRM & Stripe Connect)."},"paths":{"/api/v1/health":{"get":{"tags":["system"],"summary":"Liveness, readiness & PostgreSQL (app-main / app_core / main-user) contract check","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/config/bootstrap":{"get":{"tags":["system"],"summary":"Dynamic white-label branding, colors, locales, EU operating countries & pricing policy per tenant","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/system/diagnostics":{"get":{"tags":["system"],"summary":"Real-time endpoint latency metrics, tenant request counters, and transactional outbox event log","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/metrics":{"get":{"tags":["system"],"summary":"Prometheus exposition format metrics for Grafana / Loki observability stack","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/auth/otp/request":{"post":{"tags":["identity"],"summary":"Request SMS OTP login challenge (strictly rate-limited per IP and tenant)","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/auth/otp/verify":{"post":{"tags":["identity"],"summary":"Verify OTP and issue HMAC-SHA256 tenant-bound JWT access token + rotating refresh token","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/users/{userId}/account":{"get":{"tags":["users"],"summary":"Get customer personal profile, Business B2B invoice profile, saved places & emergency contact","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}},"put":{"tags":["users"],"summary":"Update customer personal & Business B2B fiscal profile","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/drivers/{driverId}/account":{"get":{"tags":["drivers"],"summary":"Get driver profile, vehicle, statutory carrier fiscal profile (KvK/BTW/KOR/IBAN), navigation prefs & KIWA docs","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}},"put":{"tags":["drivers"],"summary":"Update driver statutory carrier profile, tax regime (standard_vat / kor_exempt) & preferred navigation app","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/drivers/{driverId}/tariff":{"get":{"tags":["drivers"],"summary":"Get driver custom ride price factor (%) and tariff version","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}},"put":{"tags":["drivers"],"summary":"Set driver custom price factor (%) within tenant bounds and increment tariff version","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/geo/autocomplete":{"get":{"tags":["geo"],"summary":"PDOK / Photon address, postcode & POI autocomplete within active tenant country","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/geo/validate-address":{"post":{"tags":["geo"],"summary":"Validate address clarity (Postcode+HouseNo, missing house number, ambiguous city, or EU domestic-only geofence)","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/rides/compose-preview":{"post":{"tags":["rides"],"summary":"Calculate multi-stop OSRM route distance/duration and upfront prices across all 4 vehicle classes","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/rides/request":{"post":{"tags":["rides"],"summary":"Create new ride request (supports Idempotency-Key header to prevent double booking)","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/rides/{rideId}/accept":{"post":{"tags":["rides"],"summary":"Driver accepts ride: locks agreed driver tariff, shares driver photo/vehicle card, generates 4-digit PIN & phase-1 Waze/Google deep-links","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/rides/{rideId}/verify-pin":{"post":{"tags":["rides"],"summary":"Verify shared 4-digit customer security PIN at pickup and auto-switch navigation deep-links to final destination","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/rides/{rideId}/complete":{"post":{"tags":["rides"],"summary":"Complete ride, book double-entry ledger, and issue statutory Customer (B2B/B2C) & Driver Commission (Art. 35a / ICP 3b) invoices","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/invoices/{invoiceId}/pdf":{"get":{"tags":["payments"],"summary":"Download native binary PDF 1.4 statutory invoice (Customer Ride Invoice, Driver Commission Statement, or Credit Note)","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/invoices/{invoiceId}/credit":{"post":{"tags":["payments"],"summary":"Issue immutable statutory Credit Note (CRED-...) reversing an invoice (Art. 35a Wet OB)","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/accounting/driver/{driverId}":{"get":{"tags":["payments"],"summary":"Driver bookkeeping summary with official Belastingdienst VAT return boxes (1b, 1e, 5b, 5g) and EU DAC7 report row","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/accounting/customer/{userId}":{"get":{"tags":["payments"],"summary":"Customer bookkeeping summary strictly separated into Business (B2B with Rubriek 5b VAT recovery) and Private (B2C)","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/rides/wait-and-cancel-policy":{"post":{"tags":["rides"],"summary":"Calculate smart wait-time (3m street / 10m flight grace), late-cancellation en-route fee, or GPS-verified No-Show compensation","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/compliance/ilt-cdt-pass/{driverId}":{"get":{"tags":["drivers"],"summary":"Dutch ILT / CDT (Centrale Database Taxivervoer) & ATBv work/rest-time digital roadside inspection pass with SHA-256 signature","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/accounting/corporate-monthly":{"get":{"tags":["payments"],"summary":"B2B Corporate Account (`Op Rekening`) monthly consolidated invoice specification & Hotel/Hospital Concierge rides","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/accounting/corporate-monthly/pdf":{"get":{"tags":["payments"],"summary":"Download native binary PDF 1.4 Monthly Consolidated B2B Invoice (`VERZ-...`) with itemized cost centers & Rubriek 5b VAT","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/support/tickets":{"post":{"tags":["support"],"summary":"Create Privacy-First Lost & Found (`Gevonden Voorwerpen`) with AVG/GDPR Masked Phone Relay or TTO/TX-Keur dispute ticket","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/webhooks/stripe":{"post":{"tags":["payments"],"summary":"Cryptographic Stripe Connect Webhook receiver (`Stripe-Signature` HMAC-SHA256) with automatic Credit Note (`CRED-...`) on refund","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/events/stream":{"get":{"tags":["notifications"],"summary":"Real-time Server-Sent Events (SSE) push stream for Driver & Customer apps and Dispatch consoles","parameters":[{"name":"X-Platform-Tenant-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"429":{"description":"Rate limit exceeded"}}}}}}