OTP API: отправить и проверить код

01Sandbox и Live

В Sandbox API возвращает тестовый код без сообщения в WhatsApp и без оплаты. В Live код отправляется получателю; нужен действующий OTP-пакет для его страны. Сейчас отправка использует шаблон waix_otp_v1: код и кнопку копирования, без названия проекта в тексте. В WhatsApp отправителем отображается WAIX.

02Создать проект и ключ

1. 01
   Откройте «OTP» → «Проекты» и создайте sandbox-проект. Он не отправляет сообщения и не требует оплаты.
2. 02
   Выпустите API-ключ. Сохраните его на сервере: не помещайте ключ в JavaScript страницы, мобильное приложение или открытый репозиторий.
3. 03
   Для реальной отправки откройте «Подписка», оформите OTP-пакет и дождитесь подтверждения оплаты. Создайте Live-проект и его ключ; методы API для обоих режимов одинаковы.

У каждого проекта отдельные ключи и вебхук. Отзыв ключа не затрагивает другие ключи. Приостановка проекта блокирует все его ключи.

03Отправить код

curl -X POST https://waix.kz/api/v1/otp/send \
  -H "Authorization: Bearer YOUR_PROJECT_KEY" \
  -H "Idempotency-Key: YOUR_REQUEST_UUID" \
  -H "Content-Type: application/json" \
  -d '{"to":"+77011234567","channel":"whatsapp","ttl":300}'

channel сейчас принимает только whatsapp. ttl — срок действия кода в секундах; в примере 300. Передавайте срок от 60 до 600 секунд, в Live — не больше лимита вашего пакета. Номер можно передать как +7701…, 7701… или 8701…; WAIX приводит его к международному формату. Сохраните id ответа у себя.

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "channel": "whatsapp",
    "recipient": "+77011234567",
    "mode": "sandbox",
    "status": "sent",
    "test_code": "123456",
    "expires_at": "2026-09-22T12:05:00.000Z"
  }
}

04Проверить введённый код

curl -X POST https://waix.kz/api/v1/otp/verify \
  -H "Authorization: Bearer YOUR_PROJECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"CHALLENGE_UUID","code":"123456"}'

Успешный ответ содержит status: verified. Код одноразовый. После пяти неверных попыток или окончания TTL он больше не принимается. Запрос verify нужно выполнять с вашего сервера. Не выдавайте пользователю сессию только по статусу доставки.

05Прочитать статус

GET https://waix.kz/api/v1/otp/CHALLENGE_UUID

Передайте тот же заголовок Authorization. Ответ содержит статус и временные отметки. В sandbox нет настоящей доставки и прочтения в WhatsApp. В Live доступны статусы queued, sent, delivered, read, verified, failed и expired. Подключите вебхук проекта для автоматической обработки событий. outcome_unknown означает, что результат отправки ещё не установлен: не создавайте новый запрос до проверки статуса.

06Идемпотентность и ограничения

В проекте — до 10 запросов на номер в час, между запросами минимум 60 секунд. Общая защита ограничивает запросы разных проектов на один номер. Sandbox допускает до 20 запросов компании в минуту. IP-лимиты также могут вернуть 429.