Integrasi API WhatsApp OTP: Contoh PHP, Node.js, dan Python

Mengirim kode verifikasi melalui WhatsApp pada dasarnya terdiri dari dua panggilan ke API OTP WapFlow: satu untuk mengirim kode, satu lagi untuk memverifikasi apa yang diketik pengguna. Dalam panduan ini kami mengumpulkan cara kerja API, contoh cURL, PHP, Node.js, dan Python, penanganan error, serta poin keamanan yang perlu diperhatikan. Contoh-contohnya mengikuti format dalam dokumentasi API resmi, dengan sedikit tambahan agar lebih mudah dibaca. Jika Anda masih bertanya-tanya tentang produknya sebelum mulai membuat kode, baca Apa Itu WhatsApp OTP terlebih dahulu.
Dasar-Dasar
- Base URL:
https://wapflow.net/api/otp/v1 - Autentikasi: header
Authorization: Bearer <key>pada setiap permintaan. Kunci live dimulai denganwfo_live_, kunci uji denganwfo_test_. - Format respons:
{ "success": true, ... }saat berhasil,{ "success": false, "error": { "code": "...", "message": "..." } }saat gagal. - Nomor telepon: dengan kode negara, misalnya
905321234567. API mengubah nomor menjadi digit saja (+, spasi, dan tanda hubung dibuang) dan mengharapkan 10 hingga 15 digit. Nomor sebelas digit yang diawali 0 diperlakukan sebagai nomor Turki dan ditambahkan 90 di depannya.
Anda membuat kunci API di halaman WapFlow OTP pada panel WapFlow. Kunci hanya ditampilkan sekali saat dibuat; simpan di variabel lingkungan (environment variable) pada server Anda.
Empat Endpoint
| Endpoint | Tujuan |
|---|---|
| POST /send | Membuat kode dan mengirimkannya melalui WhatsApp. phone wajib; opsional code_length (4-8), ttl (60-900 detik), lang, app_name. |
| POST /verify | Memeriksa kode yang diketik pengguna. phone dan code wajib; jika Anda menyertakan request_id, permintaan tersebut yang diperiksa. |
| GET /status/:request_id | Mengembalikan status permintaan: queued, sent, delivered, read, failed, verified, expired. |
| GET /me | Menampilkan apakah kunci valid, paket, jumlah akun yang terhubung, dan penggunaan kuota bulan ini. |
Setelah 5 percobaan yang salah, permintaan dikunci, dan kode yang sudah diverifikasi tidak dapat digunakan lagi. Jika Anda tidak menyertakan request_id, kode terbaru yang belum kedaluwarsa dan dikirim ke nomor itu dengan kunci ini yang akan diperiksa. Karena mungkin ada beberapa sesi, kami menyarankan untuk menyimpan request_id dan mengirimkannya kembali saat verifikasi.
Percobaan Pertama dengan cURL
# 1) send the code
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) verify the code
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"}'
Lakukan percobaan pertama dengan kunci wfo_test_: tidak ada pesan WhatsApp yang dikirim, tidak ada kuota yang digunakan, dan kode dikembalikan di kolom test_code pada respons.
Contoh PHP
<?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']);
// ... when the user submits the code:
$check = wapflow_otp('/verify', ['request_id' => $sent['request_id'], 'phone' => '905321234567', 'code' => $_POST['code']]);
if (!empty($check['valid'])) { /* signed in */ }
Contoh Node.js
Contoh ini menggunakan fetch bawaan (Node.js 18 atau lebih baru) dan harus dijalankan sebagai modul ES.
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' });
// ... when the user submits the code:
const check = await otp('/verify', { request_id: sent.request_id, phone: '905321234567', code: '123456' });
if (check.valid) { /* signed in */ }
Contoh Python
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"})
# ... when the user submits the code:
check = otp("/verify", {"request_id": sent["request_id"], "phone": "905321234567", "code": "123456"})
if check.get("valid"):
pass # signed in
Penanganan Error
Tangani pengiriman dan verifikasi secara terpisah. Jika pengiriman mengembalikan success: false, bertindaklah sesuai kode error:
| HTTP / kode | Yang harus dilakukan |
|---|---|
| 401 invalid_key | Periksa kuncinya; mungkin telah dicabut atau salah ketik. |
| 402 no_subscription, subscription_expired | Mulai atau perpanjang langganan. |
| 422 invalid_phone | Minta pengguna memasukkan nomor lagi dengan kode negara. |
| 429 rate_limited | Coba lagi setelah jumlah detik retry_after pada respons. |
| 429 quota_exceeded | Kuota bulanan telah habis; tingkatkan paket atau tunggu periode berikutnya. |
| 429 daily_limit_reached | Akun yang terhubung telah mencapai batas hariannya; coba lagi setelah retry_after (hari berikutnya pukul 00.00, waktu Turki). Tidak ada kuota yang digunakan. |
| 503 no_account_connected, send_failed | Pastikan ada akun WhatsApp yang terhubung dan aktif; coba lagi sebentar lagi. |
Pada verifikasi, respons HTTP 200 tetap dapat berisi valid bernilai false. Kolom reason menjelaskan penyebabnya: invalid_code, expired, too_many_attempts, already_verified, atau not_found. Untuk kode yang salah, attempts_left menunjukkan sisa percobaan; menyampaikan informasi ini kepada pengguna membuat pengalaman yang lebih baik.
Batas Laju dan Pengalaman Pengguna
- Satu nomor dapat menerima 1 kode per 60 detik, 5 per jam, dan 10 per hari. Pasang hitung mundur 60 detik pada tombol "Kirim Ulang" Anda.
- Ada 60 pengiriman per menit per kunci API, 120 permintaan per menit per alamat IP, dan untuk verifikasi, 10 percobaan per menit per nomor.
- Batas harian dan pemanasan nomor baru memengaruhi pengiriman; lihat artikel kami tentang mengurangi risiko pemblokiran untuk rinciannya.
Daftar Periksa Keamanan
- Jangan pernah menggunakan kunci API di browser, aplikasi seluler, atau kode publik apa pun; lakukan panggilan dari server Anda.
- Selalu periksa kode di server dengan
/verify; jangan percaya pada tanda "terverifikasi" yang datang dari browser. - Simpan kunci di variabel lingkungan dan jauhkan dari repositori Anda.
- Terapkan batas laju Anda sendiri dan, jika perlu, CAPTCHA sebelum mengirim kode; penyalahgunaan dapat menghabiskan kuota Anda.
- Siapkan saluran cadangan (SMS atau e-mail) untuk tindakan penting. OTP WapFlow bukan WhatsApp Business API resmi dan tidak menjamin pengiriman.
Jika Anda menggunakan WordPress atau WooCommerce, Anda dapat melewati penulisan kode dan memakai plugin. Lihat halaman harga untuk paket dan halaman WapFlow OTP untuk gambaran umum produk.
Pertanyaan yang Sering Diajukan
Apa yang berubah saat saya beralih ke mode live?
Hanya kuncinya. Kunci uji dimulai dengan wfo_test_, dan aturan pengiriman serta batas lajunya sama dengan kunci live; langganan aktif tetap diperlukan.
Apakah saya harus mengirim request_id?
Tidak wajib, tetapi dianjurkan. Jika Anda tidak menyertakannya, kode terbaru yang belum kedaluwarsa dan dikirim ke nomor tersebut yang akan diperiksa.
Bisakah saya mengubah teks pesan?
Bisa. Di panel Anda dapat mengatur nama aplikasi, templat pesan, panjang kode, masa berlaku, dan bahasa. Templat menggunakan variabel {code}, {app}, dan {minutes}. Untuk setiap permintaan, Anda dapat menimpanya dengan app_name, code_length, ttl, dan lang.
Bagaimana saya tahu pesan sudah terkirim?
Kueri permintaan dengan /status/:request_id; Anda mungkin melihat sent, delivered, dan read. Informasi pengiriman bergantung pada WhatsApp dan tidak dijamin.
Apakah API ini juga tersedia di aplikasi Windows?
Tidak. WapFlow OTP adalah layanan cloud terpisah.


