{"openapi":"3.1.0","info":{"title":"Capital VIP Services Booking API","version":"1.0.0","description":"API contract for AI agents to quote, prepare, confirm, and send users to payment for chauffeur bookings. This file defines the target integration; endpoints must be implemented server-side before agents can transact."},"servers":[{"url":"https://capitalvipservices.com"}],"paths":{"/api/services":{"get":{"operationId":"listServices","summary":"List available chauffeur services and vehicle categories.","responses":{"200":{"description":"Available services and vehicles.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServicesResponse"}}}}}}},"/api/quote":{"post":{"operationId":"getQuote","summary":"Calculate a quote from booking details.","description":"Uses Google Maps Routes API server-side to calculate driving distance. The commercial pricing logic should stay server-side and must not be exposed to the client.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"200":{"description":"Quote ready for user confirmation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}}}}},"/api/bookings":{"post":{"operationId":"createBooking","summary":"Create a pending booking after explicit user confirmation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBookingRequest"}}}},"responses":{"201":{"description":"Pending booking created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingResponse"}}}}}}},"/api/bookings/{booking_id}/payment-link":{"post":{"operationId":"createPaymentLink","summary":"Create a secure payment link for a pending booking.","parameters":[{"name":"booking_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLinkRequest"}}}},"responses":{"200":{"description":"Payment link created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLinkResponse"}}}}}}},"/api/bookings/{booking_id}":{"get":{"operationId":"getBookingStatus","summary":"Get booking and payment status.","parameters":[{"name":"booking_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Current booking status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingResponse"}}}}}}}},"components":{"schemas":{"ServicesResponse":{"type":"object","properties":{"services":{"type":"array","items":{"type":"string"}},"vehicle_categories":{"type":"array","items":{"$ref":"#/components/schemas/VehicleCategory"}}},"required":["services","vehicle_categories"]},"VehicleCategory":{"type":"object","properties":{"id":{"type":"string","enum":["business","first","van"]},"label":{"type":"string"},"passengers_max":{"type":"integer"}},"required":["id","label","passengers_max"]},"QuoteRequest":{"type":"object","properties":{"service_type":{"type":"string"},"pickup_address":{"type":"string"},"dropoff_address":{"type":"string"},"date":{"type":"string","format":"date"},"time":{"type":"string","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$"},"passengers":{"type":"integer","minimum":1,"maximum":7},"vehicle_category":{"type":"string","enum":["business","first","van"]},"luggage_count":{"type":"integer","minimum":0},"duration_hours":{"type":"integer","minimum":3,"maximum":24},"special_requests":{"type":"string"}},"required":["service_type","pickup_address","dropoff_address","date","time","passengers","vehicle_category"],"additionalProperties":false},"QuoteResponse":{"type":"object","properties":{"quote_id":{"type":"string"},"currency":{"type":"string","const":"EUR"},"amount":{"type":"integer","description":"Amount in cents."},"distance_km":{"type":"number"},"expires_at":{"type":"string","format":"date-time"},"summary":{"type":"string"},"requires_user_confirmation":{"type":"boolean","const":true}},"required":["quote_id","currency","amount","summary","requires_user_confirmation"]},"CreateBookingRequest":{"type":"object","properties":{"quote_id":{"type":"string"},"customer_name":{"type":"string"},"customer_phone":{"type":"string"},"customer_email":{"type":"string","format":"email"},"confirmed_by_user":{"type":"boolean","const":true},"summary":{"type":"string"}},"required":["quote_id","customer_name","customer_phone","customer_email","confirmed_by_user"],"additionalProperties":false},"PaymentLinkRequest":{"type":"object","properties":{"quote_id":{"type":"string"},"quote_payload":{"$ref":"#/components/schemas/QuoteRequest","description":"Booking details are repriced server-side before payment creation."},"customer_email":{"type":"string","format":"email"}},"required":["quote_payload"],"additionalProperties":false},"BookingResponse":{"type":"object","properties":{"booking_id":{"type":"string"},"status":{"type":"string","enum":["pending_payment","paid","confirmed","cancelled"]},"payment_status":{"type":"string","enum":["not_created","pending","paid","failed"]},"summary":{"type":"string"}},"required":["booking_id","status","payment_status","summary"]},"PaymentLinkResponse":{"type":"object","properties":{"booking_id":{"type":"string"},"payment_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"}},"required":["booking_id","payment_url"]}}}}