Что понадобится до начала
Подготовьте серверное приложение, тестовый номер и аккаунт Cascade. После регистрации на баланс начисляется 1000 стартовых кредитов. В кабинете создайте API-ключ и сразу сохраните его в секретах бэкенда.
Базовый адрес API: https://cascade.kz/api. Все защищённые запросы используют заголовок:
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json
Не вставляйте токен в JavaScript страницы, публичный репозиторий, мобильную сборку или скриншоты. Если ключ раскрыт, отзовите его и создайте новый.
Шаг 1. Отправьте код
Минимальный запрос содержит номер пользователя:
curl -X POST "https://cascade.kz/api/otp/send" \
-H "Authorization: Bearer $CASCADE_API_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"phone":"77001234567","purpose":"login","channel":"whatsapp"}'
purpose связывает код с конкретным действием, например login, signup или payment. Используйте короткие предсказуемые значения и не помещайте туда персональные данные.
Поле channel можно не передавать — тогда применяется настройка компании. Публично доступны WhatsApp и Telegram. SMS присутствует в API, но открытый SMS-провайдер пока не запущен.
Успешный ответ содержит success, сообщение и expires_in. Стандартный срок действия кода — 300 секунд.
Шаг 2. Покажите пользователю форму
После успешной отправки покажите поле для шестизначного кода, таймер и понятную кнопку повторной отправки. Не запускайте resend автоматически: это создаёт лишние сообщения и мешает пользователю понять, какой код актуален.
Ваш фронтенд передаёт введённый код вашему серверу. Он не должен напрямую обращаться к Cascade.
Шаг 3. Проверьте код
Передайте тот же номер и тот же purpose, что использовались при отправке:
curl -X POST "https://cascade.kz/api/otp/verify" \
-H "Authorization: Bearer $CASCADE_API_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"phone":"77001234567","code":"482910","purpose":"login"}'
Только после success: true завершайте вход или подтверждаемое действие. Не доверяйте одной лишь успешной отправке сообщения: доставка и проверка кода — разные этапы.
Шаг 4. Обработайте ошибки
Минимально различайте следующие ответы:
| HTTP | Что означает | Что делать |
|---|---|---|
401 |
API-ключ неверен или отозван | Проверить серверный секрет, не просить пользователя повторять код |
422 |
Ошибка данных, канала, баланса либо неверный/просроченный код | Показать безопасное сообщение и исправить запрос |
429 |
Превышен лимит | Не повторять запрос сразу, применить задержку |
5xx |
Временная серверная ошибка | Записать request ID и повторить с ограниченным backoff |
Не показывайте пользователю внутренние детали провайдера и не записывайте OTP или Bearer-токен в логи.
Шаг 5. Подготовьте запуск
Перед продакшеном проверьте:
- API вызывается только с бэкенда;
- номер нормализуется до международного формата;
purposeсовпадает в send и verify;- есть лимиты отправок и попыток ввода;
- resend имеет задержку;
- UI обрабатывает истечение 5 минут;
- ошибки не раскрывают существование аккаунта;
- баланс и статусы доставки наблюдаются;
- секрет можно быстро заменить без новой сборки приложения.
Полные поля и ответы смотрите в справочниках send, verify и OpenAPI.