{ "openapi": "3.1.0", "info": { "title": "Channel API", "version": "1.0", "description": "Channel manager integration (ARI in, reservation notifications out). Body limit 10485760 bytes (also after gzip), at most 200000 expanded cell-days per request, item date range at most 750 days, horizon 750 days. Every response carries X-Request-Id and X-Kanal-Api-Version; 429 and 503 carry Retry-After; an idempotent replay carries Idempotent-Replay: true." }, "servers": [ { "url": "https://{host}/api/kanal/v1", "variables": { "host": { "default": "api.platform.test", "description": "api." } } } ], "security": [ { "apiKey": [] }, { "bearer": [] } ], "paths": { "/test_connection": { "get": { "operationId": "testConnection", "summary": "Connection test", "description": "First call moves a new connection to awaiting mapping. Trailing slash accepted without redirect. Rate limit: 30 requests per minute per connection.", "parameters": [ { "name": "hotel_code", "in": "query", "required": true, "schema": { "type": "string" }, "description": "hotel code of the connection" } ], "responses": { "200": { "description": "connection details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestConnectionResponse" } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ip_not_allowed, hotel_mismatch, module_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "connection_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "service_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mapping_details": { "get": { "operationId": "mappingDetails", "summary": "Mapping list", "description": "Room types and rate plans open to the channel. External codes are locked once listed. Rate limit: 30 requests per minute per connection.", "parameters": [ { "name": "hotel_code", "in": "query", "required": true, "schema": { "type": "string" }, "description": "hotel code of the connection" } ], "responses": { "200": { "description": "rooms and rate plans", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MappingDetailsResponse" } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ip_not_allowed, hotel_mismatch, module_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "connection_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "service_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/changes": { "post": { "operationId": "changes", "summary": "ARI changes (delta or full sync part)", "description": "Deltas only; the same request_id with the same body replays the first response, with a different body 409. A smaller sequence than an applied one does not overwrite newer groups. A full sync is split by sync_id / sync_part / sync_last; cells not covered after the last part become stale. Rate limit: 120 requests per minute per connection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangesRequest" } } } }, "responses": { "200": { "description": "accepted and queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangesResponse" } } } }, "400": { "description": "invalid_json, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ip_not_allowed, hotel_mismatch, module_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "idempotency_conflict, connection_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "unsupported_media_type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "all_items_rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "service_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/booking_revisions": { "get": { "operationId": "bookingRevisions", "summary": "Pull fallback: reservation revisions", "description": "Full notification payloads with delivery trace, oldest first, cursor paginated. Open while the module is disabled or the account is suspended. Rate limit: 12 requests per minute per connection.", "parameters": [ { "name": "hotel_code", "in": "query", "required": true, "schema": { "type": "string" }, "description": "hotel code of the connection" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "unacked", "undecided", "all" ], "default": "unacked" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "next_cursor of the previous page" } ], "responses": { "200": { "description": "revisions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRevisionsResponse" } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ip_not_allowed, hotel_mismatch, module_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "service_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/booking_revisions/{revision_id}/ack": { "post": { "operationId": "bookingRevisionAck", "summary": "Delivery acknowledgement and decision", "description": "received, accepted (with the channel manager reservation id) or rejected (reject_reason required). The same decision again returns 200; a different recorded decision 409 already_decided. Rate limit: 120 requests per minute per connection.", "parameters": [ { "name": "revision_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AckRequest" } } } }, "responses": { "200": { "description": "recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AckResponse" } } } }, "400": { "description": "invalid_json, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ip_not_allowed, hotel_mismatch, module_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "already_decided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "unsupported_media_type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "service_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "webhooks": { "reservationNotification": { "post": { "summary": "Reservation notification", "description": "Sent for every revision (new, modified, cancelled) in order per reservation. Answer accepted, rejected or received (decision later via the ack endpoint); a 2xx without decision counts as received.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "revision_id (notifications) or request_id (connection events and checks); identical on every retry" }, { "name": "X-Kanal-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "event type" }, { "name": "X-Kanal-Delivery", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "attempt number" }, { "name": "X-Kanal-Timestamp", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Unix seconds; reject outside ±300 s" }, { "name": "X-Kanal-Key-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "signing secret identifier" }, { "name": "X-Kanal-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "v1=; comma separated during secret rotation. Canonical string (LF joined, no trailing newline): KANAL1-HMAC-SHA256, method, path and query, timestamp, Idempotency-Key, content type (lower case), hex SHA-256 of the body. Compare in constant time." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationNotification" } } } }, "responses": { "200": { "description": "decision or acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationDecision" } } } }, "429": { "description": "retried after Retry-After" }, "5XX": { "description": "retried with exponential backoff up to 24 hours" } } } }, "connectionEvent": { "post": { "summary": "Connection event", "description": "connection.test verifies the target; ari.full_sync_requested asks for a full ARI sync.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "revision_id (notifications) or request_id (connection events and checks); identical on every retry" }, { "name": "X-Kanal-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "event type" }, { "name": "X-Kanal-Delivery", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "attempt number" }, { "name": "X-Kanal-Timestamp", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Unix seconds; reject outside ±300 s" }, { "name": "X-Kanal-Key-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "signing secret identifier" }, { "name": "X-Kanal-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "v1=; comma separated during secret rotation. Canonical string (LF joined, no trailing newline): KANAL1-HMAC-SHA256, method, path and query, timestamp, Idempotency-Key, content type (lower case), hex SHA-256 of the body. Compare in constant time." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionEvent" } } } }, "responses": { "200": { "description": "decision or acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationDecision" } } } }, "429": { "description": "retried after Retry-After" }, "5XX": { "description": "retried with exponential backoff up to 24 hours" } } } }, "availabilityCheck": { "post": { "summary": "Live availability check", "description": "Optional; sent before the sale when the connection has a check URL.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "revision_id (notifications) or request_id (connection events and checks); identical on every retry" }, { "name": "X-Kanal-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "event type" }, { "name": "X-Kanal-Delivery", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "attempt number" }, { "name": "X-Kanal-Timestamp", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Unix seconds; reject outside ±300 s" }, { "name": "X-Kanal-Key-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "signing secret identifier" }, { "name": "X-Kanal-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "v1=; comma separated during secret rotation. Canonical string (LF joined, no trailing newline): KANAL1-HMAC-SHA256, method, path and query, timestamp, Idempotency-Key, content type (lower case), hex SHA-256 of the body. Compare in constant time." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityCheckRequest" } } } }, "responses": { "200": { "description": "decision or acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityCheckResponse" } } } }, "429": { "description": "retried after Retry-After" }, "5XX": { "description": "retried with exponential backoff up to 24 hours" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "api-key" }, "bearer": { "type": "http", "scheme": "bearer", "description": "the same key as Authorization: Bearer; if both are sent they must be equal" } }, "schemas": { "ChangesRequest": { "type": "object", "properties": { "request_id": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "hotel_code": { "type": "string", "minLength": 1, "maxLength": 64 }, "availability_changes": { "type": "array", "items": { "type": "object", "properties": { "room_type_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "rate_plan_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "date_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "date_to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "availability": { "type": "integer", "minimum": 0, "maximum": 100000 }, "days": { "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "su", "mo", "tu", "we", "th", "fr", "sa" ] } } }, "required": [ "room_type_id", "date_from", "date_to", "availability" ] } }, "restriction_changes": { "type": "array", "items": { "type": "object", "properties": { "room_type_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "rate_plan_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "date_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "date_to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "days": { "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "su", "mo", "tu", "we", "th", "fr", "sa" ] } }, "rate": { "type": "number" }, "rates": { "minItems": 1, "maxItems": 30, "type": "array", "items": { "type": "object", "properties": { "occupancy": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rate": { "type": "number" } }, "required": [ "occupancy", "rate" ] } }, "currency": { "type": "string" }, "fraction_size": { "type": "integer", "minimum": 0, "maximum": 4 }, "stop_sell": { "type": "boolean" }, "closed_to_arrival": { "type": "boolean" }, "closed_to_departure": { "type": "boolean" }, "min_stay_arrival": { "type": "integer", "minimum": 0, "maximum": 10000 }, "min_stay_through": { "type": "integer", "minimum": 0, "maximum": 10000 }, "max_stay": { "type": "integer", "minimum": 0, "maximum": 10000 }, "min_stay": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "room_type_id", "rate_plan_id", "date_from", "date_to" ] } }, "sequence": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "sent_at": { "type": "string", "maxLength": 64 }, "full_sync": { "type": "boolean" }, "sync_id": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "sync_part": { "type": "integer", "minimum": 1, "maximum": 100000 }, "sync_last": { "type": "boolean" } }, "required": [ "request_id", "hotel_code" ], "examples": [ { "request_id": "b7c9e2d4-2f71-4c1e-9a3b-6d5e4f3a2b1c", "hotel_code": "01HZXK4M8Q2W3E5R7T9Y", "sequence": 1843, "availability_changes": [ { "room_type_id": "DBL", "date_from": "2027-06-01", "date_to": "2027-06-14", "availability": 4 } ], "restriction_changes": [ { "room_type_id": "DBL", "rate_plan_id": "BB", "date_from": "2027-06-01", "date_to": "2027-06-07", "currency": "TRY", "rates": [ { "occupancy": 1, "rate": 3200 }, { "occupancy": 2, "rate": 4100.5 } ] }, { "room_type_id": "DBL", "rate_plan_id": "RO", "date_from": "2027-06-01", "date_to": "2027-06-07", "currency": "TRY", "rate": 3600, "min_stay_arrival": 2, "closed_to_arrival": false } ] } ] }, "AckRequest": { "type": "object", "properties": { "hotel_code": { "type": "string", "minLength": 1, "maxLength": 40 }, "decision": { "type": "string", "enum": [ "accepted", "rejected", "received" ] }, "cm_reservation_id": { "type": "string", "pattern": "^[A-Za-z0-9 ./_#-]{1,64}$" }, "reject_reason": { "type": "string", "enum": [ "full", "price", "date", "restriction", "mapping", "closed", "other" ] }, "note": { "type": "string", "maxLength": 1000 } }, "required": [ "hotel_code", "decision" ], "examples": [ { "hotel_code": "01HZXK4M8Q2W3E5R7T9Y", "decision": "accepted", "cm_reservation_id": "CM-448211" } ] }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "request_id": { "type": "string", "description": "request identifier; also returned in the X-Request-Id header" }, "errors": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "path": { "description": "location in the request body, e.g. restriction_changes[3].rates[0].rate; null for the whole request", "type": [ "string", "null" ] }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "code", "message" ], "additionalProperties": false, "description": "error or warning" }, "description": "the first entry carries the request-level error code; further entries detail validation failures" }, "warnings": { "description": "item-level warnings (all_items_rejected)", "type": "array", "items": { "type": "object", "properties": { "path": { "description": "location in the request body, e.g. restriction_changes[3].rates[0].rate; null for the whole request", "type": [ "string", "null" ] }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "code", "message" ], "additionalProperties": false, "description": "error or warning" } } }, "required": [ "success", "request_id", "errors" ], "additionalProperties": false, "description": "error envelope", "examples": [ { "success": false, "request_id": "b7c9e2d4-2f71-4c1e-9a3b-6d5e4f3a2b1c", "errors": [ { "path": null, "code": "validation_failed", "message": "request does not match the schema" }, { "path": "restriction_changes[0].date_from", "code": "validation_failed", "message": "expected YYYY-MM-DD" } ] } ] }, "TestConnectionResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "request_id": { "type": "string", "description": "request identifier; also returned in the X-Request-Id header" }, "data": { "type": "object", "properties": { "hotel_code": { "type": "string" }, "connection_status": { "type": "string", "enum": [ "connected", "awaiting_mapping", "active", "faulty" ] }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "api_versions": { "type": "array", "items": { "type": "string" } }, "server_time": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "capabilities": { "type": "object", "properties": { "sequence": { "type": "boolean" }, "pull_revisions": { "type": "boolean" }, "decision_endpoint": { "type": "boolean" }, "availability_check_outbound": { "type": "boolean" }, "hold": { "type": "boolean" } }, "required": [ "sequence", "pull_revisions", "decision_endpoint", "availability_check_outbound", "hold" ], "additionalProperties": false } }, "required": [ "hotel_code", "connection_status", "environment", "api_versions", "server_time", "capabilities" ], "additionalProperties": false } }, "required": [ "success", "request_id", "data" ], "additionalProperties": false, "examples": [ { "success": true, "request_id": "0192f6a0-2b3c-7d4e-8f5a-6b7c8d9e0f1a", "data": { "hotel_code": "01HZXK4M8Q2W3E5R7T9Y", "connection_status": "awaiting_mapping", "environment": "test", "api_versions": [ "1" ], "server_time": "2027-05-20T09:30:00.000Z", "capabilities": { "sequence": true, "pull_revisions": true, "decision_endpoint": true, "availability_check_outbound": false, "hold": false } } } ] }, "MappingDetailsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "request_id": { "type": "string", "description": "request identifier; also returned in the X-Request-Id header" }, "data": { "type": "object", "properties": { "hotel": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code", "name" ], "additionalProperties": false }, "room_types": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "occupancy": { "type": "object", "properties": { "max_adults": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_children": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "max_adults", "max_children", "max_total" ], "additionalProperties": false }, "rate_plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "sell_mode": { "type": "string", "enum": [ "per_room", "per_person" ] }, "max_persons": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "read_only": { "type": "boolean" }, "meal_type": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "sell_mode", "max_persons", "currency", "read_only", "meal_type" ], "additionalProperties": false } } }, "required": [ "id", "title", "occupancy", "rate_plans" ], "additionalProperties": false } } }, "required": [ "hotel", "room_types" ], "additionalProperties": false } }, "required": [ "success", "request_id", "data" ], "additionalProperties": false, "examples": [ { "success": true, "request_id": "0192f6a0-2b3c-7d4e-8f5a-6b7c8d9e0f1b", "data": { "hotel": { "code": "01HZXK4M8Q2W3E5R7T9Y", "name": "Deniz Otel" }, "room_types": [ { "id": "DBL", "title": "Double Room", "occupancy": { "max_adults": 3, "max_children": 1, "max_total": 3 }, "rate_plans": [ { "id": "BB", "title": "Double Room BB", "sell_mode": "per_person", "max_persons": 3, "currency": "TRY", "read_only": false, "meal_type": "BB" }, { "id": "RO", "title": "Double Room RO", "sell_mode": "per_room", "max_persons": 2, "currency": "TRY", "read_only": false, "meal_type": "RO" } ] } ] } } ] }, "ChangesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "request_id": { "type": "string", "description": "request identifier; also returned in the X-Request-Id header" }, "unique_id": { "type": "string", "description": "identifier of the recorded event" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "event number of the connection (strictly increasing)" }, "status": { "type": "string", "const": "queued", "description": "accepted; applied asynchronously (p95 ≤ 10 s)" }, "counts": { "type": "object", "properties": { "availability_items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "restriction_items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected_items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "cells": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "expanded cell-days of the request" } }, "required": [ "availability_items", "restriction_items", "rejected_items", "cells" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "description": "location in the request body, e.g. restriction_changes[3].rates[0].rate; null for the whole request", "type": [ "string", "null" ] }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "code", "message" ], "additionalProperties": false, "description": "error or warning" } } }, "required": [ "success", "request_id", "unique_id", "version", "status", "counts", "warnings" ], "additionalProperties": false, "examples": [ { "success": true, "request_id": "b7c9e2d4-2f71-4c1e-9a3b-6d5e4f3a2b1c", "unique_id": "0192f6a0-11aa-7c3d-8e9f-a0b1c2d3e4f5", "version": 412, "status": "queued", "counts": { "availability_items": 1, "restriction_items": 2, "rejected_items": 0, "cells": 28 }, "warnings": [] } ] }, "BookingRevisionsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "request_id": { "type": "string", "description": "request identifier; also returned in the X-Request-Id header" }, "data": { "type": "array", "items": { "type": "object", "properties": { "schema_version": { "type": "string", "const": "1.0" }, "event_type": { "type": "string", "enum": [ "booking.new", "booking.modified", "booking.cancelled" ] }, "revision_id": { "type": "string", "description": "identifier of this revision; also the Idempotency-Key of every delivery attempt" }, "revision_no": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "new", "modified", "cancelled" ] }, "hotel_code": { "type": "string" }, "reservation_id": { "type": "string", "description": "our order code; the same for every revision of the reservation" }, "ota_name": { "type": "string" }, "agent": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "code", "phone", "email" ], "additionalProperties": false }, "created_at": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "revision_created_at": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "arrival_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "departure_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "currency": { "type": "string" }, "rooms": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "room_type_id": { "type": "string" }, "rate_plan_id": { "type": "string" }, "meal_type": { "type": [ "string", "null" ] }, "occupancy": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "children": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "infants": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "children_ages": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } }, "required": [ "adults", "children", "infants", "children_ages" ], "additionalProperties": false }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amount": { "type": "number", "minimum": 0, "description": "amount with two decimals (major unit)" } }, "required": [ "date", "amount" ], "additionalProperties": false } }, "amount": { "type": "number", "minimum": 0, "description": "amount with two decimals (major unit)" }, "guests": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "surname": { "type": "string" } }, "required": [ "name", "surname" ], "additionalProperties": false } } }, "required": [ "room_type_id", "rate_plan_id", "meal_type", "occupancy", "days", "amount", "guests" ], "additionalProperties": false } }, "amount": { "type": "number", "minimum": 0, "description": "amount with two decimals (major unit)" }, "price_type": { "type": "string", "enum": [ "net", "gross" ] }, "commission": { "description": "only with price_type gross", "type": "number", "minimum": 0 }, "tax_included": { "type": "boolean", "const": true }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "surname": { "type": "string" }, "nationality": { "type": "string" }, "email": { "description": "only when the connection forwards guest contact", "type": "string" }, "phone": { "description": "only when the connection forwards guest contact", "type": "string" } }, "required": [ "name", "surname" ], "additionalProperties": false }, "notes": { "type": "string" }, "payment_collect": { "type": "string", "const": "channel" }, "payment_type": { "type": "string", "const": "bank_transfer" }, "sales_source": { "type": "string", "enum": [ "site", "panel", "ts" ] }, "check_id": { "description": "availability check identifier, when a live check preceded the sale", "type": "string" }, "hold_id": { "type": "string" }, "test": { "type": "boolean" }, "delivery": { "type": "object", "properties": { "attempts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "last_attempt_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "last_error_code": { "type": [ "string", "null" ] } }, "required": [ "attempts", "last_attempt_at", "last_error_code" ], "additionalProperties": false } }, "required": [ "schema_version", "event_type", "revision_id", "revision_no", "status", "hotel_code", "reservation_id", "ota_name", "agent", "created_at", "revision_created_at", "arrival_date", "departure_date", "currency", "rooms", "amount", "price_type", "tax_included", "payment_collect", "payment_type", "sales_source", "test", "delivery" ], "additionalProperties": false } }, "next_cursor": { "description": "pass as after= to fetch the next page", "type": [ "string", "null" ] } }, "required": [ "success", "request_id", "data", "next_cursor" ], "additionalProperties": false }, "AckResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "request_id": { "type": "string", "description": "request identifier; also returned in the X-Request-Id header" }, "data": { "type": "object", "properties": { "revision_id": { "type": "string" }, "decision": { "type": "string", "enum": [ "accepted", "rejected", "received" ] }, "applied": { "type": "boolean", "description": "true when this call changed the reservation state" }, "order_state": { "type": "string", "enum": [ "confirmed", "awaiting_confirmation", "cancelled" ] }, "recorded_at": { "type": "string", "description": "ISO 8601 timestamp (UTC)" } }, "required": [ "revision_id", "decision", "applied", "order_state", "recorded_at" ], "additionalProperties": false } }, "required": [ "success", "request_id", "data" ], "additionalProperties": false, "examples": [ { "success": true, "request_id": "0192f6a0-2b3c-7d4e-8f5a-6b7c8d9e0f1c", "data": { "revision_id": "0192f6a0-3c1e-7b2a-9d4e-5f6a7b8c9d0e", "decision": "accepted", "applied": true, "order_state": "confirmed", "recorded_at": "2027-05-20T09:31:12.000Z" } } ] }, "ReservationNotification": { "type": "object", "properties": { "schema_version": { "type": "string", "const": "1.0" }, "event_type": { "type": "string", "enum": [ "booking.new", "booking.modified", "booking.cancelled" ] }, "revision_id": { "type": "string", "description": "identifier of this revision; also the Idempotency-Key of every delivery attempt" }, "revision_no": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "new", "modified", "cancelled" ] }, "hotel_code": { "type": "string" }, "reservation_id": { "type": "string", "description": "our order code; the same for every revision of the reservation" }, "ota_name": { "type": "string" }, "agent": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "code", "phone", "email" ], "additionalProperties": false }, "created_at": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "revision_created_at": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "arrival_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "departure_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "currency": { "type": "string" }, "rooms": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "room_type_id": { "type": "string" }, "rate_plan_id": { "type": "string" }, "meal_type": { "type": [ "string", "null" ] }, "occupancy": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "children": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "infants": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "children_ages": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } }, "required": [ "adults", "children", "infants", "children_ages" ], "additionalProperties": false }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amount": { "type": "number", "minimum": 0, "description": "amount with two decimals (major unit)" } }, "required": [ "date", "amount" ], "additionalProperties": false } }, "amount": { "type": "number", "minimum": 0, "description": "amount with two decimals (major unit)" }, "guests": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "surname": { "type": "string" } }, "required": [ "name", "surname" ], "additionalProperties": false } } }, "required": [ "room_type_id", "rate_plan_id", "meal_type", "occupancy", "days", "amount", "guests" ], "additionalProperties": false } }, "amount": { "type": "number", "minimum": 0, "description": "amount with two decimals (major unit)" }, "price_type": { "type": "string", "enum": [ "net", "gross" ] }, "commission": { "description": "only with price_type gross", "type": "number", "minimum": 0 }, "tax_included": { "type": "boolean", "const": true }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "surname": { "type": "string" }, "nationality": { "type": "string" }, "email": { "description": "only when the connection forwards guest contact", "type": "string" }, "phone": { "description": "only when the connection forwards guest contact", "type": "string" } }, "required": [ "name", "surname" ], "additionalProperties": false }, "notes": { "type": "string" }, "payment_collect": { "type": "string", "const": "channel" }, "payment_type": { "type": "string", "const": "bank_transfer" }, "sales_source": { "type": "string", "enum": [ "site", "panel", "ts" ] }, "check_id": { "description": "availability check identifier, when a live check preceded the sale", "type": "string" }, "hold_id": { "type": "string" }, "test": { "type": "boolean" } }, "required": [ "schema_version", "event_type", "revision_id", "revision_no", "status", "hotel_code", "reservation_id", "ota_name", "agent", "created_at", "revision_created_at", "arrival_date", "departure_date", "currency", "rooms", "amount", "price_type", "tax_included", "payment_collect", "payment_type", "sales_source", "test" ], "additionalProperties": false, "description": "reservation notification (booking.new, booking.modified, booking.cancelled)", "examples": [ { "schema_version": "1.0", "event_type": "booking.new", "revision_id": "0192f6a0-3c1e-7b2a-9d4e-5f6a7b8c9d0e", "revision_no": 1, "status": "new", "hotel_code": "01HZXK4M8Q2W3E5R7T9Y", "reservation_id": "ABC-2700123", "ota_name": "Acente", "agent": { "name": "Acente", "code": "ABC", "phone": null, "email": null }, "created_at": "2027-05-20T09:30:00.000Z", "revision_created_at": "2027-05-20T09:30:00.000Z", "arrival_date": "2027-06-03", "departure_date": "2027-06-05", "currency": "TRY", "rooms": [ { "room_type_id": "DBL", "rate_plan_id": "BB", "meal_type": "BB", "occupancy": { "adults": 2, "children": 0, "infants": 0, "children_ages": [] }, "days": [ { "date": "2027-06-03", "amount": 4100.5 }, { "date": "2027-06-04", "amount": 4100.5 } ], "amount": 8201, "guests": [ { "name": "ALEX", "surname": "SAMPLE" }, { "name": "SAM", "surname": "SAMPLE" } ] } ], "amount": 8201, "price_type": "net", "tax_included": true, "customer": { "name": "ALEX", "surname": "SAMPLE" }, "payment_collect": "channel", "payment_type": "bank_transfer", "sales_source": "site", "test": false } ] }, "ConnectionEvent": { "type": "object", "properties": { "schema_version": { "type": "string", "const": "1.0" }, "event_type": { "type": "string", "enum": [ "connection.test", "ari.full_sync_requested" ] }, "request_id": { "type": "string" }, "hotel_code": { "type": "string" }, "sent_at": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "test": { "type": "boolean", "const": true } }, "required": [ "schema_version", "event_type", "request_id", "hotel_code", "sent_at" ], "additionalProperties": false, "description": "connection event: connection.test (test notification) or ari.full_sync_requested", "examples": [ { "schema_version": "1.0", "event_type": "connection.test", "request_id": "0192f6a0-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "hotel_code": "01HZXK4M8Q2W3E5R7T9Y", "sent_at": "2027-05-20T09:00:00.000Z", "test": true } ] }, "NotificationDecision": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "accepted", "rejected", "received" ] }, "cm_reservation_id": { "type": "string", "pattern": "^[A-Za-z0-9 ./_#-]{1,64}$" }, "reject_reason": { "type": "string", "enum": [ "full", "price", "date", "restriction", "mapping", "closed", "other" ] }, "note": { "type": "string", "maxLength": 1000 } }, "description": "channel manager response to a notification (2xx). Without a decision the delivery counts as received.", "examples": [ { "decision": "rejected", "reject_reason": "full", "note": "no availability" } ] }, "AvailabilityCheckRequest": { "type": "object", "properties": { "check_id": { "type": "string", "description": "the same for the same basket and stay; repeated on retry" }, "hotel_code": { "type": "string" }, "arrival_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "departure_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "currency": { "type": "string" }, "rooms": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "room_type_id": { "type": "string" }, "rate_plan_id": { "type": "string" }, "adults": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "children_ages": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "count": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "room_type_id", "rate_plan_id", "adults", "children_ages", "count" ], "additionalProperties": false } }, "expected_amount": { "type": "number", "minimum": 0, "description": "hotel amount we expect for the whole stay" } }, "required": [ "check_id", "hotel_code", "arrival_date", "departure_date", "currency", "rooms", "expected_amount" ], "additionalProperties": false, "description": "live availability check sent before the sale (availability_check)", "examples": [ { "check_id": "c1f0a2b3d4e5f6a7", "hotel_code": "01HZXK4M8Q2W3E5R7T9Y", "arrival_date": "2027-06-03", "departure_date": "2027-06-05", "currency": "TRY", "rooms": [ { "room_type_id": "DBL", "rate_plan_id": "BB", "adults": 2, "children_ages": [], "count": 1 } ], "expected_amount": 8201 } ] }, "AvailabilityCheckResponse": { "type": "object", "properties": { "available": { "type": "boolean" }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "available": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "sold_out", "price_changed", "restricted" ] } }, "required": [ "index", "available" ] } }, "amount": { "description": "current amount; a different value stops the sale as a price change", "type": "number" } }, "required": [ "available" ], "description": "channel manager response to a live availability check", "examples": [ { "available": true, "rooms": [ { "index": 0, "available": true } ], "amount": 8201 } ] }, "ErrorCode": { "type": "string", "enum": [ "invalid_json", "validation_failed", "unauthorized", "ip_not_allowed", "hotel_mismatch", "module_disabled", "not_found", "idempotency_conflict", "connection_closed", "already_decided", "payload_too_large", "unsupported_media_type", "all_items_rejected", "rate_limited", "internal_error", "service_unavailable" ] }, "WarningCode": { "type": "string", "enum": [ "unmapped_room_type", "unmapped_rate_plan", "read_only_rate_plan", "currency_mismatch", "sell_mode_mismatch", "occupancy_out_of_range", "invalid_amount", "invalid_restriction", "invalid_date_range", "past_date_ignored", "beyond_horizon_ignored", "duplicate_cell_in_request", "stale_sequence_ignored" ] } } } }