Integrazione API WhatsApp OTP: esempi in PHP, Node.js e Python

Inviare un codice di verifica via WhatsApp si riduce a due chiamate con l'API WapFlow OTP: una invia il codice, l'altra verifica quello che l'utente ha digitato. In questa guida raccogliamo il funzionamento dell'API, esempi in cURL, PHP, Node.js e Python, la gestione degli errori e i punti di sicurezza da tenere d'occhio. Gli esempi seguono il formato della documentazione ufficiale dell'API, con solo piccole aggiunte per renderli più leggibili. Se si chiede cosa sia il prodotto prima di iniziare a programmare, legga prima Cos'è WhatsApp OTP.
Nozioni di base
- Indirizzo di base:
https://wapflow.net/api/otp/v1 - Autenticazione: un'intestazione
Authorization: Bearer <key>in ogni richiesta. Le chiavi live iniziano conwfo_live_, quelle di test conwfo_test_. - Formato della risposta:
{ "success": true, ... }in caso di successo,{ "success": false, "error": { "code": "...", "message": "..." } }in caso di errore. - Numero di telefono: con il prefisso internazionale, ad esempio
905321234567. L'API riduce il numero alle sole cifre (+, spazi e trattini vengono eliminati) e si aspetta da 10 a 15 cifre. I numeri di 11 cifre che iniziano con 0 sono trattati come numeri turchi e si aggiunge 90 davanti.
La chiave API si crea nella pagina WapFlow OTP del pannello WapFlow. La chiave viene mostrata una sola volta al momento della creazione; la conservi come variabile d'ambiente sul Suo server.
Quattro endpoint
| Endpoint | Scopo |
|---|---|
| POST /send | Genera il codice e lo invia tramite WhatsApp. phone è obbligatorio; facoltativi code_length (4-8), ttl (60-900 sec), lang, app_name. |
| POST /verify | Verifica il codice inserito dall'utente. phone e code sono obbligatori; se passa request_id, viene controllata quella richiesta. |
| GET /status/:request_id | Restituisce lo stato della richiesta: queued, sent, delivered, read, failed, verified, expired. |
| GET /me | Mostra la validità della chiave, il piano, il numero di account collegati e l'uso della quota di questo mese. |
Dopo 5 tentativi errati la richiesta viene bloccata, e un codice verificato non può essere riutilizzato. Se non passa request_id, viene controllato l'ultimo codice non scaduto inviato a quel numero con questa chiave. Poiché possono esistere più sessioni, consigliamo di memorizzare il request_id e di inviarlo di nuovo durante la verifica.
Primo tentativo con 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"}'
Esegua il primo tentativo con una chiave wfo_test_: non viene inviato alcun messaggio WhatsApp, non si consuma quota e il codice torna nel campo test_code della risposta.
Esempio 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 */ }
Esempio Node.js
L'esempio usa fetch integrato (Node.js 18 o successivo) e deve essere eseguito come modulo 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 */ }
Esempio 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
Gestione degli errori
Gestisca separatamente l'invio e la verifica. Se un invio restituisce success: false, agisca in base al codice di errore:
| HTTP / codice | Cosa fare |
|---|---|
| 401 invalid_key | Controlli la chiave; potrebbe essere stata revocata o digitata in modo errato. |
| 402 no_subscription, subscription_expired | Attivi o rinnovi l'abbonamento. |
| 422 invalid_phone | Chieda all'utente di inserire di nuovo il numero con il prefisso internazionale. |
| 429 rate_limited | Riprovi dopo i secondi indicati in retry_after nella risposta. |
| 429 quota_exceeded | La quota mensile è esaurita; passi a un piano superiore o attenda il periodo successivo. |
| 429 daily_limit_reached | Gli account collegati hanno raggiunto il limite giornaliero; riprovi dopo retry_after (il giorno successivo alle 00:00, ora della Turchia). Non viene consumata quota. |
| 503 no_account_connected, send_failed | Verifichi che esista un account WhatsApp collegato e attivo; riprovi dopo poco tempo. |
In fase di verifica, anche una risposta HTTP 200 può contenere valid false. Il campo reason indica il motivo: invalid_code, expired, too_many_attempts, already_verified oppure not_found. In caso di codice errato, attempts_left indica i tentativi rimasti; comunicarlo all'utente offre un'esperienza migliore.
Limiti di frequenza ed esperienza utente
- A uno stesso numero possono essere inviati 1 codice ogni 60 secondi, 5 all'ora e 10 al giorno. Inserisca un conto alla rovescia di 60 secondi sul pulsante "Invia di nuovo".
- Per chiave API sono consentiti 60 invii al minuto, per IP 120 richieste al minuto e, in verifica, 10 tentativi al minuto per numero.
- Il limite giornaliero e il riscaldamento dei nuovi numeri influiscono sull'invio; per i dettagli consulti il nostro articolo su come ridurre il rischio di ban.
Checklist di sicurezza
- Non usi la chiave API nel browser, in un'app mobile o in codice pubblico; effettui le chiamate dal Suo server.
- Verifichi sempre il codice sul server con
/verify; non si fidi di un flag "verificato" proveniente dal browser. - Conservi la chiave in una variabile d'ambiente, fuori dal repository.
- Applichi un proprio limite di frequenza e, se necessario, un CAPTCHA prima dell'invio di un codice; un abuso può consumare la Sua quota.
- Mantenga un canale di backup (SMS o e-mail) per le azioni critiche. WapFlow OTP non è l'API ufficiale WhatsApp Business e non garantisce la consegna.
Se utilizza WordPress o WooCommerce, può evitare la programmazione e usare il plugin. Per i piani consulti la pagina dei prezzi e per la panoramica del prodotto la pagina di WapFlow OTP.
Domande frequenti
Cosa cambia quando passo in produzione?
Solo la chiave. Una chiave di test inizia con wfo_test_, e le sue regole di invio e di frequenza sono le stesse di una chiave live; è comunque richiesto un abbonamento attivo.
Devo inviare request_id?
No, ma è consigliato. Se non lo invia, viene controllato l'ultimo codice non scaduto inviato a quel numero.
Posso cambiare il testo del messaggio?
Sì. Nel pannello si possono impostare il nome dell'applicazione, il modello del messaggio, la lunghezza del codice, la validità e la lingua. Il modello utilizza le variabili {code}, {app} e {minutes}. Per singola richiesta può sostituirle con app_name, code_length, ttl e lang.
Come faccio a sapere che il messaggio è stato consegnato?
Interroghi la richiesta con /status/:request_id; potrebbe vedere i valori sent, delivered e read. Le informazioni sulla consegna dipendono da WhatsApp e non sono garantite.
Questa API è disponibile anche nell'app per Windows?
No. WapFlow OTP è un servizio separato basato sul cloud.


