Xizmat Safari (XF) — интеграция МВД ↔ E-mehmon

API двусторонней интеграции системы служебных командировок Xizmat Safari (МВД, *.imv.uz) с E-mehmon: бронирование гостиниц под госкомандировки, формирование и подписание договора, подтверждение заселения.

В отличие от CRM Hotel API, XF — прямая интеграция: Xizmat Safari ходит напрямую в E-mehmon (POST /api/xf-api), без промежуточного шлюза.

• Прод-домен: emehmon.uz → POST https://emehmon.uz/api/xf-api.
• Песочница: sandbox-api.emehmon.uz — см. sandbox.md.

Направления обмена

Xizmat Safari (МВД)                         E-mehmon
        │                                          │
        │ ①  POST /api/xf-api  {method,data,...}    │
        │ ─────────────────────────────────────►   │
        │ ◄─────────────────────────────────────   │  {data,message,code}
        │                                          │
        │ ②  уведомления о статусе/договоре/QR       │
        │ ◄─────────────────────────────────────   │

① Входящие (МВД → E-mehmon) — единое окно POST /api/xf-api, 7 методов (см. ниже).

② Исходящие (E-mehmon → МВД) — E-mehmon отправляет уведомления на согласованные с МВД endpoint'ы по ходу жизненного цикла брони:

Транспорт и аутентификация

POST /api/xf-api, Content-Type: application/json. Две независимые проверки:

1. IP-allowlist

Запросы принимаются только с заранее согласованных IP-адресов гейтвея МВД. Запрос с неразрешённого адреса → 401.

2. Подпись hash

Поле hash в теле запроса — SHA1 от строки id_request, секретного ключа и method:

hash = sha1(id_request + "-" + secret + "-" + method)

secret — выданный вам ключ. Сравнение регистронезависимое (hash передавайте в lowercase).

Формат запроса/ответа

Запрос:

{
  "method": "hotel-list",
  "id_request": "req-001",
  "data": { "region_id": 1703, "page": 1 },
  "hash": "<см. выше>"
}

Ответ (единый конверт):

{ "data": { /* ... */ }, "message": "success", "code": 200 }

Обязательные поля запроса: method, data, hash, id_request (отсутствие любого → 401).

Методы

region_id/district_id в запросах — это коды COATO/SP (как в официальном классификаторе), а не внутренние id. room_id в make-booking — это значение id из массива rooms[] ответа hotel-info.

Идемпотентность

Каждый запрос несёт уникальный id_request. Повторный запрос с тем же id_request, по которому уже сформирован ответ, возвращает тот же ответ без повторной обработки (защита от сетевых ретраев).

Жизненный цикл брони

make-booking → status=new
   │  (отель принимает/отклоняет бронь)
   ├─ accept  → status=accepted   → POST /emehmon/response/  (notifyStatusChange)
   └─ reject  → status=rejected   → POST /emehmon/response/  (notifyStatusChange)
        │
   МВД формирует договор → booking-doc-status (Confirmed)
        │
   E-mehmon GET emehmon-preview/ → забирает договор (contract_hashing, document)
        │
   договор Accepted → POST /ehotel/booking_accept/  (notifyContractStatus)
        │
   подтверждение заселения → POST emehmon-confirm/ (QR + PINFL + фото)
        │                     → contract_status=Accepted, листок создан
   гость проживает
        │
   выезд гостя (dateVisitOff) → POST emehmon-checkout/ (contract_uuid + datetime)

Заселение создаёт регистрацию (листок) и запускает соответствующие госуведомления. Выезд (confirmCheckout) срабатывает автоматически при выселении гостя в кабинете. В песочнице эти побочные эффекты отключены/застаблены — см. sandbox.md.

Песочница Xizmat Safari

Песочница доступна снаружи как sandbox-api.emehmon.uz, где интеграторы МВД тестируют интеграцию Xizmat Safari (/api/xf-api) на фейковых данных, не затрагивая прод и не вызывая реальные госуведомления.

[!NOTE] Статус (2026-05-26): развёрнута и работает. Приём hotel-list через sandbox-api.emehmon.uz/api/xf-api → 200; дашборд /sandbox/xf + эмуляция действий отеля проверены; документация — /sandbox/xf/docs. Endpoint, тестовый ключ и эта документация переданы интеграторам.

Чем отличается от прода

