SPEC-INT-01. Интеграции
Уточнение от 12.11.2026: демонстрационные интеграции доступа и верификации. При расхождении применяется уточнение.
1. Назначение
Документ задаёт контракты обмена с внешними системами гостевого контура, поведение при сбоях, идемпотентность и наблюдаемость. Конкретные провайдеры, кроме карт, не выбраны (ADAPT-001 B-027): контракт описан как порт системы, адаптер под провайдера реализует его.
2. Scope
Входит: платёжный провайдер, онлайн-касса, Госуслуги (ЕСИА), SMS-шлюз, push-шлюзы, Яндекс MapKit и геокодер, внешние навигаторы, Сервис доступа (только контракт порта), Админ-панель (события каталога). Не входит: протоколы замков, IoT, контроллеры.
3. Разделы, специфичные для типа
3.1. Платёжный провайдер (порт PaymentGateway)
| Операция |
Вход |
Выход |
Ошибки |
tokenizeCard (через SDK/веб-форму провайдера) |
— |
token, mask, brand |
CARD_DECLINED, 3DS_FAILED |
charge |
token, amount, idempotencyKey, bookingId |
providerRef, status |
INSUFFICIENT_FUNDS, DECLINED, TIMEOUT |
hold / releaseHold / captureHold |
token, amount, idempotencyKey |
holdRef |
HOLD_NOT_SUPPORTED (СБП) |
refund / void |
providerRef, amount |
status |
ALREADY_REFUNDED |
webhook payment.status |
подпись HMAC |
— |
неверная подпись → 401, событие отброшено |
Требования к провайдеру: холд с последующим списанием или снятием, рекуррентные списания по токену (продление, просрочка), СБП, Apple Pay, Google Pay, Mir Pay, 3-D Secure 2, сплит — заделом (B-027).
3.2. Онлайн-касса (порт FiscalRegistrar)
registerReceipt(paymentId, items[], customerContact) → receiptUrl. Признак расчёта: «приход» (аренда, услуги, продление), «возврат прихода» (возврат). Холд залога не фискализируется; удержание залога — «приход» (B-005).
3.3. Госуслуги — ЕСИА (порт IdentityVerifier)
Решение заказчика 11.11.2026 (ADAPT-001 B-035): подтверждение личности выполняется через ЕСИА вместо KYC-провайдера. Фото документов и селфи система не получает.
Протокол — OAuth 2.0 Authorization Code с PKCE и OpenID Connect; сеть регистрируется в ЕСИА как информационная система-потребитель, запросы подписываются ключом ГОСТ Р 34.10-2012 через сертифицированное СКЗИ на стороне сервера. Авторизация проходит во встроенном браузере приложения (SPEC-UI-02, C-05); client_secret и обмен кода на токен — только на сервере (модуль Identity, esia-identity-service).
| Операция |
Вход |
Выход |
Ошибки |
startAuthorization |
guestId, redirectUri |
authorizationUrl, state (одноразовый, 10 мин), codeVerifier хранится на сервере |
— |
callback redirectUri |
code, state |
accessToken, idToken (sub = esia_oid) |
access_denied (гость отменил вход) → «Вход отменён»; неверный или просроченный state → 400, попытка отброшена |
fetchPerson |
accessToken, esia_oid |
ФИО, дата рождения, паспорт РФ (серия, номер, дата выдачи, кем выдан), признак trusted (подтверждённая учётная запись) |
trusted = false → «Учётная запись Госуслуг не подтверждена»; нет паспорта РФ в профиле → та же причина; TIMEOUT → тост «Повторить» |
Запрашиваемые scope: openid, fullname, birthdate, id_doc; признак подтверждённости учётной записи читается из ответа fetchPerson (trusted). Номер телефона берётся из входа по SMS-коду, а не из ЕСИА.
Результат проверки синхронный: состояние «На проверке» отсутствует. Токены ЕСИА не сохраняются после получения данных; сохраняются esia_oid, уровень доверия и время подтверждения (SPEC-DATA-01). Таймаут вызова ЕСИА — 15 с, 1 повтор; затем состояние «Ошибка» на C-05 с «Повторить» (SR-06#2).
3.4. SMS, push, карты
| Система |
Контракт |
Сбой |
| SMS-шлюз |
send(phone, text); текст «Rest&Go: код 123456. Никому не сообщайте» + Web OTP-хвост |
2 повтора через 5 с; затем тост на C-02 (TC-007-neg); резервный шлюз — задел |
| APNs, FCM, RuStore Push |
send(deviceToken, payload{type, bookingId, title, body}) |
невалидный токен удаляется; доставка не гарантирована — каждое событие дублируется в C-41 |
| Яндекс MapKit |
SDK подложки, геокодер, routeTime(from, to, mode) |
без времени в пути — показывается только расстояние |
| Навигаторы |
deeplink yandexnavi://, yandexmaps://, dgis://, maps://, geo: |
без приложений — веб-ссылка (SR-15#3) |
3.5. Админ-панель (входящие события)
hotel.published, hotel.paused, capsule.status_changed{client_status, free_at, last_cleaned_at}, tariff.updated, review.replied, deposit.released, deposit.retained{reason}. Доставка — outbox → брокер, at-least-once.
3.6. Сервис доступа (порт AccessService, механика вне рамок)
| Операция |
Вход |
Выход |
open |
bookingId, capsuleId, deviceId |
opened | error{code} за ≤ 10 с |
getBackupCode |
bookingId |
code (6 цифр), validFrom, validTo |
revoke |
bookingId |
ok (вызывается при completed, cancelled, no_show) |
Технология (BLE, NFC, QR, PIN), офлайн-режим и подписи — внутри Сервиса доступа и не входят в комплект. Для стенда — эмулятор (SPEC-TEST-01).
3.7. Идемпотентность и dedup
Каждый мутирующий вызов к провайдерам несёт idempotencyKey = sha256(bookingId + operation + attempt-group). Входящие webhook и события дедуплицируются по eventId (таблица обработанных событий, хранение 7 дней).
3.8. Безопасность между системами
mTLS или подпись HMAC на webhook; IP-allowlist провайдеров; секреты — SPEC-SEC-01 §3.4.
3.9. Наблюдаемость
X-Correlation-Id от мобильного приложения проходит через BFF, Core и в метаданные вызовов провайдеров; метрики на каждый порт: доля ошибок, p95, число ретраев; алерт при доле ошибок оплаты > 5 % за 5 мин.
4. Связь с требованиями
SR-03, SR-06, SR-07, SR-10, SR-15, SR-24, SR-31, SR-37, SR-51.
5. Связь с другими SPEC
depends-on: SPEC-ARCH-01.
6. Verification
TC-007, TC-015, TC-016, TC-018, TC-054, TC-065, TC-066, TC-096 и парные -neg — против эмуляторов SPEC-TEST-01. Интеграционные contract-TC против sandbox провайдеров — после выбора провайдеров (README, «Известные пробелы»).