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

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

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

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

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

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 — от 60 до 600 секунд, по умолчанию 300. Номер можно передать как +7701…, 7701… или 8701…; WAIX приводит его к международному формату. Сохраните id ответа у себя.

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

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

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 нужно выполнять с вашего сервера. Не выдавайте пользователю сессию только по статусу доставки.

Проверить доставку

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

Передайте тот же заголовок Authorization. Ответ содержит статус, время отправки, доставки, чтения и проверки. Для автоматической обработки подключите вебхук проекта. Статус outcome_unknown означает, что ответ Meta потерян: не повторяйте отправку автоматически с новым ключом. Дождитесь вебхука или дайте пользователю запросить новый код после паузы.

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

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