API 2FA Service — обзор
API 2FA Service — Basic Auth, отдельный ключ, эндпоинты для отправки, проверки и статуса
Коротко: API 2FA Service — отдельный интерфейс для подключения 2FA к вашему сайту. Отличается от OMNI API: аутентификация через Basic Auth, отдельный ключ интеграции, собственные эндпоинты.
Кому подходит
- Роль: Разработчик
- Уровень: Опытный
Что это
API 2FA Service — интерфейс для интеграции 2FA с вашим сайтом или сервисом через раздел 2FA Service. В отличие от OMNI API, этот API:
- Использует отдельный ключ интеграции — он выдаётся в разделе 2FA Service и не связан с общим API-ключом из «API Подключения».
- Аутентифицируется через Basic Auth — не через заголовок
X-API-Key. - Работает с URL интеграции — он выдаётся при настройке и может отличаться от базового URL OMNI API.
- Имеет собственные эндпоинты для отправки, проверки кода и статуса запроса.
Чем отличается от OMNI API
| Параметр | OMNI API | API 2FA Service |
|---|---|---|
| Аутентификация | Заголовок X-API-Key | Basic Auth |
| Ключ | Общий API-ключ из раздела «API Подключения» | Отдельный ключ интеграции из 2FA Service |
| URL для отправки | https://web.otpcod.ru/api/v1/messages | URL интеграции из настроек 2FA Service |
| Проверка кода | — | POST /api/v1/2fa/verify |
| Статус запроса | GET /api/v1/edrs | GET /api/v1/2fa/requests/{requestId} |
Тестовое подключение бесплатно — договор не требуется, мы предоставляем баланс для тестирования.
Перед началом
- У вас есть имя отправителя со статусом Активно.
- У вас создана 2FA-интеграция в разделе 2FA Service.
- У вас есть API-ключ интеграции и URL интеграции.
Как настроить 2FA-интеграцию →
Цикл работы
API 2FA работает в три шага:
Вы отправляете номер получателя на URL интеграции. Платформа генерирует код, отправляет его через канал и возвращает requestId.
Пользователь получает код в SMS или другом канале и вводит его на вашем сайте.
Вы отправляете requestId и code на /api/v1/2fa/verify. Платформа возвращает результат — код верный или нет.
Опционально можно:
- Получать обратные вызовы о статусах через вебхук.
- Проверять статус запроса по
requestIdв любой момент.
Методы API
| Что нужно | Куда идти |
|---|---|
| Отправка и проверка кода — curl-примеры, параметры, ответы | Принцип работы 2FA: на стороне платформы → |
| Проверка статуса запроса — curl-пример, поля ответа | Раздел «Проверка статуса запроса» ниже |
| Обратные вызовы — формат данных, статусы, обработка | Получение обратных вызовов при 2FA → |
Проверка статуса запроса
Метод возвращает данные о ранее отправленном 2FA-запросе по requestId.
Эндпоинт
GET /api/v1/2fa/requests/{requestId}
Параметры
| Параметр | Что указать |
|---|---|
requestId | Идентификатор, полученный при отправке кода |
| API-ключ | Передаётся через Basic Auth — ключ интеграции, пароль пустой |
Пример запроса
curl https://<домен OTP-сервиса>/api/v1/2fa/requests/<requestId> \
-u <API-ключ интеграции>Что в ответе
| Поле | Что означает |
|---|---|
id | Идентификатор запроса |
number | Номер получателя |
rate | Стоимость |
billable | Признак тарификации |
status | Статус: SUBMIT, SENT, DELIVERED и другие |
sender | Имя отправителя интеграции |
goals | Цели запроса, например NUMBER_VERIFIED |
createdAt | Время создания запроса |
payload | Дополнительные данные |
Успешный ответ:
{
"id": "<requestId>",
"number": "<номер>",
"rate": 0.0248,
"billable": null,
"status": "SUBMIT",
"sender": "<имя отправителя>",
"goals": ["NUMBER_VERIFIED"],
"createdAt": 1234567891011,
"payload": {
"number": "<номер>"
}
}Статус ответа: 200 OK.
Когда использовать
- Диагностика проблем — если пользователь не получил код, проверьте статус запроса.
- Аудит — отследить путь конкретного кода.
- Биллинг — узнать стоимость запроса.
Если нужна генерация на своей стороне
API 2FA Service работает только с режимом «На стороне платформы» — платформа сама генерирует и проверяет код.
Если вам нужна генерация и проверка кода на своей стороне — используйте режим Умный шлюз.
Результат
Вы понимаете, чем API 2FA отличается от OMNI API, знаете эндпоинты для отправки, проверки и мониторинга кода.
Частые проблемы
Причина: неверный API-ключ интеграции или неверная схема аутентификации.
Решение: проверьте, что используете Basic Auth с ключом интеграции из раздела Данные для интеграции. Не используйте заголовок X-API-Key — он не подходит для 2FA-эндпоинтов.
Причина: неверный requestId или запрос с истёкшим сроком хранения.
Решение: проверьте, что requestId получен из ответа на отправку кода и не содержит опечаток.
Причина: номер получателя недоступен или имя отправителя неактивно.
Решение: проверьте номер и статус имени отправителя.
Причина: неверный requestId или code, или истёк срок действия кода.
Решение: убедитесь, что requestId получен из ответа на отправку, а code — тот, который ввёл пользователь.
Причина: сообщение ещё не доставлено или не проверено.
Решение: подождите и повторите запрос. Статусы обновляются по мере обработки — от SUBMIT до SENT, DELIVERED или VERIFIED.
Причина: API 2FA Service работает только с генерацией на стороне платформы.
Решение: используйте режим Умный шлюз.
См. также
Нужна помощь?
- OTP-коды: support@otpcod.ru