{ "openapi": "3.1.0", "info": { "title": "Via Turquia Partner API", "version": "1.0.0", "summary": "Manage your tours, prices and bookings with Via Turquia, and receive booking events.", "description": "The partner API for tour operators and travel agencies working with Via Turquia (v1).\n\nAuthentication: send `Authorization: Bearer vtp_live__`. Keys are created in the partner panel once Via Turquia has switched API access on for your account.\n\nEvery timestamp is ISO 8601 on the Istanbul clock (+03:00); every amount is EUR. Rate limits: 120 requests a minute and 10000 a day per key.\n\nFull documentation, including webhook signature verification: https://www.viaturquia.com/en/partners/api-docs", "contact": { "name": "Via Turquia", "email": "info@viaturquia.com" } }, "servers": [ { "url": "https://www.viaturquia.com/api/partner/v1", "description": "Via Turquia" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Service and account" }, { "name": "Tours" }, { "name": "Pricing" }, { "name": "Images" }, { "name": "Bookings" }, { "name": "Webhook" } ], "paths": { "/ping": { "get": { "operationId": "ping", "tags": [ "Service and account" ], "summary": "Is the service up, and does my Authorization header survive the trip?", "description": "The one endpoint that needs no key. authorization_header_seen is false when something between you and us removed the header - from our side that looks exactly like a wrong key, so check this first when every call answers 401.\n\nAnswers 503 service_disabled while the API is switched off.", "security": [], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ping" }, "example": { "ok": true, "version": "v1", "time": "2026-10-22T10:15:00+03:00", "authorization_header_seen": true } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/me": { "get": { "operationId": "getMe", "tags": [ "Service and account" ], "summary": "Your partner profile, the key you are using, and your rate limit.", "description": "commission_pct is read only. rate_limit.remaining counts what is left after this request in the tighter of the two windows.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "account:read" ], "x-required-scopes-note": "This scope is required.", "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" }, "example": { "partner": { "partner_id": 42, "slug": "anatolia-trails", "company_name": "Anatolia Trails", "contact_name": "Elif Demir", "email": "elif@anatolia-trails.example", "phone": "+905321234567", "country": "Turkey", "license_number": "TURSAB-1234", "type": "agency", "website": "https://anatolia-trails.example", "languages_spoken": [ "English", "Spanish" ], "description": "Day tours and short breaks in Istanbul and Cappadocia.", "logo_url": null, "status": "approved", "api_enabled": true, "notify_email": true, "commission_pct": 15, "bank_account_holder": "Anatolia Trails Ltd", "bank_name": "Example Bank", "bank_iban": "TR330006100519786457841326", "bank_swift": "EXAMPTRIS", "tax_id": "1234567890", "approved_at": "2026-09-30T12:00:00+03:00", "created_at": "2026-09-28T09:41:00+03:00" }, "key": { "key_id": "9f2c41d07ab35e18", "label": "Production sync", "scopes": [ "tours:read", "tours:write", "bookings:read", "bookings:write", "webhooks:write" ], "expires_at": null, "last_used_at": "2026-10-22T10:14:58+03:00", "created_at": "2026-10-20T16:02:11+03:00" }, "rate_limit": { "per_minute": 120, "per_day": 10000, "remaining": 118, "reset_at": "2026-10-22T10:16:00+03:00" } } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchMe", "tags": [ "Service and account" ], "summary": "Change your profile.", "description": "Editable: company_name, contact_name, phone (international form), country, website (http/https), description (simple formatting survives), languages_spoken (a list, at most 20), bank_account_holder, bank_name, bank_iban, bank_swift, tax_id.\n\nYour email, status, commission and everything else are not editable. They are not an error either: they come back in ignored[], so you can send back what GET /me gave you.\n\nA request with any invalid field changes nothing at all.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "account:write" ], "x-required-scopes-note": "This scope is required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeWrite" }, "example": { "phone": "+905321234567", "website": "https://anatolia-trails.example", "languages_spoken": [ "English", "Spanish" ] } } } }, "responses": { "200": { "description": "ok - what GET /me answers, plus ignored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeUpdated" }, "example": { "partner": { "partner_id": 42, "slug": "anatolia-trails", "company_name": "Anatolia Trails", "contact_name": "Elif Demir", "email": "elif@anatolia-trails.example", "phone": "+905321234567", "country": "Turkey", "license_number": "TURSAB-1234", "type": "agency", "website": "https://anatolia-trails.example", "languages_spoken": [ "English", "Spanish" ], "description": "Day tours and short breaks in Istanbul and Cappadocia.", "logo_url": null, "status": "approved", "api_enabled": true, "notify_email": true, "commission_pct": 15, "bank_account_holder": "Anatolia Trails Ltd", "bank_name": "Example Bank", "bank_iban": "TR330006100519786457841326", "bank_swift": "EXAMPTRIS", "tax_id": "1234567890", "approved_at": "2026-09-30T12:00:00+03:00", "created_at": "2026-09-28T09:41:00+03:00" }, "key": { "key_id": "9f2c41d07ab35e18", "label": "Production sync", "scopes": [ "tours:read", "tours:write", "bookings:read", "bookings:write", "webhooks:write" ], "expires_at": null, "last_used_at": "2026-10-22T10:14:58+03:00", "created_at": "2026-10-20T16:02:11+03:00" }, "rate_limit": { "per_minute": 120, "per_day": 10000, "remaining": 118, "reset_at": "2026-10-22T10:16:00+03:00" }, "ignored": [] } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_phone, invalid_url, company_name_required, no_updatable_fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reference": { "get": { "operationId": "getReference", "tags": [ "Service and account" ], "summary": "Every fixed value you need to build a tour: languages, categories, destinations, seasons, hotel classes, room types.", "description": "The ids you send in taxonomy and the season_id of a price cell come from here. Lists are shortened in the example.\n\nseasons[].date_ranges are MM-DD pairs and never cross the new year.\n\nReadable with either scope, so a catalogue-only key can resolve ids.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tours:read", "account:read" ], "x-required-scopes-note": "Any one of these scopes is enough.", "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reference" }, "example": { "languages": [ { "code": "en", "name": "English" }, { "code": "es", "name": "Español" } ], "categories": [ { "category_id": 3, "parent_id": null, "slug": "city-tours", "names": { "en": "City tours", "es": "Tours urbanos", "pt": "Passeios urbanos", "ar": null } } ], "destinations": [ { "destination_id": 1, "slug": "istanbul", "names": { "en": "Istanbul", "es": "Estambul", "pt": "Istambul", "ar": "إسطنبول" } } ], "experience_types": [ { "experience_type_id": 2, "slug": "cultural", "names": { "en": "Cultural", "es": "Cultural", "pt": "Cultural", "ar": null } } ], "seasons": [ { "season_id": 1, "name_key": "highest", "names": { "en": "Highest season", "es": "Temporada más alta", "pt": null, "ar": null }, "date_ranges": [ { "start": "08-01", "end": "10-31" } ] } ], "hotel_categories": [ { "code": "A", "names": { "en": "5 stars", "es": "5 estrellas", "pt": null, "ar": null }, "descriptions": { "en": "Luxury hotels", "es": null, "pt": null, "ar": null } } ], "room_types": [ { "code": "double", "capacity": 2, "names": { "en": "Double", "es": "Doble", "pt": "Duplo", "ar": null } }, { "code": "triple", "capacity": 3, "names": { "en": "Triple", "es": "Triple", "pt": "Triplo", "ar": null } }, { "code": "individual", "capacity": 1, "names": { "en": "Single", "es": "Individual", "pt": "Individual", "ar": null } } ], "difficulty_levels": [ { "code": "easy", "labels": { "en": "Easy", "es": "Fácil", "pt": "Fácil", "ar": "سهل" } } ], "group_types": [ { "code": "small_group", "labels": { "en": "Small group", "es": "Grupo pequeño", "pt": "Grupo pequeno", "ar": "مجموعة صغيرة" } } ], "age_ranges": [ { "code": "all_ages", "labels": { "en": "All ages", "es": "Todas las edades", "pt": "Todas as idades", "ar": "جميع الأعمار" } } ], "document_types": [ "license", "id", "contract", "insurance", "other" ], "guide_languages": [ "en", "es", "pt", "ar", "fr", "de", "it", "ru", "tr", "ja", "zh", "ko" ] } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/requests": { "get": { "operationId": "getRequests", "tags": [ "Service and account" ], "summary": "Your own recent API calls (the audit trail).", "description": "Newest first. Request bodies are never stored. The request that asks is not in the list: it is logged as it is answered. Entries are kept for 30 days.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "account:read" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, from 1.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page. Default 50, at most 100.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestList" }, "example": { "data": [ { "request_id": "req_8f21c0a4e3", "key_id": "9f2c41d07ab35e18", "method": "GET", "path": "/api/partner/v1/tours?page=1", "status": 200, "duration_ms": 31, "ip": "203.0.113.7", "idempotency_key": null, "created_at": "2026-10-22T10:14:58+03:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "has_more": false } } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tours": { "get": { "operationId": "listTours", "tags": [ "Tours" ], "summary": "Your tours, one summary row each.", "description": "Ordered by tour_id. Every language version of a tour is its own row with its own tour_id; group_id ties them together.\n\npagination.as_of is our clock, taken before the read. Store it and send it back as updated_since next time instead of your own clock: it cannot drift, and a row written while you read is caught by the next poll. updated_since is inclusive (>=), so the row at the boundary comes again - de-duplicate on tour_id.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tours:read" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, from 1.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page. Default 50, at most 100.", "schema": { "type": "integer" } }, { "name": "language", "in": "query", "required": false, "description": "en, es, pt or ar.", "schema": { "type": "string" } }, { "name": "active", "in": "query", "required": false, "description": "1 (published) or 0 (waiting for review).", "schema": { "type": "string" } }, { "name": "group_id", "in": "query", "required": false, "description": "Only the language versions of one tour.", "schema": { "type": "integer" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601 date or time, e.g. 2026-10-22T10:15:00+03:00. Only rows changed at or after it. Pass the previous list's pagination.as_of here. In a URL encode + as %2B.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Matches the title or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourList" }, "example": { "data": [ { "tour_id": 1207, "group_id": 1207, "language": "es", "slug": "estambul-clasico", "title": "Estambul Clásico", "status": "awaiting_review", "is_active": false, "price": 85, "duration_days": 1, "duration_nights": 0, "hotel_included": false, "pricing_mode": "flat", "main_image": "https://www.viaturquia.com/uploads/tours/3f9c1e0a7b52d4c8.jpg", "created_at": "2026-10-22T09:58:12+03:00", "updated_at": "2026-10-22T10:02:40+03:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "has_more": false, "as_of": "2026-10-22T10:15:00+03:00" } } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "one error listing every bad filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createTour", "tags": [ "Tours" ], "summary": "Create a tour (one language).", "description": "Answers 201 with the same object GET /tours/{id} gives, plus ignored[]. The tour is born unpublished: status is awaiting_review until Via Turquia approves it. You cannot publish it yourself.\n\nlanguage is en, es, pt or ar and defaults to es when you leave it out. To add the same tour in another language use POST /tours/{id}/translations - group_id cannot be set here.\n\ntitle is the only required field. Everything is described field by field in section 5.\n\nSend an Idempotency-Key so a retry after a timeout cannot create the tour twice.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tours:write" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1-80 printable ASCII characters. A second request with the same key and body within 24 hours replays the first answer (Idempotency-Replayed: true).", "schema": { "type": "string", "maxLength": 80 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourWrite" }, "example": { "language": "es", "title": "Estambul Clásico", "short_description": "Un día completo entre Santa Sofía, la Mezquita Azul y el Bósforo.", "description": "

Descubre el corazón histórico de Estambul con un guía local.

", "highlights": [ "Santa Sofía", "Mezquita Azul" ], "starting_time": "09:00", "meeting_point": "Vestíbulo de su hotel en Sultanahmet", "duration": { "days": 1, "details": "8 horas" }, "group": { "type": "small_group", "max_size": 16, "min_participants": 2 }, "difficulty_level": "easy", "includes": { "hotel": false, "guide": true, "meals": true, "transfers": true, "tickets": true }, "inclusions": [ "Guía en español", "Entradas" ], "itinerary": [ { "time": "09:00", "title": "Recogida en el hotel", "description": "

Salida desde Sultanahmet.

" } ], "supplements": [ { "name": "Cena en el Bósforo", "price": 25, "per_person": true } ], "pricing": { "price": 85, "original_price": 110, "child_discount_pct": 30, "infant_discount_pct": 100 }, "cancellation": { "policy": "

Cancelación gratuita hasta 48 horas antes.

", "free_hours": 48 }, "taxonomy": { "category_id": 3, "destinations": [ 1 ], "experience_types": [ 2 ], "guide_languages": [ "es", "en" ] }, "reference_url": "https://anatolia-trails.example/tour/123" } } } }, "responses": { "201": { "description": "created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourWritten" }, "example": { "tour_id": 1207, "group_id": 1207, "language": "es", "slug": "estambul-clasico", "status": "awaiting_review", "is_active": false, "title": "Estambul Clásico", "short_description": "Un día completo entre Santa Sofía, la Mezquita Azul y el Bósforo.", "description": "

Descubre el corazón histórico de Estambul con un guía local.

", "highlights": [ "Santa Sofía", "Mezquita Azul", "Crucero por el Bósforo" ], "important_info": "Lleve calzado cómodo y hombros cubiertos para las mezquitas.", "meeting_point": "Vestíbulo de su hotel en Sultanahmet", "ending_point": "Gran Bazar", "starting_time": "09:00", "duration": { "days": 1, "nights": 0, "details": "8 horas" }, "group": { "type": "Grupo pequeño", "max_size": 16, "min_participants": 2, "max_participants": 16 }, "age": { "min_age": 6, "range": "Todas las edades", "child_label": "6-11", "infant_label": "0-5" }, "difficulty_level": "easy", "difficulty_label": "Fácil", "includes": { "hotel": false, "guide": true, "meals": true, "transfers": true, "tickets": true }, "inclusions": [ "Guía en español", "Entradas", "Almuerzo" ], "exclusions": [ "Bebidas", "Propinas" ], "itinerary": [ { "time": "09:00", "title": "Recogida en el hotel", "description": "

Salida desde Sultanahmet.

" }, { "time": "09:30", "title": "Santa Sofía", "description": "

Visita guiada de una hora.

" } ], "faqs": [ { "question": "¿Hay que reservar con antelación?", "answer": "Sí, con 24 horas." } ], "supplements": [ { "name": "Cena en el Bósforo", "description": null, "price": 25, "per_person": true, "active": true } ], "pricing": { "mode": "flat", "hotel_included": false, "matrix_cells": 0, "matrix_complete": false, "price": 85, "original_price": 110, "child_discount_pct": 30, "infant_discount_pct": 100 }, "cancellation": { "policy": "

Cancelación gratuita hasta 48 horas antes.

", "free_hours": 48 }, "media": { "main_image": "https://www.viaturquia.com/uploads/tours/3f9c1e0a7b52d4c8.jpg", "gallery": [ "https://www.viaturquia.com/uploads/tours/3f9c1e0a7b52d4c8.jpg" ], "video_url": null }, "taxonomy": { "category_id": 3, "categories": [ 3 ], "destinations": [ 1 ], "experience_types": [ 2 ], "guide_languages": [ "es", "en" ] }, "reference_url": "https://anatolia-trails.example/tour/123", "created_at": "2026-10-22T09:58:12+03:00", "updated_at": "2026-10-22T10:02:40+03:00", "ignored": [] } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "every wrong field in error.errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tours/{id}": { "get": { "operationId": "getTour", "tags": [ "Tours" ], "summary": "One tour in full.", "description": "The object is also the shape POST and PATCH accept: fetch it, change a value, send it back. Fields we compute or that are yours to read only (tour_id, group_id, slug, status, is_active, created_at, updated_at, difficulty_label, pricing.mode and the other derived pricing fields) are dropped on the way in and listed in ignored[].\n\ntaxonomy.category_id is the tour's primary category, or null when none is set; taxonomy.categories is every category the tour is listed in.\n\nSomeone else's tour is a 404, exactly like one that does not exist.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tours:read" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The tour_id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tour" }, "example": { "tour_id": 1207, "group_id": 1207, "language": "es", "slug": "estambul-clasico", "status": "awaiting_review", "is_active": false, "title": "Estambul Clásico", "short_description": "Un día completo entre Santa Sofía, la Mezquita Azul y el Bósforo.", "description": "

Descubre el corazón histórico de Estambul con un guía local.

", "highlights": [ "Santa Sofía", "Mezquita Azul", "Crucero por el Bósforo" ], "important_info": "Lleve calzado cómodo y hombros cubiertos para las mezquitas.", "meeting_point": "Vestíbulo de su hotel en Sultanahmet", "ending_point": "Gran Bazar", "starting_time": "09:00", "duration": { "days": 1, "nights": 0, "details": "8 horas" }, "group": { "type": "Grupo pequeño", "max_size": 16, "min_participants": 2, "max_participants": 16 }, "age": { "min_age": 6, "range": "Todas las edades", "child_label": "6-11", "infant_label": "0-5" }, "difficulty_level": "easy", "difficulty_label": "Fácil", "includes": { "hotel": false, "guide": true, "meals": true, "transfers": true, "tickets": true }, "inclusions": [ "Guía en español", "Entradas", "Almuerzo" ], "exclusions": [ "Bebidas", "Propinas" ], "itinerary": [ { "time": "09:00", "title": "Recogida en el hotel", "description": "

Salida desde Sultanahmet.

" }, { "time": "09:30", "title": "Santa Sofía", "description": "

Visita guiada de una hora.

" } ], "faqs": [ { "question": "¿Hay que reservar con antelación?", "answer": "Sí, con 24 horas." } ], "supplements": [ { "name": "Cena en el Bósforo", "description": null, "price": 25, "per_person": true, "active": true } ], "pricing": { "mode": "flat", "hotel_included": false, "matrix_cells": 0, "matrix_complete": false, "price": 85, "original_price": 110, "child_discount_pct": 30, "infant_discount_pct": 100 }, "cancellation": { "policy": "

Cancelación gratuita hasta 48 horas antes.

", "free_hours": 48 }, "media": { "main_image": "https://www.viaturquia.com/uploads/tours/3f9c1e0a7b52d4c8.jpg", "gallery": [ "https://www.viaturquia.com/uploads/tours/3f9c1e0a7b52d4c8.jpg" ], "video_url": null }, "taxonomy": { "category_id": 3, "categories": [ 3 ], "destinations": [ 1 ], "experience_types": [ 2 ], "guide_languages": [ "es", "en" ] }, "reference_url": "https://anatolia-trails.example/tour/123", "created_at": "2026-10-22T09:58:12+03:00", "updated_at": "2026-10-22T10:02:40+03:00" } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "tour_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchTour", "tags": [ "Tours" ], "summary": "Change part of a tour. A field you leave out is not touched.", "description": "A tour that is already published stays published: your change goes live at once, without a new review. It is recorded in your audit trail.\n\nSome fields change every language version at once - see \"Which fields are shared\" in section 5.\n\nLists (inclusions, itinerary, faqs, supplements, gallery, taxonomy lists) are replaced as a whole when you send them. supplements is the sharp one: every supplement row is replaced, including the inactive ones, so leaving one out deletes it.\n\nSending only {\"pricing\":{\"price\":N}} to a tour priced by a room matrix is 422 no_updatable_fields, because on such a tour the price is derived from the matrix and pricing.price is ignored. Together with other fields it simply appears in ignored[].\n\nA request that fails validation changes nothing.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tours:write" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The tour_id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourWrite" }, "example": { "title": "Estambul Clásico en un día", "pricing": { "price": 89 } } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourWritten" }, "example": { "tour_id": 1207, "group_id": 1207, "language": "es", "slug": "estambul-clasico", "status": "awaiting_review", "is_active": false, "title": "Estambul Clásico en un día", "short_description": "Un día completo entre Santa Sofía, la Mezquita Azul y el Bósforo.", "description": "

Descubre el corazón histórico de Estambul con un guía local.

", "highlights": [ "Santa Sofía", "Mezquita Azul", "Crucero por el Bósforo" ], "important_info": "Lleve calzado cómodo y hombros cubiertos para las mezquitas.", "meeting_point": "Vestíbulo de su hotel en Sultanahmet", "ending_point": "Gran Bazar", "starting_time": "09:00", "duration": { "days": 1, "nights": 0, "details": "8 horas" }, "group": { "type": "Grupo pequeño", "max_size": 16, "min_participants": 2, "max_participants": 16 }, "age": { "min_age": 6, "range": "Todas las edades", "child_label": "6-11", "infant_label": "0-5" }, "difficulty_level": "easy", "difficulty_label": "Fácil", "includes": { "hotel": false, "guide": true, "meals": true, "transfers": true, "tickets": true }, "inclusions": [ "Guía en español", "Entradas", "Almuerzo" ], "exclusions": [ "Bebidas", "Propinas" ], "itinerary": [ { "time": "09:00", "title": "Recogida en el hotel", "description": "

Salida desde Sultanahmet.

" }, { "time": "09:30", "title": "Santa Sofía", "description": "

Visita guiada de una hora.

" } ], "faqs": [ { "question": "¿Hay que reservar con antelación?", "answer": "Sí, con 24 horas." } ], "supplements": [ { "name": "Cena en el Bósforo", "description": null, "price": 25, "per_person": true, "active": true } ], "pricing": { "mode": "flat", "hotel_included": false, "matrix_cells": 0, "matrix_complete": false, "price": 89, "original_price": 110, "child_discount_pct": 30, "infant_discount_pct": 100 }, "cancellation": { "policy": "

Cancelación gratuita hasta 48 horas antes.

", "free_hours": 48 }, "media": { "main_image": "https://www.viaturquia.com/uploads/tours/3f9c1e0a7b52d4c8.jpg", "gallery": [ "https://www.viaturquia.com/uploads/tours/3f9c1e0a7b52d4c8.jpg" ], "video_url": null }, "taxonomy": { "category_id": 3, "categories": [ 3 ], "destinations": [ 1 ], "experience_types": [ 2 ], "guide_languages": [ "es", "en" ] }, "reference_url": "https://anatolia-trails.example/tour/123", "created_at": "2026-10-22T09:58:12+03:00", "updated_at": "2026-10-22T10:30:00+03:00", "ignored": [] } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "tour_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "every wrong field in error.errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteTour", "tags": [ "Tours" ], "summary": "Delete one language version of a tour.", "description": "Deletes only the row you address, not its other languages. A tour that has any booking - even a cancelled one - answers 409 tour_has_bookings and stays; ask us to take it off the site instead.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tours:write" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The tour_id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "deleted": true, "tour_id": 1207 } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "tour_has_bookings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tours/{id}/pricing": { "get": { "operationId": "getTourPricing", "tags": [ "Pricing" ], "summary": "The 27-cell room matrix of an accommodation tour, or the single price of a day tour.", "description": "group_tour_ids lists the language versions that share these prices - the rows a write reaches.\n\nmode is matrix as soon as one cell exists. matrix_complete tells an accommodation tour whose matrix you have not finished from a day tour.\n\nThe example shows three of the 27 cells.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tours:read" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The tour_id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "a day tour; an accommodation tour", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pricing" }, "examples": { "first": { "summary": "a day tour", "value": { "tour_id": 1207, "group_id": 1207, "group_tour_ids": [ 1207 ], "mode": "flat", "hotel_included": false, "matrix_cells": 0, "matrix_complete": false, "price": 85, "original_price": 110, "child_discount_pct": 30, "infant_discount_pct": 100 } }, "second": { "summary": "an accommodation tour", "value": { "tour_id": 1301, "group_id": 1301, "group_tour_ids": [ 1301, 1302, 1303, 1304 ], "mode": "matrix", "hotel_included": true, "matrix_cells": 27, "matrix_complete": true, "price": 410, "original_price": null, "child_discount_pct": 30, "infant_discount_pct": 100, "matrix": [ { "season_id": 1, "hotel_category": "A", "room_type": "double", "price": 640 }, { "season_id": 1, "hotel_category": "A", "room_type": "triple", "price": 610 }, { "season_id": 1, "hotel_category": "A", "room_type": "individual", "price": 840 } ] } } } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putTourPricing", "tags": [ "Pricing" ], "summary": "Write the prices: the whole matrix for an accommodation tour, or one price for a day tour.", "description": "matrix: all 27 cells are required (3 seasons x hotel classes A/B/C x room types double/triple/individual), each above 0. A missing cell is 422 and the message names every one that is missing. The figures are per person, in EUR.\n\nThe prices are written to every language version of the tour (that is also an accommodation tour). tours.price - the \"from\" price on the site - is then set to the cheapest cell; you cannot set it by hand on such a tour.\n\nA matrix for a tour whose includes.hotel is false is 409 matrix_on_day_tour; a single price for a tour that includes accommodation is 409 flat_price_on_hotel_tour.\n\nAnything else in the body is dropped and listed in ignored[] - so you can send back what GET returned.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tours:write" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The tour_id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingWrite" }, "example": { "matrix": [ { "season_id": 1, "hotel_category": "A", "room_type": "double", "price": 640 }, { "season_id": 1, "hotel_category": "A", "room_type": "triple", "price": 610 }, { "season_id": 1, "hotel_category": "A", "room_type": "individual", "price": 840 } ] } } } }, "responses": { "200": { "description": "ok - what GET answers, plus ignored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingWritten" }, "example": { "tour_id": 1301, "group_id": 1301, "group_tour_ids": [ 1301, 1302, 1303, 1304 ], "mode": "matrix", "hotel_included": true, "matrix_cells": 27, "matrix_complete": true, "price": 410, "original_price": null, "child_discount_pct": 30, "infant_discount_pct": 100, "matrix": [ { "season_id": 1, "hotel_category": "A", "room_type": "double", "price": 640 }, { "season_id": 1, "hotel_category": "A", "room_type": "triple", "price": 610 }, { "season_id": 1, "hotel_category": "A", "room_type": "individual", "price": 840 } ], "ignored": [] } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "matrix_on_day_tour, flat_price_on_hotel_tour", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "matrix_cell_missing, invalid_matrix_cell, duplicate_matrix_cell, invalid_matrix_price, invalid_price", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tours/{id}/images": { "post": { "operationId": "addTourImage", "tags": [ "Images" ], "summary": "Add an image to a tour's gallery - upload a file, or give us an address to fetch.", "description": "Either multipart/form-data with the file in a part named \"file\" (or \"image\"), or JSON {\"url\": \"https://...\"} and our server downloads it.\n\nAccepted: JPEG, PNG, GIF, WebP. HEIC/HEIF photos (iPhones) are refused with heic_not_supported. Uploads up to 12 MB; downloads up to 5 MB; at most 50 megapixels. We apply the EXIF rotation and scale the longest edge down to 1920 px.\n\nA fetched address must be https, must resolve to a public address, is not allowed to redirect, and has 10 seconds. At most 20 image POSTs a minute per key.\n\nThe image is appended to the gallery of that one language version (a gallery belongs to its row). The answer is the stored address; to make it the main image, send it as media.main_image with PATCH. A tour holds at most 40 gallery images.\n\nMedia addresses in a PATCH/POST body must already be on Via Turquia - this endpoint is how an outside image gets there.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tours:write" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The tour_id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1-80 printable ASCII characters. A second request with the same key and body within 24 hours replays the first answer (Idempotency-Replayed: true).", "schema": { "type": "string", "maxLength": 80 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageUrl" }, "example": { "url": "https://anatolia-trails.example/photos/santa-sofia.jpg" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageAdded" }, "example": { "tour_id": 1207, "url": "https://www.viaturquia.com/uploads/tours/3f9c1e0a7b52d4c8.jpg", "source": "url", "gallery_count": 2 } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "file_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "image_required, unsafe_url, fetch_failed, heic_not_supported, not_an_image, too_many_images", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteTourImage", "tags": [ "Images" ], "summary": "Take an image out of a tour's gallery.", "description": "The image leaves the gallery; the file itself is not deleted from our storage.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tours:write" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The tour_id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageUrl" }, "example": { "url": "https://www.viaturquia.com/uploads/tours/3f9c1e0a7b52d4c8.jpg" } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageRemoved" }, "example": { "deleted": true, "tour_id": 1207, "url": "https://www.viaturquia.com/uploads/tours/3f9c1e0a7b52d4c8.jpg", "gallery_count": 1 } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "image_not_in_gallery, tour_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tours/{id}/translations": { "post": { "operationId": "createTranslation", "tags": [ "Tours" ], "summary": "Open a tour in another language.", "description": "Creates a new language version in the same tour group, unpublished. It copies the structure - durations, group sizes, cancellation hours, prices and the whole matrix, the include switches, categories, destinations, experience types, guide languages, ages - and leaves every text empty. The translation is yours to write with PATCH.\n\nneeds[] lists what you still have to fill in. Supplements arrive with their price but inactive and with no name (needs shows the source name as a hint); they are not sold until you PATCH supplements with a name and \"active\": true.\n\nA language the group already has is 409 translation_exists.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tours:write" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The tour_id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1-80 printable ASCII characters. A second request with the same key and body within 24 hours replays the first answer (Idempotency-Replayed: true).", "schema": { "type": "string", "maxLength": 80 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationCreate" }, "example": { "language": "en" } } } }, "responses": { "201": { "description": "created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationCreated" }, "example": { "tour_id": 1208, "group_id": 1207, "language": "en", "slug": "estambul-clasico-en", "status": "awaiting_review", "is_active": false, "title": "", "short_description": null, "description": null, "highlights": [], "important_info": null, "meeting_point": null, "ending_point": null, "starting_time": null, "duration": { "days": 1, "nights": 0, "details": null }, "group": { "type": null, "max_size": 16, "min_participants": 2, "max_participants": 16 }, "age": { "min_age": 6, "range": null, "child_label": "6-11", "infant_label": "0-5" }, "difficulty_level": null, "difficulty_label": null, "includes": { "hotel": false, "guide": true, "meals": true, "transfers": true, "tickets": true }, "inclusions": [], "exclusions": [], "itinerary": [], "faqs": [], "supplements": [ { "name": "", "description": null, "price": 25, "per_person": true, "active": false } ], "pricing": { "mode": "flat", "hotel_included": false, "matrix_cells": 0, "matrix_complete": false, "price": 85, "original_price": 110, "child_discount_pct": 30, "infant_discount_pct": 100 }, "cancellation": { "policy": null, "free_hours": 48 }, "media": { "main_image": null, "gallery": [], "video_url": null }, "taxonomy": { "category_id": 3, "categories": [ 3 ], "destinations": [ 1 ], "experience_types": [ 2 ], "guide_languages": [ "es", "en" ] }, "reference_url": "https://anatolia-trails.example/tour/123", "created_at": "2026-10-22T09:58:12+03:00", "updated_at": "2026-10-22T10:02:40+03:00", "ignored": [], "needs": [ "title", "short_description", "description", "highlights", "important_info", "itinerary", "inclusions", "exclusions", "meeting_point", "ending_point", "cancellation.policy", "faqs", "media.main_image", "media.gallery", "supplements[0].name (source: Cena en el Bósforo)" ] } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "translation_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_language", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bookings": { "get": { "operationId": "listBookings", "tags": [ "Bookings" ], "summary": "Bookings made on your tours, newest first.", "description": "Customers book on the Via Turquia site (or through its chat assistant); you cannot create a booking through the API.\n\npagination.as_of works as it does for tours.\n\nThe customer's name, email and phone are in the booking: the same details your new-booking email already carries, so you can run the tour.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "bookings:read" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, from 1.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page. Default 50, at most 100.", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "pending, confirmed, cancelled or completed.", "schema": { "type": "string" } }, { "name": "tour_id", "in": "query", "required": false, "description": "One tour row.", "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "required": false, "description": "Travel date from, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "description": "Travel date to, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601 date or time, e.g. 2026-10-22T10:15:00+03:00. Only rows changed at or after it. Pass the previous list's pagination.as_of here. In a URL encode + as %2B.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingList" }, "example": { "data": [ { "booking_ref": "VT2026K7M2QX", "booking_id": 8841, "status": "pending", "source": "web", "tour": { "tour_id": 1301, "group_id": 1301, "language": "en", "title": "Cappadocia 3 Days", "slug": "cappadocia-3-days" }, "booking_date": "2026-11-14", "travellers": { "adults": 2, "children": 0, "infants": 0, "total": 2 }, "rooms": [ { "room_type_id": 1, "room_type": "double", "room_type_name": "Double", "capacity": 2, "hotel_category_id": 2, "hotel_category": "B", "hotel_category_name": "4 stars", "season_id": 1, "season": "highest", "season_name": "Highest season", "occupancy": 2, "travellers": { "adults": 2, "children": 0, "infants": 0 }, "price_per_person": 520, "room_subtotal": 1040 } ], "room_summary": { "season_id": 1, "season_name": "Highest season", "hotel_category_id": 2, "hotel_category_name": "4 stars", "room_type_id": 1, "room_type_name": "Double" }, "supplements": { "info": "Hot-air balloon x2", "total": 300 }, "special_requests": "Vegetarian meals, please.", "hotel": { "name": "Cave Hotel Goreme", "address": "Goreme, Nevsehir" }, "pickup_time": "08:30:00", "customer": { "name": "Ana García", "email": "ana@example.com", "phone": "+34600111222", "country": "Spain" }, "amounts": { "currency": "EUR", "price_per_person": 520, "discount": 0, "promo_code": null, "total": 1340, "commission_pct": 15, "commission": 201, "net": 1139, "currency_shown": "EUR" }, "payment": { "deposit_status": "pending", "deposit_amount": 268, "deposit_paid_at": null, "deposit_method": null, "payment_status": "pending" }, "partner_answer": { "action": "none", "at": null, "note": null }, "created_at": "2026-10-22T09:12:30+03:00", "updated_at": "2026-10-22T09:12:30+03:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "has_more": false, "as_of": "2026-10-22T10:15:00+03:00" } } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bookings/{ref}": { "get": { "operationId": "getBooking", "tags": [ "Bookings" ], "summary": "One booking, by its reference (VT2026...).", "description": "rooms[] is one entry per room, with the room type, hotel class, season and who sleeps in it; room_summary is the single-room summary kept on the booking row.\n\namounts are EUR. commission and net are zero for a cancelled booking. currency_shown is only what the customer saw on the page.\n\npayment tells you whether the deposit has arrived. partner_answer is what you answered (none until you do) and stays even if Via Turquia later changes the status.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "bookings:read" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The booking reference, e.g. VT2026K7M2QX.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" }, "example": { "booking_ref": "VT2026K7M2QX", "booking_id": 8841, "status": "pending", "source": "web", "tour": { "tour_id": 1301, "group_id": 1301, "language": "en", "title": "Cappadocia 3 Days", "slug": "cappadocia-3-days" }, "booking_date": "2026-11-14", "travellers": { "adults": 2, "children": 0, "infants": 0, "total": 2 }, "rooms": [ { "room_type_id": 1, "room_type": "double", "room_type_name": "Double", "capacity": 2, "hotel_category_id": 2, "hotel_category": "B", "hotel_category_name": "4 stars", "season_id": 1, "season": "highest", "season_name": "Highest season", "occupancy": 2, "travellers": { "adults": 2, "children": 0, "infants": 0 }, "price_per_person": 520, "room_subtotal": 1040 } ], "room_summary": { "season_id": 1, "season_name": "Highest season", "hotel_category_id": 2, "hotel_category_name": "4 stars", "room_type_id": 1, "room_type_name": "Double" }, "supplements": { "info": "Hot-air balloon x2", "total": 300 }, "special_requests": "Vegetarian meals, please.", "hotel": { "name": "Cave Hotel Goreme", "address": "Goreme, Nevsehir" }, "pickup_time": "08:30:00", "customer": { "name": "Ana García", "email": "ana@example.com", "phone": "+34600111222", "country": "Spain" }, "amounts": { "currency": "EUR", "price_per_person": 520, "discount": 0, "promo_code": null, "total": 1340, "commission_pct": 15, "commission": 201, "net": 1139, "currency_shown": "EUR" }, "payment": { "deposit_status": "pending", "deposit_amount": 268, "deposit_paid_at": null, "deposit_method": null, "payment_status": "pending" }, "partner_answer": { "action": "none", "at": null, "note": null }, "created_at": "2026-10-22T09:12:30+03:00", "updated_at": "2026-10-22T09:12:30+03:00" } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "booking_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bookings/{ref}/accept": { "post": { "operationId": "acceptBooking", "tags": [ "Bookings" ], "summary": "Accept a pending booking.", "description": "The booking becomes confirmed and Via Turquia may now ask the customer for the deposit. The customer is not mailed by this call.\n\nOnly a pending booking can be accepted: anything else is 409 booking_not_pending. Two simultaneous accepts are safe - one wins, the other gets the 409.\n\nnote is optional, plain text, 500 characters.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "bookings:write" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The booking reference, e.g. VT2026K7M2QX.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1-80 printable ASCII characters. A second request with the same key and body within 24 hours replays the first answer (Idempotency-Replayed: true).", "schema": { "type": "string", "maxLength": 80 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptBody" }, "example": { "note": "Rooms held." } } } }, "responses": { "200": { "description": "ok - the booking as it now stands, plus action, message and ignored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingAnswered" }, "example": { "booking_ref": "VT2026K7M2QX", "booking_id": 8841, "status": "confirmed", "source": "web", "tour": { "tour_id": 1301, "group_id": 1301, "language": "en", "title": "Cappadocia 3 Days", "slug": "cappadocia-3-days" }, "booking_date": "2026-11-14", "travellers": { "adults": 2, "children": 0, "infants": 0, "total": 2 }, "rooms": [ { "room_type_id": 1, "room_type": "double", "room_type_name": "Double", "capacity": 2, "hotel_category_id": 2, "hotel_category": "B", "hotel_category_name": "4 stars", "season_id": 1, "season": "highest", "season_name": "Highest season", "occupancy": 2, "travellers": { "adults": 2, "children": 0, "infants": 0 }, "price_per_person": 520, "room_subtotal": 1040 } ], "room_summary": { "season_id": 1, "season_name": "Highest season", "hotel_category_id": 2, "hotel_category_name": "4 stars", "room_type_id": 1, "room_type_name": "Double" }, "supplements": { "info": "Hot-air balloon x2", "total": 300 }, "special_requests": "Vegetarian meals, please.", "hotel": { "name": "Cave Hotel Goreme", "address": "Goreme, Nevsehir" }, "pickup_time": "08:30:00", "customer": { "name": "Ana García", "email": "ana@example.com", "phone": "+34600111222", "country": "Spain" }, "amounts": { "currency": "EUR", "price_per_person": 520, "discount": 0, "promo_code": null, "total": 1340, "commission_pct": 15, "commission": 201, "net": 1139, "currency_shown": "EUR" }, "payment": { "deposit_status": "pending", "deposit_amount": 268, "deposit_paid_at": null, "deposit_method": null, "payment_status": "pending" }, "partner_answer": { "action": "accepted", "at": "2026-10-22T10:20:05+03:00", "note": "Rooms held." }, "created_at": "2026-10-22T09:12:30+03:00", "updated_at": "2026-10-22T10:20:05+03:00", "action": "accepted", "message": "The booking is confirmed. Via Turquia will ask the customer for the deposit.", "ignored": [] } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "booking_not_pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bookings/{ref}/decline": { "post": { "operationId": "declineBooking", "tags": [ "Bookings" ], "summary": "Decline a pending or confirmed booking.", "description": "The booking is cancelled and the customer is emailed the cancellation automatically, in their own language. customer_notified is false when that email could not be delivered (a blocked address, a failed send) - then reach the customer another way.\n\nDeclining works only while the deposit has not been paid. Once it has, the answer is 409 deposit_already_paid and Via Turquia is told: money has changed hands, so only we can cancel and refund.\n\nreason is optional, plain text, 500 characters; it is stored with the booking.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "bookings:write" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The booking reference, e.g. VT2026K7M2QX.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1-80 printable ASCII characters. A second request with the same key and body within 24 hours replays the first answer (Idempotency-Replayed: true).", "schema": { "type": "string", "maxLength": 80 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineBody" }, "example": { "reason": "No rooms on that date." } } } }, "responses": { "200": { "description": "ok - the booking as it now stands, plus action, message, customer_notified and ignored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingAnswered" }, "example": { "booking_ref": "VT2026K7M2QX", "booking_id": 8841, "status": "cancelled", "source": "web", "tour": { "tour_id": 1301, "group_id": 1301, "language": "en", "title": "Cappadocia 3 Days", "slug": "cappadocia-3-days" }, "booking_date": "2026-11-14", "travellers": { "adults": 2, "children": 0, "infants": 0, "total": 2 }, "rooms": [ { "room_type_id": 1, "room_type": "double", "room_type_name": "Double", "capacity": 2, "hotel_category_id": 2, "hotel_category": "B", "hotel_category_name": "4 stars", "season_id": 1, "season": "highest", "season_name": "Highest season", "occupancy": 2, "travellers": { "adults": 2, "children": 0, "infants": 0 }, "price_per_person": 520, "room_subtotal": 1040 } ], "room_summary": { "season_id": 1, "season_name": "Highest season", "hotel_category_id": 2, "hotel_category_name": "4 stars", "room_type_id": 1, "room_type_name": "Double" }, "supplements": { "info": "Hot-air balloon x2", "total": 300 }, "special_requests": "Vegetarian meals, please.", "hotel": { "name": "Cave Hotel Goreme", "address": "Goreme, Nevsehir" }, "pickup_time": "08:30:00", "customer": { "name": "Ana García", "email": "ana@example.com", "phone": "+34600111222", "country": "Spain" }, "amounts": { "currency": "EUR", "price_per_person": 520, "discount": 0, "promo_code": null, "total": 1340, "commission_pct": 15, "commission": 0, "net": 0, "currency_shown": "EUR" }, "payment": { "deposit_status": "pending", "deposit_amount": 268, "deposit_paid_at": null, "deposit_method": null, "payment_status": "pending" }, "partner_answer": { "action": "declined", "at": "2026-10-22T10:20:05+03:00", "note": "No rooms on that date." }, "created_at": "2026-10-22T09:12:30+03:00", "updated_at": "2026-10-22T10:20:05+03:00", "action": "declined", "message": "The booking is cancelled and the customer has been told by email.", "customer_notified": true, "ignored": [] } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "booking_not_cancellable, deposit_already_paid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook": { "get": { "operationId": "getWebhook", "tags": [ "Webhook" ], "summary": "Your webhook registration and how delivery is going.", "description": "webhook is null until you register one. The signing secret is never shown here - only secret_set. If you lost it, rotate it.\n\ndeliveries counts every delivery you have by state. fail_streak is the number of failed attempts in a row; at 20 the webhook is switched off.\n\nA key with account:read can read the registration and the delivery log without being able to change it.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write", "account:read" ], "x-required-scopes-note": "Any one of these scopes is enough.", "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookState" }, "example": { "webhook": { "url": "https://anatolia-trails.example/hooks/viaturquia", "events": [ "booking.created", "booking.confirmed", "booking.cancelled", "booking.deposit_paid", "booking.updated", "tour.approved", "tour.unpublished" ], "is_active": true, "fail_streak": 0, "secret_set": true, "created_at": "2026-10-21T11:00:00+03:00", "updated_at": "2026-10-21T11:00:00+03:00" }, "available_events": [ "booking.created", "booking.confirmed", "booking.cancelled", "booking.deposit_paid", "booking.updated", "tour.approved", "tour.unpublished", "ping" ], "last_delivery": { "delivery_id": 311, "event_id": "evt_4be1f09a77c3d2a05c18", "event_type": "booking.created", "status": "delivered", "attempts": 1, "max_attempts": 6, "next_attempt_at": null, "last_status": 200, "last_error": null, "created_at": "2026-10-22T09:12:31+03:00", "delivered_at": "2026-10-22T09:13:02+03:00" }, "deliveries": { "pending": 0, "delivered": 14, "failed": 1 } } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putWebhook", "tags": [ "Webhook" ], "summary": "Register or change your webhook: the address, the events, on or off.", "description": "url is required, https only, no user name or password in it, and the host must resolve to a public address (never a private or local network). The address is checked again at every send.\n\nevents is a list of names from available_events. Left out on the first registration it subscribes you to every event except ping; left out later, it keeps what you have. ping is only ever sent when you ask for it with POST /webhook/test.\n\nThe first PUT creates the signing secret and is the only answer, besides rotate_secret, that carries it. Copy it now: it is not shown again.\n\nA PUT that leaves the webhook active clears the failure streak. After the automatic shut-off, this is how you say \"I have fixed my endpoint\".", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write" ], "x-required-scopes-note": "This scope is required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWrite" }, "example": { "url": "https://anatolia-trails.example/hooks/viaturquia", "events": [ "booking.created", "booking.confirmed", "booking.cancelled" ], "is_active": true } } } }, "responses": { "200": { "description": "ok - what GET /webhook answers, plus secret on the first registration and ignored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWritten" }, "example": { "webhook": { "url": "https://anatolia-trails.example/hooks/viaturquia", "events": [ "booking.created", "booking.confirmed", "booking.cancelled", "booking.deposit_paid", "booking.updated", "tour.approved", "tour.unpublished" ], "is_active": true, "fail_streak": 0, "secret_set": true, "created_at": "2026-10-21T11:00:00+03:00", "updated_at": "2026-10-21T11:00:00+03:00" }, "available_events": [ "booking.created", "booking.confirmed", "booking.cancelled", "booking.deposit_paid", "booking.updated", "tour.approved", "tour.unpublished", "ping" ], "last_delivery": { "delivery_id": 311, "event_id": "evt_4be1f09a77c3d2a05c18", "event_type": "booking.created", "status": "delivered", "attempts": 1, "max_attempts": 6, "next_attempt_at": null, "last_status": 200, "last_error": null, "created_at": "2026-10-22T09:12:31+03:00", "delivered_at": "2026-10-22T09:13:02+03:00" }, "deliveries": { "pending": 0, "delivered": 14, "failed": 1 }, "secret": "whsec_Q7mX2dT9pLk4vN8cR1sZ6bYh3WaE5uJf0GoIxA9tKeD", "ignored": [] } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "url_required, invalid_url, unsafe_url, unknown_event, invalid_events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook/rotate_secret": { "post": { "operationId": "rotateWebhookSecret", "tags": [ "Webhook" ], "summary": "Create a new signing secret.", "description": "The old secret stops working the moment this answers. Deploy the new one to your receiver first if you can, because events signed after this call use it.\n\nShown once. 404 webhook_not_configured if you have no webhook yet.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1-80 printable ASCII characters. A second request with the same key and body within 24 hours replays the first answer (Idempotency-Replayed: true).", "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWritten" }, "example": { "webhook": { "url": "https://anatolia-trails.example/hooks/viaturquia", "events": [ "booking.created", "booking.confirmed", "booking.cancelled", "booking.deposit_paid", "booking.updated", "tour.approved", "tour.unpublished" ], "is_active": true, "fail_streak": 0, "secret_set": true, "created_at": "2026-10-21T11:00:00+03:00", "updated_at": "2026-10-21T11:00:00+03:00" }, "available_events": [ "booking.created", "booking.confirmed", "booking.cancelled", "booking.deposit_paid", "booking.updated", "tour.approved", "tour.unpublished", "ping" ], "last_delivery": { "delivery_id": 311, "event_id": "evt_4be1f09a77c3d2a05c18", "event_type": "booking.created", "status": "delivered", "attempts": 1, "max_attempts": 6, "next_attempt_at": null, "last_status": 200, "last_error": null, "created_at": "2026-10-22T09:12:31+03:00", "delivered_at": "2026-10-22T09:13:02+03:00" }, "deliveries": { "pending": 0, "delivered": 14, "failed": 1 }, "secret": "whsec_n4B8kV2zQxT7pLd1sWm9RhYc6AeU3uJf5GoIxC0tKeH", "ignored": [] } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "webhook_not_configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook/test": { "post": { "operationId": "testWebhook", "tags": [ "Webhook" ], "summary": "Queue a ping event to your webhook.", "description": "Answers 202 Accepted, not 200: the event is queued, not sent. It goes out within a minute; read its outcome from GET /webhook/deliveries.\n\nThis, the test button on your partner panel and /webhook/deliveries/{id}/retry share one allowance of 10 an hour per partner (not per key). A test event counts whichever of the two doors queued it; every POST to the retry path counts whatever the answer, including a 403 for a missing scope and a 429. Over the allowance: 429 with Retry-After.\n\n409 webhook_inactive if the webhook is switched off; 404 webhook_not_configured if you have none.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1-80 printable ASCII characters. A second request with the same key and body within 24 hours replays the first answer (Idempotency-Replayed: true).", "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "202": { "description": "queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryQueued" }, "example": { "data": [ { "delivery_id": 312, "event_id": "evt_c07d6e25b19f8a3340e7", "event_type": "ping", "status": "pending", "attempts": 0, "max_attempts": 6, "next_attempt_at": "2026-10-22T10:21:00+03:00", "last_status": null, "last_error": null, "created_at": "2026-10-22T10:21:00+03:00", "delivered_at": null } ], "pagination": { "page": 1, "per_page": 1, "total": 1, "has_more": false }, "ignored": [] } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "webhook_inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook/deliveries": { "get": { "operationId": "listDeliveries", "tags": [ "Webhook" ], "summary": "Recent deliveries, newest first, with their state and what your endpoint answered. Deliveries are kept for 90 days.", "description": "last_error holds the first 500 characters of what your endpoint answered, or the reason nothing did. It is empty on a delivered row.\n\nattempts counts tries so far out of max_attempts. A pending row carries next_attempt_at.\n\nReadable with webhooks:write or account:read.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write", "account:read" ], "x-required-scopes-note": "Any one of these scopes is enough.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, from 1.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page. Default 50, at most 100.", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "pending, delivered or failed.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryList" }, "example": { "data": [ { "delivery_id": 312, "event_id": "evt_c07d6e25b19f8a3340e7", "event_type": "ping", "status": "pending", "attempts": 0, "max_attempts": 6, "next_attempt_at": "2026-10-22T10:21:00+03:00", "last_status": null, "last_error": null, "created_at": "2026-10-22T10:21:00+03:00", "delivered_at": null }, { "delivery_id": 311, "event_id": "evt_4be1f09a77c3d2a05c18", "event_type": "booking.created", "status": "delivered", "attempts": 1, "max_attempts": 6, "next_attempt_at": null, "last_status": 200, "last_error": null, "created_at": "2026-10-22T09:12:31+03:00", "delivered_at": "2026-10-22T09:13:02+03:00" }, { "delivery_id": 305, "event_id": "evt_91d0a3c6e84b7f21a9d3", "event_type": "booking.confirmed", "status": "failed", "attempts": 6, "max_attempts": 6, "next_attempt_at": null, "last_status": 503, "last_error": "The endpoint answered 503.", "created_at": "2026-10-21T17:40:10+03:00", "delivered_at": null } ], "pagination": { "page": 1, "per_page": 50, "total": 3, "has_more": false } } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook/deliveries/{id}/retry": { "post": { "operationId": "retryDelivery", "tags": [ "Webhook" ], "summary": "Send a failed delivery again.", "description": "Acts only on a delivery whose status is failed - one that has given up. A delivered row is 409 already_delivered and a still-queued one 409 delivery_not_failed (it will be tried on its own).\n\nThe schedule starts over (a fresh run of 6 attempts), the event id does not change. Answers 202: it is queued, not sent.\n\nShares the 10-an-hour allowance with /webhook/test (see there). Needs an active webhook: 409 webhook_inactive otherwise.", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write" ], "x-required-scopes-note": "This scope is required.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The delivery_id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1-80 printable ASCII characters. A second request with the same key and body within 24 hours replays the first answer (Idempotency-Replayed: true).", "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "202": { "description": "queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryQueued" }, "example": { "data": [ { "delivery_id": 305, "event_id": "evt_91d0a3c6e84b7f21a9d3", "event_type": "booking.confirmed", "status": "pending", "attempts": 0, "max_attempts": 6, "next_attempt_at": "2026-10-22T10:25:00+03:00", "last_status": 503, "last_error": "The endpoint answered 503.", "created_at": "2026-10-21T17:40:10+03:00", "delivered_at": null } ], "pagination": { "page": 1, "per_page": 1, "total": 1, "has_more": false }, "ignored": [] } } } }, "401": { "description": "authentication_error - see \"Errors\" in the documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error - the key lacks the scope (insufficient_scope), or API access is off for the partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "delivery_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "delivery_not_failed, already_delivered, webhook_inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error - wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_disabled - the API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApi", "tags": [ "Service and account" ], "summary": "This API as an OpenAPI 3.1 document.", "description": "Needs no key and is readable even while the API is switched off, so you can load it into Postman or Insomnia before you have an account.", "security": [], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "vtp_live__", "description": "An API key from the partner panel. Never put it in a query string - that is refused." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "conflict", "validation_error", "rate_limit_error", "server_error", "service_unavailable" ] }, "code": { "type": "string", "description": "A stable machine-readable code." }, "message": { "type": "string" }, "field": { "type": "string", "description": "The input that was wrong, when one was." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } } }, "description": "Every wrong field, when several were." } }, "required": [ "type", "code", "message" ] }, "request_id": { "type": "string", "description": "Also in the X-Request-Id header. Quote it to us." } }, "required": [ "error", "request_id" ] }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" }, "as_of": { "type": "string", "description": "Only on GET /tours and GET /bookings: send it back as updated_since.", "format": "date-time" } }, "required": [ "page", "per_page", "total", "has_more" ] }, "Ping": { "type": "object", "properties": { "ok": { "type": "boolean" }, "version": { "type": "string" }, "time": { "type": "string", "format": "date-time" }, "authorization_header_seen": { "type": "boolean" } } }, "Me": { "type": "object", "properties": { "partner": { "type": "object", "properties": { "partner_id": { "type": "integer" }, "slug": { "type": "string" }, "company_name": { "type": "string" }, "contact_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "license_number": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "languages_spoken": { "type": "array", "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "api_enabled": { "type": "boolean" }, "notify_email": { "type": "boolean" }, "commission_pct": { "type": "number", "description": "Read only." }, "bank_account_holder": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "bank_iban": { "type": [ "string", "null" ] }, "bank_swift": { "type": [ "string", "null" ] }, "tax_id": { "type": [ "string", "null" ] }, "approved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." } } }, "key": { "type": "object", "properties": { "key_id": { "type": "string" }, "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." } } }, "rate_limit": { "type": "object", "properties": { "per_minute": { "type": "integer" }, "per_day": { "type": "integer" }, "remaining": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." } } } } }, "MeUpdated": { "type": "object", "properties": { "partner": { "type": "object", "properties": { "partner_id": { "type": "integer" }, "slug": { "type": "string" }, "company_name": { "type": "string" }, "contact_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "license_number": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "languages_spoken": { "type": "array", "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "api_enabled": { "type": "boolean" }, "notify_email": { "type": "boolean" }, "commission_pct": { "type": "number", "description": "Read only." }, "bank_account_holder": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "bank_iban": { "type": [ "string", "null" ] }, "bank_swift": { "type": [ "string", "null" ] }, "tax_id": { "type": [ "string", "null" ] }, "approved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." } } }, "key": { "type": "object", "properties": { "key_id": { "type": "string" }, "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." } } }, "rate_limit": { "type": "object", "properties": { "per_minute": { "type": "integer" }, "per_day": { "type": "integer" }, "remaining": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." } } }, "ignored": { "type": "array", "items": { "type": "string" }, "description": "Fields of the request that were dropped (not writable, or not known)." } } }, "MeWrite": { "type": "object", "properties": { "company_name": { "type": "string" }, "contact_name": { "type": "string" }, "phone": { "type": "string", "description": "International form, +905321234567." }, "country": { "type": "string" }, "website": { "type": "string", "description": "http or https." }, "description": { "type": "string", "description": "Simple HTML formatting." }, "languages_spoken": { "type": "array", "items": { "type": "string" } }, "bank_account_holder": { "type": "string" }, "bank_name": { "type": "string" }, "bank_iban": { "type": "string" }, "bank_swift": { "type": "string" }, "tax_id": { "type": "string" } } }, "Reference": { "type": "object", "properties": { "languages": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "category_id": { "type": "integer" }, "parent_id": { "type": [ "integer", "null" ] }, "slug": { "type": "string" }, "names": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } } } } }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "destination_id": { "type": "integer" }, "slug": { "type": "string" }, "names": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } } } } }, "experience_types": { "type": "array", "items": { "type": "object", "properties": { "experience_type_id": { "type": "integer" }, "slug": { "type": "string" }, "names": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } } } } }, "seasons": { "type": "array", "items": { "type": "object", "properties": { "season_id": { "type": "integer" }, "name_key": { "type": "string" }, "names": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "date_ranges": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "description": "MM-DD" }, "end": { "type": "string", "description": "MM-DD" } } } } } } }, "hotel_categories": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "names": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "descriptions": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } } } } }, "room_types": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "capacity": { "type": "integer" }, "names": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } } } } }, "difficulty_levels": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "labels": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "group_types": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "labels": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "age_ranges": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "labels": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "document_types": { "type": "array", "items": { "type": "string" } }, "guide_languages": { "type": "array", "items": { "type": "string" } } } }, "RequestList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "request_id": { "type": "string" }, "key_id": { "type": [ "string", "null" ] }, "method": { "type": "string" }, "path": { "type": "string" }, "status": { "type": "integer" }, "duration_ms": { "type": "integer" }, "ip": { "type": "string" }, "idempotency_key": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "MatrixCell": { "type": "object", "properties": { "season_id": { "type": "integer", "description": "From GET /reference seasons." }, "hotel_category": { "type": "string", "description": "A, B or C.", "enum": [ "A", "B", "C" ] }, "room_type": { "type": "string", "enum": [ "double", "triple", "individual" ] }, "price": { "type": "number", "description": "Per person, EUR, above 0." } }, "required": [ "season_id", "hotel_category", "room_type", "price" ] }, "Tour": { "type": "object", "properties": { "tour_id": { "type": "integer", "description": "Read only." }, "group_id": { "type": "integer", "description": "Read only. Ties the language versions of one tour together." }, "language": { "type": "string", "description": "en, es, pt or ar. Chosen at creation, never changed.", "enum": [ "en", "es", "pt", "ar" ] }, "slug": { "type": "string", "description": "Read only." }, "status": { "type": "string", "description": "Read only. awaiting_review until Via Turquia publishes it.", "enum": [ "awaiting_review", "published" ] }, "is_active": { "type": "boolean", "description": "Read only." }, "title": { "type": "string", "description": "Required on create. At most 255 characters." }, "short_description": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ], "description": "Simple HTML formatting." }, "highlights": { "type": "array", "items": { "type": "string" }, "description": "One line each." }, "important_info": { "type": [ "string", "null" ] }, "meeting_point": { "type": [ "string", "null" ] }, "ending_point": { "type": [ "string", "null" ] }, "starting_time": { "type": [ "string", "null" ] }, "duration": { "type": "object", "properties": { "days": { "type": "integer", "description": "Shared by every language. At least 1." }, "nights": { "type": "integer", "description": "Shared. Forced to 0 while includes.hotel is false." }, "details": { "type": [ "string", "null" ] } } }, "group": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "description": "A code from /reference group_types, or your own text." }, "max_size": { "type": [ "integer", "null" ], "description": "Shared." }, "min_participants": { "type": [ "integer", "null" ], "description": "Shared." }, "max_participants": { "type": [ "integer", "null" ], "description": "Shared." } } }, "age": { "type": "object", "properties": { "min_age": { "type": [ "integer", "null" ] }, "range": { "type": [ "string", "null" ], "description": "A code from /reference age_ranges, or your own text." }, "child_label": { "type": [ "string", "null" ] }, "infant_label": { "type": [ "string", "null" ] } } }, "difficulty_level": { "type": [ "string", "null" ], "description": "easy, moderate, challenging or difficult. Null leaves the stored value alone." }, "difficulty_label": { "type": [ "string", "null" ], "description": "Read only: the stored text." }, "includes": { "type": "object", "properties": { "hotel": { "type": "boolean", "description": "The switch that decides whether the tour is priced by room. Shared by every language." }, "guide": { "type": "boolean" }, "meals": { "type": "boolean" }, "transfers": { "type": "boolean" }, "tickets": { "type": "boolean" } } }, "inclusions": { "type": "array", "items": { "type": "string" } }, "exclusions": { "type": "array", "items": { "type": "string" } }, "itinerary": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "description": "Simple HTML formatting." } } } }, "faqs": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } }, "supplements": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Required while active." }, "description": { "type": [ "string", "null" ] }, "price": { "type": "number", "description": "EUR." }, "per_person": { "type": "boolean", "description": "Default true." }, "active": { "type": "boolean", "description": "Default true. false hides it from customers." } } }, "description": "A write replaces every row, inactive ones included." }, "pricing": { "type": "object", "properties": { "mode": { "type": "string", "description": "matrix as soon as one cell exists, otherwise flat. Derived.", "enum": [ "flat", "matrix" ] }, "hotel_included": { "type": "boolean", "description": "Derived from includes.hotel." }, "matrix_cells": { "type": "integer", "description": "How many of the 27 cells exist." }, "matrix_complete": { "type": "boolean" }, "price": { "type": "number", "description": "Per person, EUR. On a matrix tour this is the cheapest cell and cannot be set by hand." }, "original_price": { "type": [ "number", "null" ], "description": "A struck-through \"was\" price." }, "child_discount_pct": { "type": "number", "description": "0-100." }, "infant_discount_pct": { "type": "number", "description": "0-100." }, "matrix": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixCell" }, "description": "Present once at least one cell exists." } } }, "cancellation": { "type": "object", "properties": { "policy": { "type": [ "string", "null" ], "description": "Simple HTML formatting." }, "free_hours": { "type": [ "integer", "null" ], "description": "Shared." } } }, "media": { "type": "object", "properties": { "main_image": { "type": [ "string", "null" ], "description": "A Via Turquia address. Use POST /tours/{id}/images to bring one in." }, "gallery": { "type": "array", "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] } } }, "taxonomy": { "type": "object", "properties": { "category_id": { "type": [ "integer", "null" ], "description": "Primary category, or null." }, "categories": { "type": "array", "items": { "type": "integer" }, "description": "Every category the tour is listed in." }, "destinations": { "type": "array", "items": { "type": "integer" } }, "experience_types": { "type": "array", "items": { "type": "integer" } }, "guide_languages": { "type": "array", "items": { "type": "string" } } }, "description": "Ids come from GET /reference." }, "reference_url": { "type": [ "string", "null" ], "description": "Your own page for this tour. Shared. Never shown to customers." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." } } }, "TourWrite": { "type": "object", "properties": { "language": { "type": "string", "description": "en, es, pt or ar. Chosen at creation, never changed.", "enum": [ "en", "es", "pt", "ar" ] }, "title": { "type": "string", "description": "Required on create. At most 255 characters." }, "short_description": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ], "description": "Simple HTML formatting." }, "highlights": { "type": "array", "items": { "type": "string" }, "description": "One line each." }, "important_info": { "type": [ "string", "null" ] }, "meeting_point": { "type": [ "string", "null" ] }, "ending_point": { "type": [ "string", "null" ] }, "starting_time": { "type": [ "string", "null" ] }, "duration": { "type": "object", "properties": { "days": { "type": "integer", "description": "Shared by every language. At least 1." }, "nights": { "type": "integer", "description": "Shared. Forced to 0 while includes.hotel is false." }, "details": { "type": [ "string", "null" ] } } }, "group": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "description": "A code from /reference group_types, or your own text." }, "max_size": { "type": [ "integer", "null" ], "description": "Shared." }, "min_participants": { "type": [ "integer", "null" ], "description": "Shared." }, "max_participants": { "type": [ "integer", "null" ], "description": "Shared." } } }, "age": { "type": "object", "properties": { "min_age": { "type": [ "integer", "null" ] }, "range": { "type": [ "string", "null" ], "description": "A code from /reference age_ranges, or your own text." }, "child_label": { "type": [ "string", "null" ] }, "infant_label": { "type": [ "string", "null" ] } } }, "difficulty_level": { "type": [ "string", "null" ], "description": "easy, moderate, challenging or difficult. Null leaves the stored value alone." }, "includes": { "type": "object", "properties": { "hotel": { "type": "boolean", "description": "The switch that decides whether the tour is priced by room. Shared by every language." }, "guide": { "type": "boolean" }, "meals": { "type": "boolean" }, "transfers": { "type": "boolean" }, "tickets": { "type": "boolean" } } }, "inclusions": { "type": "array", "items": { "type": "string" } }, "exclusions": { "type": "array", "items": { "type": "string" } }, "itinerary": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "description": "Simple HTML formatting." } } } }, "faqs": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } }, "supplements": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Required while active." }, "description": { "type": [ "string", "null" ] }, "price": { "type": "number", "description": "EUR." }, "per_person": { "type": "boolean", "description": "Default true." }, "active": { "type": "boolean", "description": "Default true. false hides it from customers." } } }, "description": "A write replaces every row, inactive ones included." }, "pricing": { "type": "object", "properties": { "price": { "type": "number", "description": "Per person, EUR. On a matrix tour this is the cheapest cell and cannot be set by hand." }, "original_price": { "type": [ "number", "null" ], "description": "A struck-through \"was\" price." }, "child_discount_pct": { "type": "number", "description": "0-100." }, "infant_discount_pct": { "type": "number", "description": "0-100." } }, "description": "Flat figures only. The matrix has its own endpoint." }, "cancellation": { "type": "object", "properties": { "policy": { "type": [ "string", "null" ], "description": "Simple HTML formatting." }, "free_hours": { "type": [ "integer", "null" ], "description": "Shared." } } }, "media": { "type": "object", "properties": { "main_image": { "type": [ "string", "null" ], "description": "A Via Turquia address. Use POST /tours/{id}/images to bring one in." }, "gallery": { "type": "array", "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] } } }, "taxonomy": { "type": "object", "properties": { "category_id": { "type": [ "integer", "null" ], "description": "Primary category, or null." }, "categories": { "type": "array", "items": { "type": "integer" }, "description": "Every category the tour is listed in." }, "destinations": { "type": "array", "items": { "type": "integer" } }, "experience_types": { "type": "array", "items": { "type": "integer" } }, "guide_languages": { "type": "array", "items": { "type": "string" } } }, "description": "Ids come from GET /reference." }, "reference_url": { "type": [ "string", "null" ], "description": "Your own page for this tour. Shared. Never shown to customers." } }, "description": "Every field is optional on PATCH. On POST only title is required. Read-only fields sent back are accepted and ignored." }, "TourWritten": { "type": "object", "properties": { "tour_id": { "type": "integer", "description": "Read only." }, "group_id": { "type": "integer", "description": "Read only. Ties the language versions of one tour together." }, "language": { "type": "string", "description": "en, es, pt or ar. Chosen at creation, never changed.", "enum": [ "en", "es", "pt", "ar" ] }, "slug": { "type": "string", "description": "Read only." }, "status": { "type": "string", "description": "Read only. awaiting_review until Via Turquia publishes it.", "enum": [ "awaiting_review", "published" ] }, "is_active": { "type": "boolean", "description": "Read only." }, "title": { "type": "string", "description": "Required on create. At most 255 characters." }, "short_description": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ], "description": "Simple HTML formatting." }, "highlights": { "type": "array", "items": { "type": "string" }, "description": "One line each." }, "important_info": { "type": [ "string", "null" ] }, "meeting_point": { "type": [ "string", "null" ] }, "ending_point": { "type": [ "string", "null" ] }, "starting_time": { "type": [ "string", "null" ] }, "duration": { "type": "object", "properties": { "days": { "type": "integer", "description": "Shared by every language. At least 1." }, "nights": { "type": "integer", "description": "Shared. Forced to 0 while includes.hotel is false." }, "details": { "type": [ "string", "null" ] } } }, "group": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "description": "A code from /reference group_types, or your own text." }, "max_size": { "type": [ "integer", "null" ], "description": "Shared." }, "min_participants": { "type": [ "integer", "null" ], "description": "Shared." }, "max_participants": { "type": [ "integer", "null" ], "description": "Shared." } } }, "age": { "type": "object", "properties": { "min_age": { "type": [ "integer", "null" ] }, "range": { "type": [ "string", "null" ], "description": "A code from /reference age_ranges, or your own text." }, "child_label": { "type": [ "string", "null" ] }, "infant_label": { "type": [ "string", "null" ] } } }, "difficulty_level": { "type": [ "string", "null" ], "description": "easy, moderate, challenging or difficult. Null leaves the stored value alone." }, "difficulty_label": { "type": [ "string", "null" ], "description": "Read only: the stored text." }, "includes": { "type": "object", "properties": { "hotel": { "type": "boolean", "description": "The switch that decides whether the tour is priced by room. Shared by every language." }, "guide": { "type": "boolean" }, "meals": { "type": "boolean" }, "transfers": { "type": "boolean" }, "tickets": { "type": "boolean" } } }, "inclusions": { "type": "array", "items": { "type": "string" } }, "exclusions": { "type": "array", "items": { "type": "string" } }, "itinerary": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "description": "Simple HTML formatting." } } } }, "faqs": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } }, "supplements": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Required while active." }, "description": { "type": [ "string", "null" ] }, "price": { "type": "number", "description": "EUR." }, "per_person": { "type": "boolean", "description": "Default true." }, "active": { "type": "boolean", "description": "Default true. false hides it from customers." } } }, "description": "A write replaces every row, inactive ones included." }, "pricing": { "type": "object", "properties": { "mode": { "type": "string", "description": "matrix as soon as one cell exists, otherwise flat. Derived.", "enum": [ "flat", "matrix" ] }, "hotel_included": { "type": "boolean", "description": "Derived from includes.hotel." }, "matrix_cells": { "type": "integer", "description": "How many of the 27 cells exist." }, "matrix_complete": { "type": "boolean" }, "price": { "type": "number", "description": "Per person, EUR. On a matrix tour this is the cheapest cell and cannot be set by hand." }, "original_price": { "type": [ "number", "null" ], "description": "A struck-through \"was\" price." }, "child_discount_pct": { "type": "number", "description": "0-100." }, "infant_discount_pct": { "type": "number", "description": "0-100." }, "matrix": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixCell" }, "description": "Present once at least one cell exists." } } }, "cancellation": { "type": "object", "properties": { "policy": { "type": [ "string", "null" ], "description": "Simple HTML formatting." }, "free_hours": { "type": [ "integer", "null" ], "description": "Shared." } } }, "media": { "type": "object", "properties": { "main_image": { "type": [ "string", "null" ], "description": "A Via Turquia address. Use POST /tours/{id}/images to bring one in." }, "gallery": { "type": "array", "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] } } }, "taxonomy": { "type": "object", "properties": { "category_id": { "type": [ "integer", "null" ], "description": "Primary category, or null." }, "categories": { "type": "array", "items": { "type": "integer" }, "description": "Every category the tour is listed in." }, "destinations": { "type": "array", "items": { "type": "integer" } }, "experience_types": { "type": "array", "items": { "type": "integer" } }, "guide_languages": { "type": "array", "items": { "type": "string" } } }, "description": "Ids come from GET /reference." }, "reference_url": { "type": [ "string", "null" ], "description": "Your own page for this tour. Shared. Never shown to customers." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "ignored": { "type": "array", "items": { "type": "string" }, "description": "Fields of the request that were dropped (not writable, or not known)." } } }, "TourList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "tour_id": { "type": "integer" }, "group_id": { "type": "integer" }, "language": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "is_active": { "type": "boolean" }, "price": { "type": "number" }, "duration_days": { "type": "integer" }, "duration_nights": { "type": "integer" }, "hotel_included": { "type": "boolean" }, "pricing_mode": { "type": "string", "enum": [ "flat", "matrix" ] }, "main_image": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Deleted": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "tour_id": { "type": "integer" } } }, "Pricing": { "type": "object", "properties": { "tour_id": { "type": "integer" }, "group_id": { "type": "integer" }, "group_tour_ids": { "type": "array", "items": { "type": "integer" }, "description": "The language versions these prices are shared by." }, "mode": { "type": "string", "description": "matrix as soon as one cell exists, otherwise flat. Derived.", "enum": [ "flat", "matrix" ] }, "hotel_included": { "type": "boolean", "description": "Derived from includes.hotel." }, "matrix_cells": { "type": "integer", "description": "How many of the 27 cells exist." }, "matrix_complete": { "type": "boolean" }, "price": { "type": "number", "description": "Per person, EUR. On a matrix tour this is the cheapest cell and cannot be set by hand." }, "original_price": { "type": [ "number", "null" ], "description": "A struck-through \"was\" price." }, "child_discount_pct": { "type": "number", "description": "0-100." }, "infant_discount_pct": { "type": "number", "description": "0-100." }, "matrix": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixCell" }, "description": "Present once at least one cell exists." } } }, "PricingWritten": { "type": "object", "properties": { "tour_id": { "type": "integer" }, "group_id": { "type": "integer" }, "group_tour_ids": { "type": "array", "items": { "type": "integer" } }, "mode": { "type": "string", "description": "matrix as soon as one cell exists, otherwise flat. Derived.", "enum": [ "flat", "matrix" ] }, "hotel_included": { "type": "boolean", "description": "Derived from includes.hotel." }, "matrix_cells": { "type": "integer", "description": "How many of the 27 cells exist." }, "matrix_complete": { "type": "boolean" }, "price": { "type": "number", "description": "Per person, EUR. On a matrix tour this is the cheapest cell and cannot be set by hand." }, "original_price": { "type": [ "number", "null" ], "description": "A struck-through \"was\" price." }, "child_discount_pct": { "type": "number", "description": "0-100." }, "infant_discount_pct": { "type": "number", "description": "0-100." }, "matrix": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixCell" }, "description": "Present once at least one cell exists." }, "ignored": { "type": "array", "items": { "type": "string" }, "description": "Fields of the request that were dropped (not writable, or not known)." } } }, "PricingWrite": { "type": "object", "properties": { "matrix": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixCell" }, "description": "All 27 cells, for an accommodation tour." }, "price": { "type": "number", "description": "The single per-person price of a day tour." } }, "description": "Send matrix or price, not both." }, "ImageUrl": { "type": "object", "properties": { "url": { "type": "string", "description": "https address (POST) or a gallery address (DELETE)." } }, "required": [ "url" ] }, "ImageAdded": { "type": "object", "properties": { "tour_id": { "type": "integer" }, "url": { "type": "string" }, "source": { "type": "string", "enum": [ "upload", "url" ] }, "gallery_count": { "type": "integer" } } }, "ImageRemoved": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "tour_id": { "type": "integer" }, "url": { "type": "string" }, "gallery_count": { "type": "integer" } } }, "TranslationCreate": { "type": "object", "properties": { "language": { "type": "string", "enum": [ "en", "es", "pt", "ar" ] } }, "required": [ "language" ] }, "TranslationCreated": { "type": "object", "properties": { "tour_id": { "type": "integer", "description": "Read only." }, "group_id": { "type": "integer", "description": "Read only. Ties the language versions of one tour together." }, "language": { "type": "string", "description": "en, es, pt or ar. Chosen at creation, never changed.", "enum": [ "en", "es", "pt", "ar" ] }, "slug": { "type": "string", "description": "Read only." }, "status": { "type": "string", "description": "Read only. awaiting_review until Via Turquia publishes it.", "enum": [ "awaiting_review", "published" ] }, "is_active": { "type": "boolean", "description": "Read only." }, "title": { "type": "string", "description": "Required on create. At most 255 characters." }, "short_description": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ], "description": "Simple HTML formatting." }, "highlights": { "type": "array", "items": { "type": "string" }, "description": "One line each." }, "important_info": { "type": [ "string", "null" ] }, "meeting_point": { "type": [ "string", "null" ] }, "ending_point": { "type": [ "string", "null" ] }, "starting_time": { "type": [ "string", "null" ] }, "duration": { "type": "object", "properties": { "days": { "type": "integer", "description": "Shared by every language. At least 1." }, "nights": { "type": "integer", "description": "Shared. Forced to 0 while includes.hotel is false." }, "details": { "type": [ "string", "null" ] } } }, "group": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "description": "A code from /reference group_types, or your own text." }, "max_size": { "type": [ "integer", "null" ], "description": "Shared." }, "min_participants": { "type": [ "integer", "null" ], "description": "Shared." }, "max_participants": { "type": [ "integer", "null" ], "description": "Shared." } } }, "age": { "type": "object", "properties": { "min_age": { "type": [ "integer", "null" ] }, "range": { "type": [ "string", "null" ], "description": "A code from /reference age_ranges, or your own text." }, "child_label": { "type": [ "string", "null" ] }, "infant_label": { "type": [ "string", "null" ] } } }, "difficulty_level": { "type": [ "string", "null" ], "description": "easy, moderate, challenging or difficult. Null leaves the stored value alone." }, "difficulty_label": { "type": [ "string", "null" ], "description": "Read only: the stored text." }, "includes": { "type": "object", "properties": { "hotel": { "type": "boolean", "description": "The switch that decides whether the tour is priced by room. Shared by every language." }, "guide": { "type": "boolean" }, "meals": { "type": "boolean" }, "transfers": { "type": "boolean" }, "tickets": { "type": "boolean" } } }, "inclusions": { "type": "array", "items": { "type": "string" } }, "exclusions": { "type": "array", "items": { "type": "string" } }, "itinerary": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "description": "Simple HTML formatting." } } } }, "faqs": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } }, "supplements": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Required while active." }, "description": { "type": [ "string", "null" ] }, "price": { "type": "number", "description": "EUR." }, "per_person": { "type": "boolean", "description": "Default true." }, "active": { "type": "boolean", "description": "Default true. false hides it from customers." } } }, "description": "A write replaces every row, inactive ones included." }, "pricing": { "type": "object", "properties": { "mode": { "type": "string", "description": "matrix as soon as one cell exists, otherwise flat. Derived.", "enum": [ "flat", "matrix" ] }, "hotel_included": { "type": "boolean", "description": "Derived from includes.hotel." }, "matrix_cells": { "type": "integer", "description": "How many of the 27 cells exist." }, "matrix_complete": { "type": "boolean" }, "price": { "type": "number", "description": "Per person, EUR. On a matrix tour this is the cheapest cell and cannot be set by hand." }, "original_price": { "type": [ "number", "null" ], "description": "A struck-through \"was\" price." }, "child_discount_pct": { "type": "number", "description": "0-100." }, "infant_discount_pct": { "type": "number", "description": "0-100." }, "matrix": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixCell" }, "description": "Present once at least one cell exists." } } }, "cancellation": { "type": "object", "properties": { "policy": { "type": [ "string", "null" ], "description": "Simple HTML formatting." }, "free_hours": { "type": [ "integer", "null" ], "description": "Shared." } } }, "media": { "type": "object", "properties": { "main_image": { "type": [ "string", "null" ], "description": "A Via Turquia address. Use POST /tours/{id}/images to bring one in." }, "gallery": { "type": "array", "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] } } }, "taxonomy": { "type": "object", "properties": { "category_id": { "type": [ "integer", "null" ], "description": "Primary category, or null." }, "categories": { "type": "array", "items": { "type": "integer" }, "description": "Every category the tour is listed in." }, "destinations": { "type": "array", "items": { "type": "integer" } }, "experience_types": { "type": "array", "items": { "type": "integer" } }, "guide_languages": { "type": "array", "items": { "type": "string" } } }, "description": "Ids come from GET /reference." }, "reference_url": { "type": [ "string", "null" ], "description": "Your own page for this tour. Shared. Never shown to customers." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "ignored": { "type": "array", "items": { "type": "string" }, "description": "Fields of the request that were dropped (not writable, or not known)." }, "needs": { "type": "array", "items": { "type": "string" }, "description": "What you still have to fill in." } } }, "Booking": { "type": "object", "properties": { "booking_ref": { "type": "string" }, "booking_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "cancelled", "completed" ] }, "source": { "type": "string", "description": "web, chat, ..." }, "tour": { "type": "object", "properties": { "tour_id": { "type": "integer" }, "group_id": { "type": "integer" }, "language": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" } } }, "booking_date": { "type": [ "string", "null" ], "format": "date", "description": "The travel date." }, "travellers": { "type": "object", "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "infants": { "type": "integer" }, "total": { "type": "integer" } } }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "room_type_id": { "type": "integer" }, "room_type": { "type": [ "string", "null" ], "description": "double, triple or individual." }, "room_type_name": { "type": [ "string", "null" ] }, "capacity": { "type": [ "integer", "null" ] }, "hotel_category_id": { "type": "integer" }, "hotel_category": { "type": [ "string", "null" ], "description": "A, B or C." }, "hotel_category_name": { "type": [ "string", "null" ] }, "season_id": { "type": "integer" }, "season": { "type": [ "string", "null" ] }, "season_name": { "type": [ "string", "null" ] }, "occupancy": { "type": "integer" }, "travellers": { "type": "object", "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "infants": { "type": "integer" } } }, "price_per_person": { "type": "number", "description": "EUR." }, "room_subtotal": { "type": "number", "description": "EUR." } } } }, "room_summary": { "type": "object", "properties": { "season_id": { "type": [ "integer", "null" ] }, "season_name": { "type": [ "string", "null" ] }, "hotel_category_id": { "type": [ "integer", "null" ] }, "hotel_category_name": { "type": [ "string", "null" ] }, "room_type_id": { "type": [ "integer", "null" ] }, "room_type_name": { "type": [ "string", "null" ] } } }, "supplements": { "type": "object", "properties": { "info": { "type": [ "string", "null" ] }, "total": { "type": "number", "description": "EUR." } } }, "special_requests": { "type": [ "string", "null" ] }, "hotel": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } } }, "pickup_time": { "type": [ "string", "null" ], "description": "HH:MM:SS." }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } } }, "amounts": { "type": "object", "properties": { "currency": { "type": "string", "description": "Always EUR." }, "price_per_person": { "type": "number" }, "discount": { "type": "number" }, "promo_code": { "type": [ "string", "null" ] }, "total": { "type": "number" }, "commission_pct": { "type": "number" }, "commission": { "type": "number", "description": "Zero when cancelled." }, "net": { "type": "number", "description": "Zero when cancelled." }, "currency_shown": { "type": "string", "description": "What the customer saw on the page." } } }, "payment": { "type": "object", "properties": { "deposit_status": { "type": "string", "enum": [ "not_required", "pending", "paid", "refunded" ] }, "deposit_amount": { "type": "number" }, "deposit_paid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "deposit_method": { "type": [ "string", "null" ] }, "payment_status": { "type": "string", "enum": [ "pending", "partial", "paid", "refunded" ] } } }, "partner_answer": { "type": "object", "properties": { "action": { "type": "string", "description": "none, accepted or declined.", "enum": [ "none", "accepted", "declined" ] }, "at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "note": { "type": [ "string", "null" ] } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." } } }, "BookingList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "BookingAnswered": { "type": "object", "properties": { "booking_ref": { "type": "string" }, "booking_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "cancelled", "completed" ] }, "source": { "type": "string", "description": "web, chat, ..." }, "tour": { "type": "object", "properties": { "tour_id": { "type": "integer" }, "group_id": { "type": "integer" }, "language": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" } } }, "booking_date": { "type": [ "string", "null" ], "format": "date", "description": "The travel date." }, "travellers": { "type": "object", "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "infants": { "type": "integer" }, "total": { "type": "integer" } } }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "room_type_id": { "type": "integer" }, "room_type": { "type": [ "string", "null" ], "description": "double, triple or individual." }, "room_type_name": { "type": [ "string", "null" ] }, "capacity": { "type": [ "integer", "null" ] }, "hotel_category_id": { "type": "integer" }, "hotel_category": { "type": [ "string", "null" ], "description": "A, B or C." }, "hotel_category_name": { "type": [ "string", "null" ] }, "season_id": { "type": "integer" }, "season": { "type": [ "string", "null" ] }, "season_name": { "type": [ "string", "null" ] }, "occupancy": { "type": "integer" }, "travellers": { "type": "object", "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "infants": { "type": "integer" } } }, "price_per_person": { "type": "number", "description": "EUR." }, "room_subtotal": { "type": "number", "description": "EUR." } } } }, "room_summary": { "type": "object", "properties": { "season_id": { "type": [ "integer", "null" ] }, "season_name": { "type": [ "string", "null" ] }, "hotel_category_id": { "type": [ "integer", "null" ] }, "hotel_category_name": { "type": [ "string", "null" ] }, "room_type_id": { "type": [ "integer", "null" ] }, "room_type_name": { "type": [ "string", "null" ] } } }, "supplements": { "type": "object", "properties": { "info": { "type": [ "string", "null" ] }, "total": { "type": "number", "description": "EUR." } } }, "special_requests": { "type": [ "string", "null" ] }, "hotel": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } } }, "pickup_time": { "type": [ "string", "null" ], "description": "HH:MM:SS." }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } } }, "amounts": { "type": "object", "properties": { "currency": { "type": "string", "description": "Always EUR." }, "price_per_person": { "type": "number" }, "discount": { "type": "number" }, "promo_code": { "type": [ "string", "null" ] }, "total": { "type": "number" }, "commission_pct": { "type": "number" }, "commission": { "type": "number", "description": "Zero when cancelled." }, "net": { "type": "number", "description": "Zero when cancelled." }, "currency_shown": { "type": "string", "description": "What the customer saw on the page." } } }, "payment": { "type": "object", "properties": { "deposit_status": { "type": "string", "enum": [ "not_required", "pending", "paid", "refunded" ] }, "deposit_amount": { "type": "number" }, "deposit_paid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "deposit_method": { "type": [ "string", "null" ] }, "payment_status": { "type": "string", "enum": [ "pending", "partial", "paid", "refunded" ] } } }, "partner_answer": { "type": "object", "properties": { "action": { "type": "string", "description": "none, accepted or declined.", "enum": [ "none", "accepted", "declined" ] }, "at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "note": { "type": [ "string", "null" ] } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "action": { "type": "string", "description": "accepted or declined." }, "message": { "type": "string" }, "customer_notified": { "type": "boolean", "description": "Declines only: false when the cancellation email could not be delivered." }, "ignored": { "type": "array", "items": { "type": "string" }, "description": "Fields of the request that were dropped (not writable, or not known)." } } }, "AcceptBody": { "type": "object", "properties": { "note": { "type": "string", "description": "Optional, plain text, 500 characters." } } }, "DeclineBody": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional, plain text, 500 characters." } } }, "Delivery": { "type": "object", "properties": { "delivery_id": { "type": "integer" }, "event_id": { "type": "string", "description": "Stable across retries." }, "event_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "attempts": { "type": "integer" }, "max_attempts": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "last_status": { "type": [ "integer", "null" ], "description": "The HTTP status your endpoint answered." }, "last_error": { "type": [ "string", "null" ], "description": "First 500 characters of the answer, or why there was none." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." } } }, "DeliveryList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "DeliveryQueued": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "ignored": { "type": "array", "items": { "type": "string" }, "description": "Fields of the request that were dropped (not writable, or not known)." } } }, "WebhookState": { "type": "object", "properties": { "webhook": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "fail_streak": { "type": "integer", "description": "Failed attempts in a row." }, "secret_set": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." } } } ] }, "available_events": { "type": "array", "items": { "type": "string" } }, "last_delivery": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Delivery" } ] }, "deliveries": { "type": "object", "properties": { "pending": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" } } } } }, "WebhookWritten": { "type": "object", "properties": { "webhook": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "fail_streak": { "type": "integer", "description": "Failed attempts in a row." }, "secret_set": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, Istanbul clock." } } } ] }, "available_events": { "type": "array", "items": { "type": "string" } }, "last_delivery": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Delivery" } ] }, "deliveries": { "type": "object", "properties": { "pending": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" } } }, "secret": { "type": "string", "description": "Present on the first registration and on rotate_secret. Shown once." }, "ignored": { "type": "array", "items": { "type": "string" }, "description": "Fields of the request that were dropped (not writable, or not known)." } } }, "WebhookWrite": { "type": "object", "properties": { "url": { "type": "string", "description": "https only." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "booking.created", "booking.confirmed", "booking.cancelled", "booking.deposit_paid", "booking.updated", "tour.approved", "tour.unpublished", "ping" ] } }, "is_active": { "type": "boolean", "description": "Default true." } }, "required": [ "url" ] }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_..., the same on every retry." }, "type": { "type": "string", "enum": [ "booking.created", "booking.confirmed", "booking.cancelled", "booking.deposit_paid", "booking.updated", "tour.approved", "tour.unpublished", "ping" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "description": "A Booking for booking.* events, a Tour for tour.* events, {message, partner_id, sent_at} for ping." }, "actor": { "type": "string", "description": "Who caused it.", "enum": [ "partner", "admin", "customer", "system" ] } }, "required": [ "id", "type", "created_at", "data", "actor" ] } } }, "webhooks": { "event": { "post": { "summary": "An event Via Turquia POSTs to your registered address", "description": "Verify `X-VT-Signature` (`t=,v1=`) before trusting the body. Reply with any 2xx within 10 seconds. Events can arrive more than once and out of order: de-duplicate on `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_4be1f09a77c3d2a05c18", "type": "booking.created", "created_at": "2026-10-22T09:12:31+03:00", "data": { "booking_ref": "VT2026K7M2QX", "booking_id": 8841, "status": "pending", "source": "web", "tour": { "tour_id": 1301, "group_id": 1301, "language": "en", "title": "Cappadocia 3 Days", "slug": "cappadocia-3-days" }, "booking_date": "2026-11-14", "travellers": { "adults": 2, "children": 0, "infants": 0, "total": 2 }, "rooms": [ { "room_type_id": 1, "room_type": "double", "room_type_name": "Double", "capacity": 2, "hotel_category_id": 2, "hotel_category": "B", "hotel_category_name": "4 stars", "season_id": 1, "season": "highest", "season_name": "Highest season", "occupancy": 2, "travellers": { "adults": 2, "children": 0, "infants": 0 }, "price_per_person": 520, "room_subtotal": 1040 } ], "room_summary": { "season_id": 1, "season_name": "Highest season", "hotel_category_id": 2, "hotel_category_name": "4 stars", "room_type_id": 1, "room_type_name": "Double" }, "supplements": { "info": "Hot-air balloon x2", "total": 300 }, "special_requests": "Vegetarian meals, please.", "hotel": { "name": "Cave Hotel Goreme", "address": "Goreme, Nevsehir" }, "pickup_time": "08:30:00", "customer": { "name": "Ana García", "email": "ana@example.com", "phone": "+34600111222", "country": "Spain" }, "amounts": { "currency": "EUR", "price_per_person": 520, "discount": 0, "promo_code": null, "total": 1340, "commission_pct": 15, "commission": 201, "net": 1139, "currency_shown": "EUR" }, "payment": { "deposit_status": "pending", "deposit_amount": 268, "deposit_paid_at": null, "deposit_method": null, "payment_status": "pending" }, "partner_answer": { "action": "none", "at": null, "note": null }, "created_at": "2026-10-22T09:12:30+03:00", "updated_at": "2026-10-22T09:12:30+03:00" }, "actor": "customer" } } } }, "responses": { "200": { "description": "Any 2xx marks the delivery as delivered." } } } } } }