{ "openapi": "3.1.0", "info": { "title": "Hickmet — данные для ИИ-агентов", "version": "2026-08-28", "description": "Только чтение: поиск вылетов на Умру и Хадж, программы туров, отели и магазин для паломников. Бронирование и оплату совершает человек на сайте — в каждом ответе есть booking_url, который открывает форму с уже заполненными датами и составом группы.", "contact": { "name": "Hickmet", "url": "https://hickmet.kz/ru/contact", "email": "ceo@hickmet.kz" } }, "servers": [ { "url": "https://hickmet.kz" } ], "paths": { "/api/agent/cities": { "get": { "operationId": "listDepartureCities", "summary": "Города вылета", "description": "Города, из которых действительно есть вылеты. Идентификатор отсюда передаётся в departure_city_id.", "parameters": [ { "name": "lang", "in": "query", "description": "Язык описаний и локаль в ссылках. По умолчанию ru. Где перевода нет, приходит русский текст.", "schema": { "type": "string", "enum": [ "ru", "kk", "en" ], "default": "ru" } } ], "responses": { "200": { "description": "Список городов", "content": { "application/json": { "schema": { "type": "object", "properties": { "departure_cities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "airport_code": { "type": "string", "nullable": true } } } } } } } } }, "404": { "description": "Ничего не найдено по такому идентификатору.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string" } } } } } } } }, "502": { "description": "Каталог временно недоступен.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string" } } } } } } } } } } }, "/api/agent/tours": { "get": { "operationId": "searchDepartures", "summary": "Поиск вылетов", "description": "Один тур продаётся несколькими вылетами, и сайт адресует каждый по идентификатору ВЫЛЕТА. Две строки с одним названием и разными датами — это норма, а не дубль.", "parameters": [ { "name": "lang", "in": "query", "description": "Язык описаний и локаль в ссылках. По умолчанию ru. Где перевода нет, приходит русский текст.", "schema": { "type": "string", "enum": [ "ru", "kk", "en" ], "default": "ru" } }, { "name": "departure_city_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "adults", "in": "query", "description": "Взрослые, от 18 лет.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "teens", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "children", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Найденные вылеты", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "example": "KZT" }, "generated_at": { "type": "string", "format": "date-time" }, "total": { "type": "integer" }, "departures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Идентификатор вылета; он же в адресе страницы тура." }, "tour": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "example": "Умра" }, "duration_days": { "type": "integer", "nullable": true } } }, "departure_city": { "type": "string", "nullable": true }, "departure_date": { "type": "string", "format": "date" }, "return_date": { "type": "string", "format": "date", "nullable": true }, "price_from": { "type": "object", "description": "Цена за одного человека, в тенге. null — цена не задана.", "properties": { "adult": { "type": "number", "nullable": true }, "teen": { "type": "number", "nullable": true }, "child": { "type": "number", "nullable": true } } }, "url": { "type": "string", "format": "uri" }, "booking_url": { "type": "string", "format": "uri", "description": "Ссылка для человека: форма откроется заполненной." } } } } } } } } }, "404": { "description": "Ничего не найдено по такому идентификатору.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string" } } } } } } } }, "502": { "description": "Каталог временно недоступен.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string" } } } } } } } } } } }, "/api/agent/tours/{schedule_id}": { "get": { "operationId": "getDeparture", "summary": "Вылет целиком", "description": "Программа по дням, что входит в цену и что нет, отели и места. Поле bookable — единственное, на что стоит смотреть, прежде чем звать человека бронировать.", "parameters": [ { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lang", "in": "query", "description": "Язык описаний и локаль в ссылках. По умолчанию ru. Где перевода нет, приходит русский текст.", "schema": { "type": "string", "enum": [ "ru", "kk", "en" ], "default": "ru" } } ], "responses": { "200": { "description": "Вылет", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "departure": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "bookable": { "type": "boolean" }, "departure_date": { "type": "string", "format": "date" }, "return_date": { "type": "string", "format": "date", "nullable": true }, "seats": { "type": "object", "description": "Вместимость, а не живой остаток: не говорите, что мест нет, опираясь только на это.", "properties": { "total": { "type": "integer" }, "available": { "type": "integer" } } } } }, "tour": { "type": "object" }, "url": { "type": "string", "format": "uri" }, "booking_url": { "type": "string", "format": "uri", "nullable": true } } } } } }, "404": { "description": "Ничего не найдено по такому идентификатору.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string" } } } } } } } }, "502": { "description": "Каталог временно недоступен.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string" } } } } } } } } } } }, "/api/agent/hotels": { "get": { "operationId": "listHotels", "summary": "Отели", "description": "Поле stars — звёздность отеля, до пяти. Оценка гостей с Booking.com (guest_score, из десяти) приходит только в карточке отеля.", "parameters": [ { "name": "lang", "in": "query", "description": "Язык описаний и локаль в ссылках. По умолчанию ru. Где перевода нет, приходит русский текст.", "schema": { "type": "string", "enum": [ "ru", "kk", "en" ], "default": "ru" } } ], "responses": { "200": { "description": "Отели" }, "404": { "description": "Ничего не найдено по такому идентификатору.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string" } } } } } } } }, "502": { "description": "Каталог временно недоступен.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string" } } } } } } } } } } }, "/api/agent/hotels/{hotel_id}": { "get": { "operationId": "getHotel", "summary": "Отель", "description": "Координаты, расстояние и время пешком до Харама, удобства.", "parameters": [ { "name": "hotel_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lang", "in": "query", "description": "Язык описаний и локаль в ссылках. По умолчанию ru. Где перевода нет, приходит русский текст.", "schema": { "type": "string", "enum": [ "ru", "kk", "en" ], "default": "ru" } } ], "responses": { "200": { "description": "Отель" }, "404": { "description": "Ничего не найдено по такому идентификатору.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string" } } } } } } } }, "502": { "description": "Каталог временно недоступен.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string" } } } } } } } } } } }, "/api/agent/products": { "get": { "operationId": "listProducts", "summary": "Магазин для паломников", "description": "Цены магазина хранятся сразу в тенге, без пересчёта — в отличие от цен туров.", "parameters": [ { "name": "lang", "in": "query", "description": "Язык описаний и локаль в ссылках. По умолчанию ru. Где перевода нет, приходит русский текст.", "schema": { "type": "string", "enum": [ "ru", "kk", "en" ], "default": "ru" } } ], "responses": { "200": { "description": "Товары" }, "404": { "description": "Ничего не найдено по такому идентификатору.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string" } } } } } } } }, "502": { "description": "Каталог временно недоступен.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string" } } } } } } } } } } } } }