Подключение к API OTP-кодов

Коротко: для работы с API OTP-кодов нужен базовый URL https://web.otpcod.ru/api/v1 и API-ключ в заголовке X-API-Key. Для 2FA-интеграции — отдельный ключ и Basic Auth.

Кому подходит

• Роль: Разработчик, Интегратор
• Уровень: Опытный

Что вы получите

Готовое подключение к API OTP-сервиса: базовый URL, ключ, формат запросов, который можно использовать в интеграции.

Перед началом

• У вас есть API-ключ с нужными правами доступа.
• У вас есть имена отправителей для каналов, по которым будете отправлять коды.
• Вы определили URL вебхука (если планируете получать статусы).

Базовый URL

https://web.otpcod.ru/api/v1

Все эндпоинты добавляются к базовому URL. Например:

Аутентификация

OMNI API и Broadcasts API

API-ключ передаётся в заголовке X-API-Key:

X-API-Key: <ваш-ключ>

2FA-эндпоинты

2FA-интеграция использует Basic Auth. Логин — API-ключ интеграции, пароль — пустой. Ключ и URL выдаются при настройке интеграции в разделе 2FA Service.

Authorization: Basic <base64(API-ключ:)>

В curl это передаётся флагом -u:

curl -X POST https://<домен-OTP>/api/v1/2fa/verify -u <API-ключ> -d requestId=<requestId> -d code=<код>

Формат запроса

Все запросы используют JSON или form-data.

OMNI API и Broadcasts API

Пример:

curl --location 'https://web.otpcod.ru/api/v1/messages' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "contact": "905063565285",
    "channel": 1,
    "senderId": "<senderID>",
    "isOtp": true,
    "payload": {
      "text": "Ваш код: 1234"
    }
  }'

2FA-эндпоинты

Пример:

curl -X POST https://<домен-OTP>/api/v1/2fa/verify \
  -u <API-ключ> \
  -d requestId=<requestId> \
  -d code=<код>

Формат ответа

OMNI API

Успешный ответ 202 Accepted:

{
  "error": false,
  "data": {
    "channel": 1,
    "transactionId": "95e3e0da-9684-4ba4-88a3-e9207ddeca05",
    "messageId": "6719b5f4-36af-4fba-b111-49ff07f4f96b"
  }
}

Ошибка содержит error: true и data с message и requestId. Подробнее: Обработка ошибок API.

Broadcasts API

Успех — 200 OK (с телом) или 204 No Content (удаление). Ошибка содержит execId, key, code, message, args.

2FA-эндпоинты

Проверка кода (/2fa/verify) — успешный ответ 200 OK:

{
  "number": "12345678910",
  "verifiedAt": 1234567890
}

Статус запроса (/2fa/requests/{requestId}) — успешный ответ 200 OK:

{
  "id": "<requestId>",
  "number": "<номер>",
  "rate": 0.0248,
  "status": "SUBMIT",
  "sender": "<имя отправителя>",
  "goals": ["NUMBER_VERIFIED"],
  "createdAt": 1234567891011
}

Коды ответов

Swagger UI

• OMNI API: https://web.otpcod.ru/api/v1/swagger-ui/index.html?urls.primaryName=OMNI_API
• Broadcasts API: https://web.otpcod.ru/api/v1/swagger-ui/index.html?urls.primaryName=Broadcasts_API

Результат

Вы знаете базовый URL, умеете передавать ключ и понимаете формат ответов. Можно переходить к работе с конкретными эндпоинтами.

Частые проблемы

См. также

Нужна помощь?

• OTP-коды: support@otpcod.ru