Песочница повторяет реальный контракт /api/xf-api — отличаются только данные и отключённые/застабленные побочные эффекты.

Доступ

• Endpoint: POST https://sandbox-api.emehmon.uz/api/xf-api
• IP-allowlist: ваш IP должен быть согласован с администратором. Иначе 401.
• Тестовый ключ: администратор выдаёт вам тестовый ключ (secret). Подпись — hash в теле (SHA1, см. README).

Фейковые данные

Администратор засевает в песочнице тест-данные:

• тест-отель «XF Sandbox Hotel» в регионе с COATO;
• тип номера + номера 101/102;
• прайс;
• тест-бронь (status=new) — для booking-single / cancel-booking / booking-doc-status.

Вам передают готовые значения: hotel_id, region_id (COATO для hotel-list), district_id (sp_id), price_id (= room_id для make-booking), booking_id и готовую curl-команду smoke-теста с валидным SHA1-hash.

Справочники (регионы/районы с COATO, типы номеров) — настоящие коды.

Дашборд и эмуляция действий — /sandbox/xf

https://sandbox-api.emehmon.uz/sandbox/xf:

• статус тест-отеля (регион/район/COATO, сертификат, номера, price_id);
• текущие настройки песочницы;
• журнал входящих запросов (метод, id_request, код ответа, IP);
• XF-брони с кнопками эмуляции действий отеля — то, что на проде делается в кабинете:

new ──[Принять]──► accepted ──[Договор: Accepted]──► (Accepted)
          │                                              │
       [Отклонить] → rejected            [Забрать договор] → договор сохранён
                                                           │
                                              [Подтвердить заселение] → QR

Каждая кнопка прогоняет тот же сценарий, что прод-кабинет, и шлёт соответствующее уведомление в МВД — так интегратор прогоняет полный двусторонний цикл без логина в кабинет.

Сброс

На дашборде кнопка «Сбросить» очищает журнал входящих и XF-брони; тест-отель, номера, прайс и справочники остаются — удобно начать тесты с чистого листа.

Примеры запросов

Python (рабочий SHA1):

import hashlib, json, requests

BASE   = "https://sandbox-api.emehmon.uz/api/xf-api"
SECRET = "<ваш тестовый ключ>"

def call(method, data, id_request):
    h = hashlib.sha1(f"{id_request}-{SECRET}-{method}".encode()).hexdigest()
    body = {"method": method, "id_request": id_request, "data": data, "hash": h}
    r = requests.post(BASE, json=body, verify=False)  # verify=False — если самоподписанный
    print(r.status_code, json.dumps(r.json(), ensure_ascii=False, indent=2))
    return r.json()

# 1. Список отелей региона (region_id — COATO, переданный администратором)
call("hotel-list", {"region_id": 1703, "page": 1}, "req-001")

# 2. Создать бронь (room_id = price_id из hotel-info)
call("make-booking", {
    "hotel_id": 123, "checkin_date": "2026-06-01", "checkout_date": "2026-06-03",
    "organization_name": "Test Org", "organization_tin": "999999999",
    "contact_phone": "+998900000000", "rooms_qty": 1,
    "doc_number": "CMD-001", "pinfl": "00000000000000",
    "dtb": "1990-01-01", "staffname": "Test Xodim", "room_id": 456,
}, "req-002")

curl (hash вычислить заранее: echo -n "req-001-<SECRET>-hotel-list" | sha1sum):

curl -sk https://sandbox-api.emehmon.uz/api/xf-api \
  -H 'Content-Type: application/json' \
  -d '{"method":"hotel-list","id_request":"req-001","data":{"region_id":1703,"page":1},"hash":"<sha1>"}'

Поведение callback'ов в песочнице

По запросу администратор включает отправку уведомлений (callback'ов) в ваш dev-контур МВД. В песочнице они отправляются синхронно (в проде часть из них идёт асинхронно), а забор договора и подтверждение заселения работают как на проде. Если callback'и не нужны — их можно отключить (останется только приём входящих запросов).

Ограничения

• Проверка иностранцев и KOGG застаблены — в песочнице нельзя воспроизвести реальный отказ по иностранцу.
• Госуведомления (СГБ/ГНИ/ГТК) и запись в аналитику не выполняются.
• Для подписи используйте SHA1 (см. README).
• Данные песочницы не персистентны — администратор может их сбросить.