{ "openapi": "3.1.0", "info": { "title": "Aruba Your Way · Van Tour Planning and Guest Operations API", "version": "1.2.0", "description": "Public discovery, quotes and booking handoff remain stateless and accept no personal/card fields. The separate question endpoint sends an authorized inquiry with a reply email and retains hashed duplicate/rate metadata. Separate expiring guest-approved capabilities support drafts, verified booking outcomes, and reservation service requests. Guests complete booking on the website. No payment actions or raw card data. All money is whole USD. Canonical page: https://arubasightseeingtours.com/." }, "servers": [ { "url": "https://arubasightseeingtours.com/van-tour/api/v1" } ], "paths": { "/index.php": { "get": { "operationId": "discoverVanTourAPI", "summary": "API links and version", "description": "API links and version.", "security": [], "responses": { "200": { "description": "API links and version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discovery" } } } }, "400": { "description": "Malformed JSON or unsupported query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry or use the tour page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/service.php": { "get": { "operationId": "getPrivateVanTour", "summary": "Owner-approved tour facts, price rules and booking policies", "description": "Owner-approved tour facts, price rules and booking policies. No live inventory check.", "security": [], "responses": { "200": { "description": "Owner-approved tour facts, price rules and booking policies. No live inventory check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "description": "Malformed JSON or unsupported query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry or use the tour page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/stops.php": { "get": { "operationId": "getVanTourStops", "summary": "All 25 selectable stops and separate attraction admission rules", "description": "All 25 selectable stops and separate attraction admission rules.", "security": [], "responses": { "200": { "description": "All 25 selectable stops and separate attraction admission rules.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } }, "400": { "description": "Malformed JSON or unsupported query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry or use the tour page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/quote.php": { "post": { "operationId": "quotePrivateVanTour", "summary": "Calculate a whole-dollar tour total with the same calculator as checkout", "description": "Calculate a whole-dollar tour total with the same calculator as checkout. Does not create or reserve a booking.", "security": [], "responses": { "200": { "description": "Calculate a whole-dollar tour total with the same calculator as checkout. Does not create or reserve a booking.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Malformed JSON or unsupported query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry or use the tour page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 8192 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid party, duration, stops or schedule; correct before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "adults": 7, "children": 0, "duration_hours": 4, "stop_ids": [ "california-lighthouse", "tres-trapi", "bushiribana", "casibari" ] } } } } } }, "/handoff.php": { "post": { "operationId": "prepareVanTourHandoff", "summary": "Return a prefilled booking-page link", "description": "Return a prefilled booking-page link. No personal data, payment data, booking creation, inventory hold or email. The guest must review, consent and complete Stripe card saving on the website.", "security": [], "responses": { "200": { "description": "Return a prefilled booking-page link. No personal data, payment data, booking creation, inventory hold or email. The guest must review, consent and complete Stripe card saving on the website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Handoff" } } } }, "400": { "description": "Malformed JSON or unsupported query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry or use the tour page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 8192 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid party, duration, stops or schedule; correct before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "adults": 7, "children": 0, "duration_hours": 4, "stop_ids": [ "california-lighthouse", "tres-trapi", "bushiribana", "casibari" ] } } } } } }, "/question.php": { "post": { "operationId": "sendTourQuestion", "summary": "Send an authorized question", "description": "Send a tour question to the team with the customer’s explicit permission to share the question and reply email. This sends an email and is NOT read-only. No booking, payment, amendment or cancellation is performed. Returns received and a reference only after mail transport accepts it, not proof of inbox delivery. Reuse request_id and identical content on retries for seven days; never restart an uncertain send. Shared limits, spam screening and duplicate protection apply; suspicious requests require staff verification by phone. No API key needed. Do not send card details or attachments.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Question" } } } }, "responses": { "200": { "description": "Received; reuse the reference for follow-up. Not a reservation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResult" } } } }, "400": { "description": "Malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResult" } } } }, "403": { "description": "Verification required; nothing sent. Contact the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResult" } } } }, "405": { "description": "Use POST.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResult" } } } }, "409": { "description": "Request ID reused with changed content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResult" } } } }, "413": { "description": "Maximum body is 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResult" } } } }, "415": { "description": "Send application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResult" } } } }, "422": { "description": "Invalid question or missing customer permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResult" } } } }, "429": { "description": "Rate limited; honor retry_after_seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResult" } } } }, "503": { "description": "Busy, unavailable or uncertain delivery. Retry the SAME request only; read status and message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResult" } } } } } } }, "/assess.php": { "post": { "operationId": "assessVanTourRequest", "summary": "Assess a complete tour request", "description": "Assess a supplied plan against explicit customer requirements and return an exact group quote, evidence links and unmet or unresolved needs. Read-only: no booking or contact. This is product-fit checking, not live inventory, exact route planning, opening-hour or sea-condition verification. Present all qualifications; never report product_fit as a confirmed reservation. Unknown needs go in other and require team confirmation. No personal or card data.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssessmentInput" } } } }, "responses": { "200": { "description": "Product-fit assessment with qualifications.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Assessment" } } } }, "422": { "description": "Invalid plan or requirements; correct before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/operation.php": { "post": { "operationId": "customerApprovedVanOperation", "summary": "Customer-approved draft and reservation operations", "description": "Private operation credentials are per draft/reservation, not an account API key or OAuth login. Create a draft only with permission; customer approval happens on the website. Reservation access additionally requires the guest to verify their recorded email and approve one hour of delegated access. Never ask for the verification code. A submitted change/cancellation is pending until the team completes it. No card details, charges or refunds are handled here. Keep credentials and proposal tokens out of URLs, analytics and logs. Retry identical requests after uncertain responses.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "operation": { "const": "create_draft" }, "arguments": { "$ref": "#/components/schemas/AgentDraft" } }, "required": [ "operation", "arguments" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "const": "begin_access" }, "arguments": { "$ref": "#/components/schemas/AgentAccess" } }, "required": [ "operation", "arguments" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "const": "outcome" }, "arguments": { "$ref": "#/components/schemas/AgentCredential" } }, "required": [ "operation", "arguments" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "const": "reservation" }, "arguments": { "$ref": "#/components/schemas/AgentCredential" } }, "required": [ "operation", "arguments" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "const": "preview_request" }, "arguments": { "$ref": "#/components/schemas/AgentRequestPreview" } }, "required": [ "operation", "arguments" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "const": "submit_request" }, "arguments": { "$ref": "#/components/schemas/AgentRequestSubmit" } }, "required": [ "operation", "arguments" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Operation state. Confirmed means a verified booking receipt; pending is not a completed change.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing, expired, revoked or wrong-scope authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or stale preview; review again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Uncertain or unavailable. Retry the same request, never duplicate it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Plan": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 40, "description": "Total passengers aged 13 or older. Maximum 10 per van; provide vans for multiple vans." }, "children": { "type": "integer", "minimum": 0, "maximum": 36, "description": "Passengers aged 0–12; free on the tour but counted toward capacity." }, "vans": { "type": "array", "minItems": 1, "maxItems": 4, "description": "Optional per-van passenger allocation. Counts must add up to adults and children; each van requires 1–10 guests including at least one adult. Each van is priced and rounded down separately, then totals are added. All vans share date, start time and duration. Omit for one van.", "items": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 10 }, "children": { "type": "integer", "minimum": 0, "maximum": 9 } }, "required": [ "adults", "children" ], "additionalProperties": false } }, "duration_hours": { "type": "integer", "minimum": 4, "maximum": 8 }, "stop_ids": { "type": "array", "items": { "type": "string", "enum": [ "tres-trapi", "bushiribana", "natural-bridge", "ayo", "casibari", "california-lighthouse", "seroe-colorado", "mangel-halto", "arikok", "eagle-beach", "hooiberg", "malmok", "palm-beach", "donkey-sanctuary", "oranjestad", "arashi", "red-anchor", "san-nicolas", "rodgers", "boca-catalina", "baby-beach", "alto-vista", "philips-garden", "butterfly-farm", "ostrich-farm" ] }, "maxItems": 25, "uniqueItems": true, "default": [], "description": "Optional wish list, not a guaranteed driving route. Empty means decide with the guide." }, "tour_date": { "type": "string", "format": "date", "description": "Optional. Must be supplied together with pickup_time, at least 24 hours ahead in America/Aruba." }, "pickup_time": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):(?:00|15|30|45)$", "description": "Aruba local time, HH:mm. Afternoon starts are supported; this does not check attraction opening hours." } }, "required": [ "adults", "children", "duration_hours" ], "additionalProperties": false, "dependentRequired": { "tour_date": [ "pickup_time" ], "pickup_time": [ "tour_date" ] } }, "Price": { "type": "object", "properties": { "base": { "type": "integer", "minimum": 0, "description": "Whole US dollars, not cents." }, "extra_adults": { "type": "integer", "minimum": 0, "description": "Whole US dollars, not cents." }, "subtotal": { "type": "integer", "minimum": 0, "description": "Whole US dollars, not cents." }, "tax_and_card_fee": { "type": "integer", "minimum": 0, "description": "Whole US dollars, not cents." }, "total": { "type": "integer", "minimum": 0, "description": "Whole US dollars, not cents." }, "amount_due_today": { "type": "integer", "minimum": 0, "description": "Whole US dollars, not cents." }, "money_unit": { "const": "whole_USD" }, "attraction_admission_included": { "const": false }, "vans": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "type": "object", "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "subtotal": { "type": "integer", "minimum": 0, "description": "Whole US dollars, not cents." }, "fee": { "type": "integer", "minimum": 0, "description": "Whole US dollars, not cents." }, "total": { "type": "integer", "minimum": 0, "description": "Whole US dollars, not cents." } }, "required": [ "adults", "children", "subtotal", "fee", "total" ] } } }, "required": [ "base", "extra_adults", "subtotal", "tax_and_card_fee", "total", "amount_due_today", "money_unit", "attraction_admission_included" ] }, "Admission": { "type": "object", "properties": { "currency": { "const": "USD" }, "source": { "type": "string" }, "updated": { "type": "string", "format": "date" }, "kind": { "enum": [ "free", "paid", "optional_activity" ] }, "base_entry": { "type": "integer", "minimum": 0, "description": "Whole US dollars, not cents." }, "activity": { "type": "string" }, "admission_group": { "type": "string" }, "charge_once_per_person": { "type": "boolean" }, "covers": { "type": "array", "items": { "type": "string" } }, "rates": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "amount": { "type": "integer", "minimum": 0, "description": "Whole US dollars, not cents." }, "age_min": { "type": "integer" }, "age_max": { "type": "integer" } }, "required": [ "category", "amount" ] } }, "age_boundaries_confirmed": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "currency", "source", "updated", "kind", "rates" ] }, "Stop": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "includes": { "type": "array", "items": { "type": "string" } }, "entry_fee": { "type": "string" }, "fee_details": { "type": "array", "items": { "type": "string" } }, "visit_note": { "type": "string" }, "admission": { "$ref": "#/components/schemas/Admission" } }, "required": [ "id", "name", "category", "description", "entry_fee", "fee_details", "admission" ] }, "Quote": { "type": "object", "properties": { "api_version": { "type": "string" }, "service_id": { "const": "private-van-tour" }, "facts_updated": { "type": "string", "format": "date" }, "source": { "type": "string", "format": "uri" }, "operator": { "type": "string" }, "currency": { "const": "USD" }, "timezone": { "const": "America/Aruba" }, "pricing_version": { "type": "string" }, "quoted_at": { "type": "string", "format": "date-time" }, "plan": { "$ref": "#/components/schemas/Plan" }, "price": { "$ref": "#/components/schemas/Price" }, "selected_attraction_fees": { "type": "array", "items": { "$ref": "#/components/schemas/Stop" } }, "admission_total": { "type": "null", "description": "Not estimated from adult/child tour counts; attraction age bands and optional activities differ." }, "admission_note": { "type": "string" }, "suggested_stops": { "type": "object", "properties": { "minimum": { "type": "integer" }, "maximum": { "type": "integer" } }, "required": [ "minimum", "maximum" ] }, "schedule_validated": { "type": "boolean" }, "inventory_checked": { "const": false }, "route_feasibility_checked": { "const": false }, "booking_created": { "const": false }, "warnings": { "type": "array", "items": { "type": "string" } }, "recheck_price_at_booking": { "const": true } }, "required": [ "api_version", "service_id", "facts_updated", "source", "operator", "currency", "timezone", "pricing_version", "quoted_at", "plan", "price", "selected_attraction_fees", "admission_total", "admission_note", "suggested_stops", "schedule_validated", "inventory_checked", "route_feasibility_checked", "booking_created", "warnings", "recheck_price_at_booking" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Catalog": { "type": "object", "properties": { "api_version": { "type": "string" }, "service_id": { "const": "private-van-tour" }, "facts_updated": { "type": "string", "format": "date" }, "source": { "type": "string", "format": "uri" }, "operator": { "type": "string" }, "currency": { "const": "USD" }, "timezone": { "const": "America/Aruba" }, "count": { "type": "integer" }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/Stop" } } }, "required": [ "api_version", "service_id", "facts_updated", "source", "operator", "currency", "timezone", "count", "stops" ] }, "Handoff": { "allOf": [ { "$ref": "#/components/schemas/Quote" }, { "type": "object", "properties": { "handoff": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "status": { "const": "review_required" }, "creates_booking": { "const": false }, "next_step": { "type": "string" } }, "required": [ "url", "status", "creates_booking", "next_step" ] } }, "required": [ "handoff" ] } ] }, "Service": { "type": "object", "properties": { "api_version": { "type": "string" }, "service_id": { "type": "string" }, "facts_updated": { "type": "string", "format": "date" }, "source": { "type": "string" }, "operator": { "type": "string" }, "currency": { "type": "string" }, "timezone": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "string" }, "private": { "type": "boolean" }, "shared_with_other_groups": { "type": "boolean" }, "air_conditioned": { "type": "boolean" }, "local_driver_guide_included": { "type": "boolean" }, "vehicle": { "type": "string" }, "pickup": { "type": "object", "properties": { "included": { "type": "boolean" }, "area": { "type": "string" }, "hotel_or_villa": { "type": "boolean" }, "dropoff_included": { "type": "boolean" }, "address_can_be_arranged_later": { "type": "boolean" } }, "required": [ "included", "area", "hotel_or_villa", "dropoff_included", "address_can_be_arranged_later" ] }, "duration_hours": { "type": "object", "properties": { "minimum": { "type": "integer" }, "maximum": { "type": "integer" }, "increment": { "type": "integer" } }, "required": [ "minimum", "maximum", "increment" ] }, "passengers": { "type": "object", "properties": { "minimum_adults": { "type": "integer" }, "maximum_total": { "type": "integer" }, "comfortable_full_size_seats": { "type": "integer" }, "driver_counts_toward_capacity": { "type": "boolean" }, "tenth_seat": { "type": "string" }, "adult_minimum_age": { "type": "integer" }, "child_age_minimum": { "type": "integer" }, "child_age_maximum": { "type": "integer" }, "children_free": { "type": "boolean" }, "children_count_toward_capacity": { "type": "boolean" }, "multiple_vans": { "type": "object", "properties": { "maximum_vans_per_booking": { "type": "integer" }, "maximum_passengers_per_van": { "type": "integer" }, "allocation": { "type": "string" }, "pricing": { "type": "string" } }, "required": [ "maximum_vans_per_booking", "maximum_passengers_per_van", "allocation", "pricing" ] } }, "required": [ "minimum_adults", "maximum_total", "comfortable_full_size_seats", "driver_counts_toward_capacity", "tenth_seat", "adult_minimum_age", "child_age_minimum", "child_age_maximum", "children_free", "children_count_toward_capacity", "multiple_vans" ] }, "itinerary": { "type": "object", "properties": { "customizable": { "type": "boolean" }, "selection_optional": { "type": "boolean" }, "decide_with_guide_on_day": { "type": "boolean" }, "stops_catalog_count": { "type": "integer" }, "suggested_stops_four_hours": { "type": "object", "properties": { "minimum": { "type": "integer" }, "maximum": { "type": "integer" } }, "required": [ "minimum", "maximum" ] }, "suggested_stops_per_extra_hour": { "type": "object", "properties": { "minimum": { "type": "integer" }, "maximum": { "type": "integer" } }, "required": [ "minimum", "maximum" ] }, "guidance": { "type": "string" } }, "required": [ "customizable", "selection_optional", "decide_with_guide_on_day", "stops_catalog_count", "suggested_stops_four_hours", "suggested_stops_per_extra_hour", "guidance" ] }, "pricing": { "type": "object", "properties": { "version": { "type": "string" }, "money_unit": { "type": "string" }, "base_four_hours_up_to_three_adults": { "type": "integer" }, "additional_hour_base": { "type": "integer" }, "additional_adult_per_hour_after_three": { "type": "integer" }, "tax_and_card_fee_percent": { "type": "integer" }, "rounding": { "type": "string" }, "attraction_admission_included": { "type": "boolean" }, "admission_note": { "type": "string" }, "included_adults": { "type": "integer" }, "tax_percent": { "type": "integer" }, "card_fee_percent": { "type": "integer" }, "formula": { "type": "string" } }, "required": [ "version", "money_unit", "base_four_hours_up_to_three_adults", "additional_hour_base", "additional_adult_per_hour_after_three", "tax_and_card_fee_percent", "rounding", "attraction_admission_included", "admission_note", "included_adults", "tax_percent", "card_fee_percent", "formula" ] }, "schedule": { "type": "object", "properties": { "minimum_notice_hours": { "type": "integer" }, "pickup_increment_minutes": { "type": "integer" }, "pickup_time_format": { "type": "string" }, "inventory_checked": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "minimum_notice_hours", "pickup_increment_minutes", "pickup_time_format", "inventory_checked", "note" ] }, "booking": { "type": "object", "properties": { "confirmation": { "type": "string" }, "staff_followup_within_hours": { "type": "integer" }, "amount_due_today": { "type": "integer" }, "charge_hours_before_start": { "type": "integer" }, "free_cancel_or_change_before_hours": { "type": "integer" }, "late_cancellation_charge_percent": { "type": "integer" }, "no_show_charge_percent": { "type": "integer" }, "card_required": { "type": "boolean" }, "card_collection": { "type": "string" }, "card_save_is_funds_hold": { "type": "boolean" }, "policy": { "type": "string" }, "handoff_creates_booking": { "type": "boolean" }, "human_review_and_consent_required": { "type": "boolean" }, "statement_descriptor": { "type": "string" } }, "required": [ "confirmation", "staff_followup_within_hours", "amount_due_today", "charge_hours_before_start", "free_cancel_or_change_before_hours", "late_cancellation_charge_percent", "no_show_charge_percent", "card_required", "card_collection", "card_save_is_funds_hold", "policy", "handoff_creates_booking", "human_review_and_consent_required", "statement_descriptor" ] }, "description": { "type": "string" }, "facts": { "type": "object", "properties": { "duration": { "type": "string" }, "privacy": { "type": "string" }, "pickup": { "type": "string" } }, "required": [ "duration", "privacy", "pickup" ] }, "cruise": { "type": "object", "properties": { "meeting": { "type": "string" }, "return_plan": { "type": "string" }, "skipped_port": { "type": "string" }, "ship_details": { "type": "string" }, "time_basis": { "type": "string" }, "return_guarantee": { "type": "boolean" }, "details_url": { "type": "string" } }, "required": [ "meeting", "return_plan", "skipped_port", "ship_details", "time_basis", "return_guarantee", "details_url" ] }, "contact": { "type": "object", "properties": { "phone": { "type": "string" }, "phone_display": { "type": "string" }, "phone_hours": { "type": "string" }, "timezone": { "type": "string" }, "form_url": { "type": "string" }, "question_endpoint": { "type": "string" }, "tool": { "type": "string" }, "permission_required": { "type": "boolean" }, "creates_booking": { "type": "boolean" }, "reply_channel": { "type": "string" } }, "required": [ "phone", "phone_display", "phone_hours", "timezone", "form_url", "question_endpoint", "tool", "permission_required", "creates_booking", "reply_channel" ] }, "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } }, "required": [ "air_conditioned", "api_version", "booking", "brand", "contact", "cruise", "currency", "description", "duration_hours", "facts", "facts_updated", "itinerary", "links", "local_driver_guide_included", "name", "operator", "passengers", "pickup", "pricing", "private", "schedule", "service_id", "shared_with_other_groups", "source", "timezone", "vehicle" ] }, "Discovery": { "type": "object", "properties": { "api_version": { "type": "string" }, "service_id": { "const": "private-van-tour" }, "facts_updated": { "type": "string", "format": "date" }, "source": { "type": "string", "format": "uri" }, "operator": { "type": "string" }, "currency": { "const": "USD" }, "timezone": { "const": "America/Aruba" }, "name": { "type": "string" }, "authentication": { "type": "string" }, "booking_created": { "const": false }, "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } }, "required": [ "api_version", "service_id", "facts_updated", "source", "operator", "currency", "timezone", "name", "authentication", "booking_created", "links" ] }, "Question": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-4[a-fA-F0-9]{3}-[89aAbB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$", "description": "Fresh random UUID v4 for each new question. Reuse unchanged on retries for seven days; never retry an uncertain send with a new ID." }, "name": { "type": "string", "maxLength": 80, "default": "" }, "reply_email": { "type": "string", "format": "email", "maxLength": 254, "description": "The customer’s email, shared with their permission, for the team to reply." }, "question": { "type": "string", "minLength": 5, "maxLength": 3000, "description": "Plain-text tour question only. No card/account numbers, secrets, HTML, attachments or promotional links." }, "customer_authorized": { "type": "boolean", "const": true, "description": "True only after the customer has authorized sending this question and sharing their reply email. This is consent to an inquiry, never a booking or charge." } }, "required": [ "request_id", "reply_email", "question", "customer_authorized" ], "additionalProperties": false }, "QuestionResult": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "message": { "type": "string" }, "booking_created": { "const": false }, "reference": { "type": "string" }, "retry_after_seconds": { "type": "integer" }, "phone": { "type": "string" }, "contact_url": { "type": "string", "format": "uri" } }, "required": [ "ok", "status", "message", "booking_created" ], "additionalProperties": false }, "AssessmentInput": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 40, "description": "Total passengers aged 13 or older. Maximum 10 per van; provide vans for multiple vans." }, "children": { "type": "integer", "minimum": 0, "maximum": 36, "description": "Passengers aged 0–12; free on the tour but counted toward capacity." }, "vans": { "type": "array", "minItems": 1, "maxItems": 4, "description": "Optional per-van passenger allocation. Counts must add up to adults and children; each van requires 1–10 guests including at least one adult. Each van is priced and rounded down separately, then totals are added. All vans share date, start time and duration. Omit for one van.", "items": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 10 }, "children": { "type": "integer", "minimum": 0, "maximum": 9 } }, "required": [ "adults", "children" ], "additionalProperties": false } }, "duration_hours": { "type": "integer", "minimum": 4, "maximum": 8 }, "stop_ids": { "type": "array", "items": { "type": "string", "enum": [ "tres-trapi", "bushiribana", "natural-bridge", "ayo", "casibari", "california-lighthouse", "seroe-colorado", "mangel-halto", "arikok", "eagle-beach", "hooiberg", "malmok", "palm-beach", "donkey-sanctuary", "oranjestad", "arashi", "red-anchor", "san-nicolas", "rodgers", "boca-catalina", "baby-beach", "alto-vista", "philips-garden", "butterfly-farm", "ostrich-farm" ] }, "maxItems": 25, "uniqueItems": true, "default": [], "description": "Optional wish list, not a guaranteed driving route. Empty means decide with the guide." }, "tour_date": { "type": "string", "format": "date", "description": "Optional. Must be supplied together with pickup_time, at least 24 hours ahead in America/Aruba." }, "pickup_time": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):(?:00|15|30|45)$", "description": "Aruba local time, HH:mm. Afternoon starts are supported; this does not check attraction opening hours." } }, "required": [ "adults", "children", "duration_hours" ], "additionalProperties": false, "dependentRequired": { "tour_date": [ "pickup_time" ], "pickup_time": [ "tour_date" ] } }, "requirements": { "type": "object", "properties": { "private": { "type": "boolean" }, "air_conditioned": { "type": "boolean" }, "hotel_or_villa_pickup": { "type": "boolean" }, "swimming": { "type": "boolean" }, "remain_in_wheelchair": { "type": "boolean" }, "child_seats": { "type": "boolean" }, "budget_includes_admissions": { "type": "boolean" }, "start_period": { "enum": [ "morning", "afternoon", "evening" ] }, "walking": { "enum": [ "unrestricted", "limited", "no_stairs" ] }, "required_stop_ids": { "type": "array", "items": { "type": "string", "enum": [ "tres-trapi", "bushiribana", "natural-bridge", "ayo", "casibari", "california-lighthouse", "seroe-colorado", "mangel-halto", "arikok", "eagle-beach", "hooiberg", "malmok", "palm-beach", "donkey-sanctuary", "oranjestad", "arashi", "red-anchor", "san-nicolas", "rodgers", "boca-catalina", "baby-beach", "alto-vista", "philips-garden", "butterfly-farm", "ostrich-farm" ] }, "maxItems": 25, "uniqueItems": true, "default": [], "description": "Optional wish list, not a guaranteed driving route. Empty means decide with the guide." }, "budget_total_usd": { "type": "integer", "minimum": 0, "description": "Whole USD for all vans together, not per person." }, "other": { "type": "array", "maxItems": 10, "items": { "type": "string", "minLength": 2, "maxLength": 300 }, "description": "Unmodeled needs. Always returned for team confirmation; never treated as automatically understood or fulfilled." } }, "required": [], "additionalProperties": false } }, "required": [ "plan", "requirements" ], "additionalProperties": false }, "Assessment": { "type": "object", "required": [ "assessment_status", "checks", "quote", "warnings", "inventory_checked", "route_feasibility_checked", "booking_created", "limitations" ], "properties": { "assessment_status": { "enum": [ "requirements_not_met", "review_needed", "product_fit" ] }, "checks": { "type": "array", "items": { "type": "object", "properties": { "requirement": { "type": "string" }, "status": { "enum": [ "supported", "supported_with_conditions", "not_met", "not_supported", "needs_clarification", "needs_team_confirmation" ] }, "detail": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "requirement", "status", "detail", "sources" ], "additionalProperties": false } }, "quote": { "$ref": "#/components/schemas/Quote" }, "warnings": { "type": "array", "items": { "type": "string" } }, "inventory_checked": { "const": false }, "route_feasibility_checked": { "const": false }, "booking_created": { "const": false }, "limitations": { "type": "string" }, "next_step": { "type": "string" } } }, "AgentDraft": { "type": "object", "properties": { "request_key": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Generate 32 cryptographically random bytes as 64 lowercase hex characters. Keep this private request_key and all input unchanged on retries. Never derive it from customer data." }, "plan": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 40, "description": "Total passengers aged 13 or older. Maximum 10 per van; provide vans for multiple vans." }, "children": { "type": "integer", "minimum": 0, "maximum": 36, "description": "Passengers aged 0–12; free on the tour but counted toward capacity." }, "vans": { "type": "array", "minItems": 1, "maxItems": 4, "description": "Optional per-van passenger allocation. Counts must add up to adults and children; each van requires 1–10 guests including at least one adult. Each van is priced and rounded down separately, then totals are added. All vans share date, start time and duration. Omit for one van.", "items": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 10 }, "children": { "type": "integer", "minimum": 0, "maximum": 9 } }, "required": [ "adults", "children" ], "additionalProperties": false } }, "duration_hours": { "type": "integer", "minimum": 4, "maximum": 8 }, "stop_ids": { "type": "array", "items": { "type": "string", "enum": [ "tres-trapi", "bushiribana", "natural-bridge", "ayo", "casibari", "california-lighthouse", "seroe-colorado", "mangel-halto", "arikok", "eagle-beach", "hooiberg", "malmok", "palm-beach", "donkey-sanctuary", "oranjestad", "arashi", "red-anchor", "san-nicolas", "rodgers", "boca-catalina", "baby-beach", "alto-vista", "philips-garden", "butterfly-farm", "ostrich-farm" ] }, "maxItems": 25, "uniqueItems": true, "default": [], "description": "Optional wish list, not a guaranteed driving route. Empty means decide with the guide." }, "tour_date": { "type": "string", "format": "date", "description": "Optional. Must be supplied together with pickup_time, at least 24 hours ahead in America/Aruba." }, "pickup_time": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):(?:00|15|30|45)$", "description": "Aruba local time, HH:mm. Afternoon starts are supported; this does not check attraction opening hours." } }, "required": [ "adults", "children", "duration_hours" ], "additionalProperties": false, "dependentRequired": { "tour_date": [ "pickup_time" ], "pickup_time": [ "tour_date" ] } }, "guest": { "type": "object", "properties": { "first_name": { "type": "string", "maxLength": 80 }, "last_name": { "type": "string", "maxLength": 80 }, "email": { "type": "string", "maxLength": 254 }, "phone": { "type": "string", "maxLength": 80 }, "pickup_address": { "type": "string", "maxLength": 500 }, "dropoff_address": { "type": "string", "maxLength": 500 }, "special_requests": { "type": "string", "maxLength": 2000 } }, "required": [], "additionalProperties": false }, "customer_authorized": { "const": true, "type": "boolean" } }, "required": [ "request_key", "plan", "customer_authorized" ], "additionalProperties": false }, "AgentAccess": { "type": "object", "properties": { "request_key": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Generate 32 cryptographically random bytes as 64 lowercase hex characters. Keep this private request_key and all input unchanged on retries. Never derive it from customer data." }, "booking_reference": { "type": "string", "minLength": 5, "maxLength": 40 }, "assistant_name": { "type": "string", "maxLength": 80 } }, "required": [ "request_key", "booking_reference" ], "additionalProperties": false }, "AgentCredential": { "type": "object", "properties": { "operation_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "operation_token": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Private scoped capability. Do not publish, log, put in query parameters or share with anyone other than the authorized caller." } }, "required": [ "operation_id", "operation_token" ], "additionalProperties": false }, "AgentRequestPreview": { "type": "object", "properties": { "operation_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "operation_token": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Private scoped capability. Do not publish, log, put in query parameters or share with anyone other than the authorized caller." }, "request_id": { "type": "string", "format": "uuid", "description": "New random UUID v4 for this change request; preserve on retries." }, "change": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "pickup" }, "pickup_address": { "type": "string", "minLength": 1, "maxLength": 500 }, "note": { "type": "string", "maxLength": 1000 } }, "required": [ "kind", "pickup_address" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "schedule" }, "tour_date": { "type": "string", "format": "date" }, "pickup_time": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):(?:00|15|30|45)$", "description": "Aruba local time, HH:mm. Afternoon starts are supported; this does not check attraction opening hours." }, "note": { "type": "string", "maxLength": 1000 } }, "required": [ "kind", "tour_date", "pickup_time" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "cancel" }, "note": { "type": "string", "maxLength": 1000 } }, "required": [ "kind" ], "additionalProperties": false } ] } }, "required": [ "operation_id", "operation_token", "request_id", "change" ], "additionalProperties": false }, "AgentRequestSubmit": { "type": "object", "properties": { "operation_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "operation_token": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Private scoped capability. Do not publish, log, put in query parameters or share with anyone other than the authorized caller." }, "proposal_token": { "type": "string", "maxLength": 12000 }, "customer_authorized": { "type": "boolean", "const": true } }, "required": [ "operation_id", "operation_token", "proposal_token", "customer_authorized" ], "additionalProperties": false } } } }