Verify yüzeyi, son kullanıcılarınıza WhatsApp üzerinden tek kullanımlık doğrulama kodu göndermek ve girdikleri kodu doğrulamak için kullanılır — giriş, kayıt veya işlem onayı senaryoları için.
/v1/messages/otp ucundan farkı: orada kodu siz üretip yönetirsiniz, uç yalnızca
metni iletir. Verify'da ise kodu sistem üretir, hash'leyip saklar, geçerlilik süresini, deneme
sayısını ve kilidi sizin adınıza yönetir. Kendi tarafınızda kod deposu veya brute-force koruması
yazmanıza gerek kalmaz.
/verify/start kodu üretir, hash'iyle saklar ve WhatsApp'a gönderir. Size bir verification_id döner.
Kullanıcının girdiği kodu verification_id ile /verify/check'e yollarsınız; sonuç status alanında gelir.
Deneme sayacı, kilit ve resend cooldown sunucuda uygulanır. Kod tek kullanımlıktır ve TTL sonrası düşer.
/v1/verify/startDoğrulama başlat
Sistem tarafında bir doğrulama kodu üretir, hash'leyip saklar ve hedef numaraya WhatsApp üzerinden gönderir. Kod asla düz metin olarak saklanmaz.
device_id (bağlı ve connected bir cihaz) ve phone (E.164 formatı önerilir).start çağrısı 429 VERIFY_RESEND_TOO_SOON döndürür.Dönen `verification_id`'yi saklayın; doğrulama adımında kullanacaksınız. Kodun kendisi yanıtta DÖNMEZ — yalnızca kullanıcının WhatsApp'ına gider. Bu uç transaction bazlı `otp` rate-limit paketini kullanır, kampanya trafiğinden ayrıdır.
İstek
curl --request POST \
--url {{BASE_URL}}/v1/verify/start \
--header "X-API-Key: {{API_KEY}}" \
--header "Content-Type: application/json" \
--data '{
"device_id": "{{DEVICE_ID}}",
"phone": "+905551112233"
}'Yanıt
{
"data": {
"verification_id": "3f1c9a70-2d54-4f1e-9b8a-1c2d3e4f5a6b",
"status": "pending",
"phone": "+905551112233",
"remaining_attempts": 3,
"expires_at": "2026-07-13T09:35:00Z"
}
}/v1/verify/checkKodu doğrula
Kullanıcının girdiği kodu ilgili doğrulamaya karşı kontrol eder. Sonuç `status` alanında döner; deneme sayacı ve kilit sunucuda uygulanır.
verification_id (start yanıtından) ve kullanıcının girdiği code.expired statüsü alır.HTTP durumu her zaman 200'dür; asıl sonucu `status` alanından okuyun. Doğru kod girildiğinde doğrulama tüketilir — aynı kod ikinci kez `expired` döner.
İstek
curl --request POST \
--url {{BASE_URL}}/v1/verify/check \
--header "X-API-Key: {{API_KEY}}" \
--header "Content-Type: application/json" \
--data '{
"verification_id": "3f1c9a70-2d54-4f1e-9b8a-1c2d3e4f5a6b",
"code": "483920"
}'Yanıt
{
"data": {
"verification_id": "3f1c9a70-2d54-4f1e-9b8a-1c2d3e4f5a6b",
"status": "approved",
"remaining_attempts": 2
}
}Doğrulama durumları (status)
check çağrısı HTTP 200 ile döner; akışı yönlendirmek için status alanını kullanın:
| status | Anlamı | Ne yapmalı |
|---|---|---|
pending | start başarılı, kod gönderildi | Kullanıcıdan kodu bekleyin |
approved | Doğru kod girildi | Kullanıcıyı doğrulanmış kabul edin |
failed | Yanlış kod, hâlâ deneme hakkı var | remaining_attempts ile tekrar deneme sunun |
locked | Çok fazla yanlış deneme → kilit | Yeni bir doğrulama başlatın (kilit süresi dolunca) |
expired | Kod bulunamadı / TTL doldu / tüketildi | start ile yeni bir kod üretin |
Güvenlik politikası
Aşağıdaki değerler platform genelinde uygulanır ve güvenli varsayılanlar olacak şekilde seçilmiştir:
| Parametre | Varsayılan | Amaç |
|---|---|---|
| Kod uzunluğu | 6 hane | 10⁶ kombinasyon — deneme limitiyle birlikte tahmin olasılığı ≈ %0,0003 |
| Geçerlilik (TTL) | 5 dakika | Kod bu süre sonunda otomatik düşer |
| Maksimum deneme | 3 | Aşılınca doğrulama kilitlenir (locked) |
| Kilit süresi | 15 dakika | Brute-force sonrası bekleme penceresi |
| Resend cooldown | 60 saniye | OTP-bombası / spam koruması |
/messages/otp mi, /verify mi?Kod üretimini ve doğrulamayı kendi sisteminizde yönetiyorsanız /messages/otp yeterlidir — yalnızca teslimat yapar. Uçtan uca doğrulama (kod üretimi, TTL, deneme limiti, kilit) istiyorsanız /verify uçlarını kullanın.