WhatsApp OTP API Entegrasyonu: PHP, Node.js ve Python Örnekleriyle

WhatsApp'tan doğrulama kodu göndermek, WapFlow OTP API'siyle iki çağrıya iner: biri kodu gönderir, diğeri kullanıcının girdiği kodu doğrular. Bu rehberde API'nin nasıl çalıştığını, cURL, PHP, Node.js ve Python örneklerini, hata yönetimini ve güvenlik noktalarını topladık. Örnekler resmî API belgesindeki biçimle uyumludur; yalnızca daha okunur olması için küçük ekler yaptık. Kodlamadan önce ürünün ne olduğunu merak ediyorsanız WhatsApp OTP nedir yazımıza bakın.
Temel Bilgiler
- Temel adres:
https://wapflow.net/api/otp/v1 - Kimlik doğrulama: Her istekte
Authorization: Bearer <anahtar>başlığı. Canlı anahtarlarwfo_live_, test anahtarlarıwfo_test_ile başlar. - Yanıt biçimi: Başarıda
{ "success": true, ... }, hatada{ "success": false, "error": { "code": "...", "message": "..." } }. - Telefon numarası: Ülke koduyla birlikte, örneğin
905321234567. API numarayı rakamlara indirger (+, boşluk ve tireler atılır), 10 ile 15 hane bekler. Başında 0 olan 11 haneli numaralar Türkiye sayılır ve başına 90 eklenir.
API anahtarını WapFlow panelindeki WapFlow OTP sayfasından oluşturursunuz. Anahtar yalnızca oluşturulurken bir kez gösterilir; sunucunuzda ortam değişkeni olarak saklayın.
Dört Uç Nokta
| Uç | Görev |
|---|---|
| POST /send | Kodu üretir ve WhatsApp'tan gönderir. phone zorunlu; isteğe bağlı code_length (4-8), ttl (60-900 sn), lang, app_name. |
| POST /verify | Kullanıcının girdiği kodu doğrular. phone ve code zorunlu; request_id verirseniz o istek kontrol edilir. |
| GET /status/:request_id | İsteğin durumunu verir: queued, sent, delivered, read, failed, verified, expired. |
| GET /me | Anahtarın geçerliliğini, paketi, bağlı hesap sayısını ve bu ayki kota kullanımını gösterir. |
Doğrulamada en fazla 5 yanlış denemeden sonra istek kilitlenir ve doğrulanan kod bir daha kullanılamaz. request_id vermezseniz, o numaraya bu anahtarla gönderilmiş, süresi dolmamış en son kod kontrol edilir. Birden çok oturum olabileceği için request_id'yi saklayıp doğrulamada geri göndermenizi öneririz.
cURL ile İlk Deneme
# 1) kodu gönder
curl -X POST https://wapflow.net/api/otp/v1/send \
-H "Authorization: Bearer wfo_live_XXXX" \
-H "Content-Type: application/json" \
-d '{"phone":"905321234567","app_name":"Acme"}'
# 2) kodu doğrula
curl -X POST https://wapflow.net/api/otp/v1/verify \
-H "Authorization: Bearer wfo_live_XXXX" \
-H "Content-Type: application/json" \
-d '{"request_id":"req_...","phone":"905321234567","code":"123456"}'
İlk denemeyi wfo_test_ anahtarıyla yapın: WhatsApp'a mesaj gitmez, kota harcanmaz ve yanıtta kod test_code alanında gelir.
PHP Örneği
<?php
function wapflow_otp(string $path, array $body): array {
$ch = curl_init('https://wapflow.net/api/otp/v1' . $path);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WAPFLOW_OTP_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($body),
]);
$res = json_decode(curl_exec($ch), true) ?: [];
curl_close($ch);
return $res;
}
$sent = wapflow_otp('/send', ['phone' => '905321234567', 'app_name' => 'Acme']);
// ... kullanıcı kodu girince:
$check = wapflow_otp('/verify', ['request_id' => $sent['request_id'], 'phone' => '905321234567', 'code' => $_POST['code']]);
if (!empty($check['valid'])) { /* giriş başarılı */ }
Node.js Örneği
Örnek, yerleşik fetch kullanır (Node.js 18 ve üzeri) ve ES modülü olarak çalıştırılmalıdır.
const BASE = 'https://wapflow.net/api/otp/v1';
async function otp(path, body) {
const res = await fetch(BASE + path, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.WAPFLOW_OTP_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
return res.json();
}
const sent = await otp('/send', { phone: '905321234567', app_name: 'Acme' });
// ... kullanıcı kodu gönderince:
const check = await otp('/verify', { request_id: sent.request_id, phone: '905321234567', code: '123456' });
if (check.valid) { /* giriş başarılı */ }
Python Örneği
import os
import requests
BASE = "https://wapflow.net/api/otp/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["WAPFLOW_OTP_KEY"]}
def otp(path, body):
return requests.post(BASE + path, json=body, headers=HEADERS, timeout=15).json()
sent = otp("/send", {"phone": "905321234567", "app_name": "Acme"})
# ... kullanıcı kodu gönderince:
check = otp("/verify", {"request_id": sent["request_id"], "phone": "905321234567", "code": "123456"})
if check.get("valid"):
pass # giriş başarılı
Hata Yönetimi
Gönderim ve doğrulama sonuçlarını ayrı ele alın. Gönderimde success: false dönerse hata koduna göre davranın:
| HTTP / kod | Ne yapmalı? |
|---|---|
| 401 invalid_key | Anahtarı kontrol edin; iptal edilmiş ya da yanlış girilmiş olabilir. |
| 402 no_subscription, subscription_expired | Aboneliği başlatın ya da yenileyin. |
| 422 invalid_phone | Kullanıcıdan numarayı ülke koduyla yeniden girmesini isteyin. |
| 429 rate_limited | Yanıttaki retry_after saniye sonra tekrar deneyin. |
| 429 quota_exceeded | Aylık kota doldu; paketi yükseltin ya da dönemi bekleyin. |
| 429 daily_limit_reached | Bağlı hesapların günlük sınırı doldu; retry_after sonrası (ertesi gün 00:00, Türkiye saati) deneyin. Kota harcanmaz. |
| 503 no_account_connected, send_failed | Bağlı ve açık bir WhatsApp hesabı olduğundan emin olun; kısa süre sonra tekrar deneyin. |
Doğrulamada HTTP 200 dönse bile valid false olabilir. reason alanı nedenini söyler: invalid_code, expired, too_many_attempts, already_verified ya da not_found. Yanlış kodda attempts_left kalan hakkı gösterir; kullanıcıya bunu iletmek iyi bir deneyim sağlar.
Hız Sınırları ve Kullanıcı Deneyimi
- Aynı numaraya 60 saniyede 1, saatte 5, günde 10 kod gönderilebilir. "Tekrar gönder" düğmesine 60 saniyelik geri sayım koyun.
- API anahtarı başına dakikada 60 gönderim, IP başına dakikada 120 istek, doğrulamada numara başına dakikada 10 deneme vardır.
- Günlük sınır ve yeni numaraların ısınması gönderimi etkiler; ayrıntı için ban riskini azaltma yazımıza bakın.
Güvenlik Kontrol Listesi
- API anahtarını tarayıcıda, mobil uygulamada ya da herkese açık kodda kullanmayın; çağrıları sunucunuzdan yapın.
- Kodun doğruluğunu her zaman sunucuda
/verifyile kontrol edin; tarayıcıdan gelen "doğrulandı" bilgisine güvenmeyin. - Anahtarı ortam değişkeninde saklayın, depoya işlemeyin.
- Kod göndermeden önce kendi tarafınızda da hız sınırı ve gerekirse CAPTCHA uygulayın; kotanızı kötüye kullanım yiyebilir.
- Kritik işlemler için yedek kanal (SMS ya da e-posta) bulundurun. WapFlow OTP resmî WhatsApp Business API değildir ve teslimat garantisi vermez.
WordPress ya da WooCommerce kullanıyorsanız kodlamaya gerek kalmadan eklentiyi kullanabilirsiniz. Paketler için fiyat sayfasına, ürün özeti için WapFlow OTP sayfasına bakın.
Sık Sorulan Sorular
Canlıya geçerken ne değişir?
Yalnızca anahtar. Test anahtarı wfo_test_ ile başlar ve gönderim, hız kuralları canlı anahtarla aynıdır; aktif abonelik yine gerekir.
request_id göndermek zorunda mıyım?
Hayır, ama önerilir. Göndermezseniz o numaraya gönderilmiş, süresi dolmamış en son kod kontrol edilir.
Mesaj metnini değiştirebilir miyim?
Evet. Panelde uygulama adı, mesaj şablonu, kod uzunluğu, süre ve dil ayarlanabilir. Şablonda {code}, {app} ve {minutes} değişkenleri kullanılır. İstek başına app_name, code_length, ttl ve lang ile bunları geçersiz kılabilirsiniz.
Mesajın iletildiğini nasıl anlarım?
/status/:request_id ucuyla istek durumunu sorgulayın; sent, delivered ve read değerleri görülebilir. Teslim bilgisi WhatsApp'a bağlıdır ve garanti değildir.
Bu API Windows uygulamasında da var mı?
Hayır. WapFlow OTP bulut tabanlı ayrı bir hizmettir.


