Инструкция по эксплуатации
Программного обеспечения «Apichannel»

ООО «Румлинк Отель АПИ»

1. Общие сведения

Программное обеспечение «Apichannel» — REST API-сервис для управления бронированием средств размещения (включая следующие типы: гостиницы, санатории, базы отдыха, кемпинги). Сервис принимает HTTP- запросы в формате JSON и возвращает ответы в формате JSON.
Базовый URL сервиса:
http://localhost:8090
(в production-окружении адрес предоставляется администратором)
Документация API (Swagger UI):
http://localhost:8090/swagger/index.html
Swagger UI позволяет просматривать все эндпоинты и выполнять тестовые запросы прямо в браузере.

2. Аутентификация

Все эндпоинты REST API требуют передачи API-ключа контрагента. Ключ передаётся в заголовке каждого запроса (далее в листинге представлен демо-ключ, который позволяет выполнить проверку сервиса в тестовом репозитории):
X-API-Key: demo-api-key-aabbccddeeff001122334455
API-ключ выдаётся администратором системы при подключении контрагента. При отсутствии или неверном значении ключа сервис возвращает ответ:
HTTP 403
{ "message": "Access denied" }
Важно: не передавайте API-ключ в URL или теле запроса — только в заголовке X-API-Key

3. Модуль 1 — Получение номеров и тарифов

Модуль позволяет получить список номеров и тарифных планов для указанного средства размещения.
[GET] /api/rooms-and-rate-plans – получить номера и тарифы средства размещения
Параметры запроса
Пример запроса
GET /api/rooms-and-rate-plans?hotel_id=85430
X-API-Key: demo-api-key-aabbccddeeff001122334455
Пример успешного ответа (HTTP 200)
{
"roomsAndRatePlans": [
{
"room_id": "101",
"room_name": "Стандартный двухместный",
"occupancies": [{ "occupancyId": 1, "occupancy": 2 }],
"rate_plans": [
{ "rate_id": "RP01", "rate_plan_name": "Завтрак включён",
"is_netto_price": true }
]
}
]
}
Возможные ошибки
— 400 — параметр hotel_id не передан 

— 403 — неверный API-ключ 

— 417 — hotel_id не является числом или равен нулю 

— 422 — средство размещения не подключёно к системе 

— 500 — внутренняя ошибка сервера

4. Модуль 2 – Управление заказами

Модуль обеспечивает полный жизненный цикл заказа: создание, получение, изменение, подтверждение и отмену.
Статусы заказа:
— NEW — заказ создан, ожидает обработки 

— CONFIRMED — заказ подтверждён средством размещения 

— MODIFIED — заказ изменён 

— CANCELLED — заказ отменён

4.1 Создание заказа

[POST] /api/orders – создать новый заказ
Параметры запроса
Пример запроса
POST /api/orders
X-API-Key: demo-api-key-aabbccddeeff001122334455
Content-Type: application/json
{
"hotel_id": "85430",
"order_id": "EXT-00123"
}
Пример успешного ответа (HTTP 200)
{
"order_id": "EXT-00123",
"hotel_id": "85430",
"status": "NEW",
"paymentMethod": "PREPAY",
"created": "2025-03-01T10:00:00Z",
"roomStays": []
}

4.2 Получение заказа по ID

[GET] /api/orders/{id} – получить заказ по идентификатору
Параметры запроса
Пример запроса
GET /api/orders/42
X-API-Key: demo-api-key-aabbccddeeff001122334455

4.3 Список заказов

[GET] /api/orders – получить список всех заказов контрагента
Параметры запроса
Пример запроса
GET /api/orders
X-API-Key: demo-api-key-aabbccddeeff001122334455

4.4 Изменение заказа

[PATCH] /api/orders/{id} - изменить существующий заказ
Параметры запроса
Пример запроса
PATCH /api/orders/42
X-API-Key: demo-api-key-aabbccddeeff001122334455
Content-Type: application/json
{ "hotel_id": "85430" }

4.5 Подтверждение заказа

[POST] /api/orders/{id}/confirm – подтвердить заказ
Параметры запроса
Пример запроса
POST /api/orders/42/confirm
X-API-Key: demo-api-key-aabbccddeeff001122334455
Content-Type: application/json
{ "ext_order_id": "EXT-00123", "token": "abc123" }
Примечание: при конфликте данных (статус заказа изменился с момента последнего получения) сервис вернёт HTTP 409. Необходимо повторно получить актуальное состояние заказа и затем подтвердить.

4.6 Отмена заказа

[PATCH] /api/orders/{id}/cancel – отменить заказ
Параметры запроса
Пример запроса
PATCH /api/orders/42/cancel
X-API-Key: demo-api-key-aabbccddeeff001122334455
Content-Type: application/json
{ "hotel_id": "85430" }

5. Модуль 3 – Обновление данных

Модуль предназначен для поставщиков, передающих актуальные цены, квоты и ограничения по номерам средств размещения.
[POST] /api/hotels/update – обновить цены, квоты и ограничения
Параметры запроса
Пример запроса
POST /api/hotels/update
X-API-Key: demo-api-key-aabbccddeeff001122334455
Content-Type: application/json
{
"hotels_info": [{
"hotel_id": 85430,
"description": {
"prices": [{ "date": "2025-06-01", "room_id": 1, "rate_id": 1, "price": 4500.00 }],
"quotas": [{ "date": "2025-06-01", "room_id": 1, "quota": 5 }],
"restrictions": [{ "date": "2025-06-01", "room_id": 1, "min_nights": 2 }]
}
}]
}
При успешной обработке сервис возвращает HTTP 200. Данные публикуются в соответствующие Kafka-топики для дальнейшей обработки системой.

6. Модуль 4 – Legacy API (connect.php)

Модуль обеспечивает интеграцию по альтернативным протоколам путем маршрутизации запросов на единый эндпоинт с указанием метода в теле запроса.
[POST] /api/connect.php – единая точка входа Legacy API
Параметры запроса (тело JSON)
Доступные методы и их REST-эквиваленты
Пример запроса
POST /api/connect.php
Content-Type: application/json
{
"key": "demo-api-key-aabbccddeeff001122334455",
"method": "getRoomsAndRatePlans",
"message": { "hotel_id": 85430 }
}
Рекомендация: для новых интеграций используйте REST API (модули 1- 3). Legacy API поддерживается для совместимости с уже подключёнными партнёрами.

7. Модуль 5 – Служебные эндпоинты

7.1 Проверка работоспособности

[GET] /healthz – статус сервиса и доступность БД
Используется для мониторинга и проверки готовности сервиса. Аутентификация не требуется.
Пример запроса и ответа
GET /healthz
HTTP 200 { "status": "ok" }
Если база данных недоступна – сервис вернёт HTTP 503.

7.2 Метрики Prometheus

[GET] /metrics – метрики в формате Prometheus
Эндпоинт предоставляет метрики HTTP-запросов и операций с базой данных в формате Prometheus. Доступ рекомендуется ограничить на уровне сетевых политик.
GET http://localhost:9090/metrics

8. Коды ответов и обработка ошибок

Все ответы сервиса содержат стандартные HTTP-коды. В случае ошибки тело ответа содержит JSON с полем message:
Пример ответа об ошибке
HTTP 403
{
"message": "Access denied"
}
При получении ошибки 500 или 503 рекомендуется повторить запрос через 30−60 секунд. Если ошибка повторяется — обратитесь в техническую поддержку по адресу helpdesk@apichannel.ru, указав:
— метод и URL запроса 

— тело запроса (без API-ключа) 

— полученный ответ 

— временную метку запроса (UTC)