--- title: API 2FA Service — обзор description: API 2FA Service — Basic Auth, отдельный ключ, эндпоинты для отправки, проверки и статуса --- > **For AI agents:** the complete documentation index is at [llms.txt](https://docs.mydialogi.ru/llms.txt). Append `.md` to any page URL for its markdown version. > **Коротко:** 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}` | **Тестовое подключение бесплатно** — договор не требуется, мы предоставляем баланс для тестирования. [Начните с быстрого старта →](https://iba-platform.jamdesk.app/02-otp/00-start-here/otp-003-quick-start) ## Перед началом - [ ] У вас есть имя отправителя со статусом **Активно**. - [ ] У вас создана 2FA-интеграция в разделе **2FA Service**. - [ ] У вас есть **API-ключ интеграции** и **URL интеграции**. [Как настроить 2FA-интеграцию →](https://iba-platform.jamdesk.app/02-otp/01-turnkey/otp-102-setup-2fa) ## Цикл работы API 2FA работает в три шага: ### 1. Отправка кода Вы отправляете номер получателя на URL интеграции. Платформа генерирует код, отправляет его через канал и возвращает `requestId`. ### 2. Пользователь вводит код Пользователь получает код в SMS или другом канале и вводит его на вашем сайте. ### 3. Проверка кода Вы отправляете `requestId` и `code` на `/api/v1/2fa/verify`. Платформа возвращает результат — код верный или нет. Опционально можно: - Получать **обратные вызовы** о статусах через вебхук. - Проверять **статус запроса** по `requestId` в любой момент. ## Методы API | Что нужно | Куда идти | |---|---| | **Отправка и проверка кода** — curl-примеры, параметры, ответы | [Принцип работы 2FA: на стороне платформы →](https://docs.mydialogi.ru/02-otp/01-turnkey/otp-106-platform-side) | | **Проверка статуса запроса** — curl-пример, поля ответа | Раздел [«Проверка статуса запроса»](#проверка-статуса-запроса) ниже | | **Обратные вызовы** — формат данных, статусы, обработка | [Получение обратных вызовов при 2FA →](https://docs.mydialogi.ru/02-otp/01-turnkey/otp-108-callbacks) | ## Проверка статуса запроса Метод возвращает данные о ранее отправленном 2FA-запросе по `requestId`. ### Эндпоинт ``` GET /api/v1/2fa/requests/{requestId} ``` ### Параметры | Параметр | Что указать | |---|---| | `requestId` | Идентификатор, полученный при отправке кода | | **API-ключ** | Передаётся через **Basic Auth** — ключ интеграции, пароль пустой | ### Пример запроса ```bash curl https://<домен OTP-сервиса>/api/v1/2fa/requests/ \ -u ``` ### Что в ответе | Поле | Что означает | |---|---| | `id` | Идентификатор запроса | | `number` | Номер получателя | | `rate` | Стоимость | | `billable` | Признак тарификации | | `status` | Статус: `SUBMIT`, `SENT`, `DELIVERED` и другие | | `sender` | Имя отправителя интеграции | | `goals` | Цели запроса, например `NUMBER_VERIFIED` | | `createdAt` | Время создания запроса | | `payload` | Дополнительные данные | **Успешный ответ:** ```json { "id": "", "number": "<номер>", "rate": 0.0248, "billable": null, "status": "SUBMIT", "sender": "<имя отправителя>", "goals": ["NUMBER_VERIFIED"], "createdAt": 1234567891011, "payload": { "number": "<номер>" } } ``` **Статус ответа:** `200 OK`. ### Когда использовать - **Диагностика проблем** — если пользователь не получил код, проверьте статус запроса. - **Аудит** — отследить путь конкретного кода. - **Биллинг** — узнать стоимость запроса. ## Если нужна генерация на своей стороне API 2FA Service работает **только с режимом «На стороне платформы»** — платформа сама генерирует и проверяет код. Если вам нужна генерация и проверка кода на своей стороне — используйте режим **Умный шлюз**. [Как работает умный шлюз →](https://iba-platform.jamdesk.app/02-otp/02-smart-gateway/otp-201-how-gateway-works) ## Результат Вы понимаете, чем API 2FA отличается от OMNI API, знаете эндпоинты для отправки, проверки и мониторинга кода. ## Частые проблемы ### Ошибка 401 Unauthorized **Причина:** неверный API-ключ интеграции или неверная схема аутентификации. **Решение:** проверьте, что используете **Basic Auth** с ключом интеграции из раздела **Данные для интеграции**. Не используйте заголовок `X-API-Key` — он не подходит для 2FA-эндпоинтов. [Принцип работы 2FA: на стороне платформы →](https://iba-platform.jamdesk.app/02-otp/01-turnkey/otp-106-platform-side) ### Ошибка 404 Not Found при проверке статуса **Причина:** неверный `requestId` или запрос с истёкшим сроком хранения. **Решение:** проверьте, что `requestId` получен из ответа на отправку кода и не содержит опечаток. [Принцип работы 2FA: на стороне платформы →](https://iba-platform.jamdesk.app/02-otp/01-turnkey/otp-106-platform-side) ### Не приходит код **Причина:** номер получателя недоступен или имя отправителя неактивно. **Решение:** проверьте номер и статус имени отправителя. [OTP: код не приходит →](https://iba-platform.jamdesk.app/06-reference/03-troubleshooting/ts-otp-code) ### Проверка кода не работает **Причина:** неверный `requestId` или `code`, или истёк срок действия кода. **Решение:** убедитесь, что `requestId` получен из ответа на отправку, а `code` — тот, который ввёл пользователь. [Принцип работы 2FA: на стороне платформы →](https://iba-platform.jamdesk.app/02-otp/01-turnkey/otp-106-platform-side) ### Статус запроса не меняется **Причина:** сообщение ещё не доставлено или не проверено. **Решение:** подождите и повторите запрос. Статусы обновляются по мере обработки — от `SUBMIT` до `SENT`, `DELIVERED` или `VERIFIED`. [Получение обратных вызовов при 2FA →](https://iba-platform.jamdesk.app/02-otp/01-turnkey/otp-108-callbacks) ### Нужна генерация кода на своей стороне **Причина:** API 2FA Service работает только с генерацией на стороне платформы. **Решение:** используйте режим **Умный шлюз**. [Как работает умный шлюз →](https://iba-platform.jamdesk.app/02-otp/02-smart-gateway/otp-201-how-gateway-works) ## См. также Создание интеграции в разделе 2FA Service Curl-примеры отправки и проверки Формат данных и обработка вебхуков Изменение параметров и тестирование Обзор режима «Под ключ» HTTP-коды и форматы ответов ## Нужна помощь? - **OTP-коды:** support@otpcod.ru