{"openapi":"3.0.3","info":{"title":"TransferTourism Enterprise API","version":"1.0.0","description":"Enterprise transfer API. The partner is merchant of record and passenger collection is represented by COLLECTED_BY_PARTNER."},"servers":[{"url":"https:\/\/api.transfertourism.com\/v1","description":"Production"},{"url":"https:\/\/sandbox-api.transfertourism.com\/v1","description":"Sandbox"}],"security":[{"EnterpriseHmac":[]}],"components":{"securitySchemes":{"EnterpriseHmac":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Also requires X-TIMESTAMP, X-NONCE and X-SIGNATURE. Signature is HMAC-SHA256({timestamp}.{nonce}.{method}.{path}.{sha256(raw-body)})."}},"parameters":{"BookingId":{"name":"booking_id","in":"path","required":true,"schema":{"type":"string"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":128}}},"schemas":{"Place":{"type":"object","required":["type","name","lat","lng","country_code"],"properties":{"type":{"type":"string","enum":["AIRPORT","HOTEL","ADDRESS","POI"]},"name":{"type":"string"},"lat":{"type":"number","format":"double"},"lng":{"type":"number","format":"double"},"city":{"type":"string","nullable":true},"country_code":{"type":"string","minLength":2,"maxLength":2},"external_id":{"type":"string","nullable":true},"hotel_id":{"type":"integer","nullable":true},"hotel_uuid":{"type":"string","format":"uuid","nullable":true},"place_id":{"type":"string","nullable":true}}},"Pax":{"type":"object","required":["adults"],"properties":{"adults":{"type":"integer","minimum":1},"children":{"type":"integer","minimum":0},"infants":{"type":"integer","minimum":0}}},"Flight":{"type":"object","properties":{"code":{"type":"string","maxLength":50},"date":{"type":"string","format":"date"}}},"FxSnapshot":{"type":"object","properties":{"fx_rate_id":{"type":"string"},"source":{"type":"string","example":"TCMB"},"type":{"type":"string","example":"TCMB_EXCHANGE_SELLING"},"rate_date":{"type":"string","format":"date"},"rate_value":{"type":"number"},"try_per_unit":{"type":"number"},"rate_value_try_per_1":{"type":"object","properties":{"USD":{"type":"number","nullable":true},"EUR":{"type":"number","nullable":true}}},"is_stale":{"type":"boolean"}}},"CancellationPolicy":{"type":"object","properties":{"free_cancel_until":{"type":"string","format":"date-time","nullable":true},"free_update_until":{"type":"string","format":"date-time","nullable":true},"cancel_cutoff_minutes":{"type":"integer"},"update_cutoff_minutes":{"type":"integer"},"no_show_grace_minutes":{"type":"integer"}}},"QuoteVehicle":{"type":"object","properties":{"vehicle_id":{"type":"integer"},"title":{"type":"string"},"category":{"type":"string"},"capacity":{"type":"integer"},"luggage_capacity":{"type":"integer"},"amount":{"type":"number"},"base_currency":{"type":"string","example":"USD"},"base_amount":{"type":"number"},"base_amount_try":{"type":"number"},"amount_try":{"type":"number"},"amount_in_invoice_currency":{"type":"number"},"invoice_currency":{"type":"string","enum":["TRY","USD","EUR"]},"currency":{"type":"string"},"pricing_source":{"type":"string"}}},"Quote":{"type":"object","required":["quote_id","expires_at","vehicles","currency","fx","cancellation_policy"],"properties":{"quote_id":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"currency":{"type":"string","enum":["TRY","USD","EUR"]},"invoice_currency":{"type":"string","enum":["TRY","USD","EUR"]},"fx_rate_id":{"type":"string","nullable":true},"fx_rate_date":{"type":"string","format":"date","nullable":true},"fx_rate_value":{"type":"number","nullable":true},"distance_km":{"type":"number","nullable":true},"duration_min":{"type":"integer","nullable":true},"vehicles":{"type":"array","items":{"$ref":"#\/components\/schemas\/QuoteVehicle"}},"fx":{"$ref":"#\/components\/schemas\/FxSnapshot"},"cancellation_policy":{"$ref":"#\/components\/schemas\/CancellationPolicy"}}},"Passenger":{"type":"object","required":["first_name","email","phone"],"properties":{"first_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":30}}},"Booking":{"type":"object","required":["booking_id","status","payment_status","operation_status","amount_in_invoice_currency","invoice_currency","fx_rate_id"],"properties":{"booking_id":{"type":"string"},"partner_reference":{"type":"string"},"status":{"type":"string","example":"CONFIRMED"},"operation_status":{"type":"string","enum":["PENDING","DRIVER_ASSIGNED","ON_THE_WAY","PICKED_UP","COMPLETED","CANCELLED","NO_SHOW"]},"status_updated_at":{"type":"string","format":"date-time","nullable":true},"picked_up_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"cancelled_at":{"type":"string","format":"date-time","nullable":true},"payment_status":{"type":"string","enum":["COLLECTED_BY_PARTNER"]},"amount_try":{"type":"number"},"amount_in_invoice_currency":{"type":"number"},"invoice_currency":{"type":"string","enum":["TRY","USD","EUR"]},"fx_rate_id":{"type":"string","nullable":true},"fx":{"$ref":"#\/components\/schemas\/FxSnapshot"},"cancellation_policy":{"$ref":"#\/components\/schemas\/CancellationPolicy"},"pickup":{"type":"string"},"dropoff":{"type":"string"},"pickup_datetime":{"type":"string","format":"date-time"},"flight_code":{"type":"string","nullable":true},"flight":{"$ref":"#\/components\/schemas\/Flight"},"dispute_status":{"type":"string","enum":["NONE","OPEN","ACCEPTED","REJECTED"]}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","details"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}},"paths":{"\/places":{"get":{"summary":"Search normalized places","parameters":[{"name":"query","in":"query","schema":{"type":"string"}},{"name":"country_code","in":"query","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20}}],"responses":{"200":{"description":"Normalized Place objects","content":{"application\/json":{"schema":{"type":"object","required":["places"],"properties":{"places":{"type":"array","items":{"$ref":"#\/components\/schemas\/Place"}}}}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/quotes":{"post":{"summary":"Create a quote with a locked FX snapshot","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["from","to","pickup_datetime","pax","luggage"],"properties":{"from":{"$ref":"#\/components\/schemas\/Place"},"to":{"$ref":"#\/components\/schemas\/Place"},"pickup_datetime":{"type":"string","format":"date-time"},"pax":{"$ref":"#\/components\/schemas\/Pax"},"luggage":{"type":"integer","minimum":0},"flight":{"$ref":"#\/components\/schemas\/Flight"},"is_round_trip":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Quote with quote_id, expires_at, vehicles, FX snapshot and cancellation policy","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Quote"}}}},"422":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"503":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/bookings":{"post":{"summary":"Create a booking from a non-expired quote","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["quote_id","partner_reference","passenger"],"properties":{"quote_id":{"type":"string"},"vehicle_id":{"type":"integer"},"partner_reference":{"type":"string"},"passenger":{"$ref":"#\/components\/schemas\/Passenger"},"flight":{"$ref":"#\/components\/schemas\/Flight"}}}}}},"responses":{"201":{"description":"Booking response","content":{"application\/json":{"schema":{"type":"object","required":["booking"],"properties":{"booking":{"$ref":"#\/components\/schemas\/Booking"}}}}}},"200":{"description":"Booking response","content":{"application\/json":{"schema":{"type":"object","required":["booking"],"properties":{"booking":{"$ref":"#\/components\/schemas\/Booking"}}}}}},"409":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}},"get":{"summary":"List the authenticated firm bookings","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"partner_reference","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Booking list","content":{"application\/json":{"schema":{"type":"object","required":["bookings"],"properties":{"bookings":{"type":"array","items":{"$ref":"#\/components\/schemas\/Booking"}}}}}}},"422":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/bookings\/{booking_id}":{"get":{"summary":"Get one booking","parameters":[{"$ref":"#\/components\/parameters\/BookingId"}],"responses":{"200":{"description":"Booking response","content":{"application\/json":{"schema":{"type":"object","required":["booking"],"properties":{"booking":{"$ref":"#\/components\/schemas\/Booking"}}}}}},"404":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/bookings\/{booking_id}\/cancel":{"post":{"summary":"Cancel before the configured cutoff","parameters":[{"$ref":"#\/components\/parameters\/BookingId"}],"responses":{"200":{"description":"Booking response","content":{"application\/json":{"schema":{"type":"object","required":["booking"],"properties":{"booking":{"$ref":"#\/components\/schemas\/Booking"}}}}}},"404":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/bookings\/{booking_id}\/update":{"post":{"summary":"Update flight, pickup time or note before cutoff","parameters":[{"$ref":"#\/components\/parameters\/BookingId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"flight_code":{"type":"string","maxLength":50},"flight_date":{"type":"string","format":"date"},"flight":{"$ref":"#\/components\/schemas\/Flight"},"pickup_time":{"type":"string","format":"time"},"note":{"type":"string"}}}}}},"responses":{"200":{"description":"Booking response","content":{"application\/json":{"schema":{"type":"object","required":["booking"],"properties":{"booking":{"$ref":"#\/components\/schemas\/Booking"}}}}}},"404":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/bookings\/updates":{"get":{"summary":"Return changed records since a timestamp","parameters":[{"name":"updated_after","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Booking list","content":{"application\/json":{"schema":{"type":"object","required":["bookings"],"properties":{"bookings":{"type":"array","items":{"$ref":"#\/components\/schemas\/Booking"}}}}}}},"422":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}}}}