Бастауға не қажет
Серверлік қолданбаны, тест нөмірін және 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-қадам. Кодты тексеру
Жіберу кезінде қолданылған phone және 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 токенін логқа жазбаңыз.
Іске қосу чеклисті
- API тек бэкендтен шақырылады.
- Нөмір халықаралық форматқа келтіріледі.
- Send және verify кезінде
purposeсәйкес келеді. - Жіберу мен енгізу әрекеттеріне лимит қойылған.
- Resend алдында кідіріс бар.
- Интерфейс бес минуттық мерзімді өңдейді.
- Жауап аккаунттың бар-жоғын ашпайды.
- Баланс пен жеткізу мәртебесі бақыланады.
- API кілтін клиентті қайта жинамай ауыстыруға болады.
Толық өрістерді send, verify, errors және OpenAPI анықтамаларынан қараңыз.