Перейти к основному содержимому

Лучшие практики

Короткий чек-лист для устойчивой интеграции в проде.

Вебхуки против опроса​

  • Вебхуки — основной способ узнавать результат: быстро и без лишних запросов. Обязательно проверяйте подпись и делайте обработку идемпотентной по (request_id, event).
  • Опрос GET /v1/verify/{request_id} — как страховка (если вебхук не дошёл) и как источник истины при расхождениях. Разумный интервал — раз в 2–3 секунды до терминального статуса, не чаще.

Не показывайте ввод кода вслепую​

Код нужен не всегда. Для reverse_flash_call его нет вовсе; для mts_id он появляется только при откате на SMS-OTP. Ориентируйтесь на сигнал, а не на метод:

  • слушайте вебхук verification.code_required, или
  • опрашивайте awaiting_code в GET /v1/verify/{request_id} — true означает «сейчас нужен код».

Жёстко зашитый экран «введите код» ломает mts_id. Подробнее — в Потоках подтверждения.

Помните про асинхронность mts_id​

Для mts_id ответ POST /v1/verify/check — status: sent, а не verified: код ретранслируется оператору, итог приходит чуть позже вебхуком или виден при опросе. Не считайте check финальным шагом.

Не зашивайте тарифы в код​

Цены меняются. Читайте их в рантайме через GET /v1/prices (для интеграторов) или GET /dashboard/prices (для кабинета) и показывайте актуальные значения. Ответ содержит только клиентскую цену, без внутренних издержек.

Обрабатывайте ошибки по error_code​

Ошибки — это RFC-7807 с устойчивым полем error_code. Ветвитесь по нему, а не по тексту detail:

error_codeЧто делать
insufficient_balance (402)Пополнить баланс; следить за ним через GET /v1/balance
invalid_code (400)Показать attempts_remaining, дать ввести ещё раз
not_pending (409)Сессия уже завершена/истекла или код отправлен слишком рано
not_found (404)Неизвестный request_id для вашего аккаунта
rate_limit_exceeded (429)Подождать Retry-After и повторить
validation_error (400)Проверить формат полей (номер в E.164, код 4–8 цифр)

При неуспешной инициации (4xx/5xx на POST /v1/verify) списание не происходит.

Мелочи, которые экономят время​

  • Номера — в E.164 (+7…). Нормализуйте перед отправкой.
  • TTL сессии — expiry_seconds (по умолчанию 300, максимум 600). После истечения статус expired.
  • request_id — ваш ключ для статуса, check и дедупликации вебхуков; сохраните его сразу.
  • Секрет — только на сервере. api_secret не должен попадать в браузер или мобильное приложение; ротация ключей — в кабинете.