Integração da API de OTP do WhatsApp: Exemplos em PHP, Node.js e Python

Enviar um código de verificação pelo WhatsApp se resume a duas chamadas à API WapFlow OTP: uma envia o código, a outra verifica o que o usuário digitou. Neste guia reunimos como a API funciona, exemplos em cURL, PHP, Node.js e Python, o tratamento de erros e os pontos de segurança a observar. Os exemplos seguem o formato da documentação oficial da API, com pequenas adições apenas para facilitar a leitura. Se você ainda quer entender o produto antes de programar, leia primeiro O que é o WhatsApp OTP.
Informações Básicas
- Endereço base:
https://wapflow.net/api/otp/v1 - Autenticação: um cabeçalho
Authorization: Bearer <key>em cada requisição. As chaves ativas começam comwfo_live_, e as de teste, comwfo_test_. - Formato da resposta:
{ "success": true, ... }em caso de sucesso e{ "success": false, "error": { "code": "...", "message": "..." } }em caso de falha. - Número de telefone: com o código do país, por exemplo
905321234567. A API reduz o número a dígitos (são removidos +, espaços e traços) e espera de 10 a 15 dígitos. Números de 11 dígitos começando com 0 são considerados da Turquia e recebem 90 no início.
Você cria a chave de API na página do WapFlow OTP, no painel do WapFlow. A chave é exibida apenas uma vez, no momento da criação; guarde-a em uma variável de ambiente no seu servidor.
Quatro Endpoints
| Endpoint | Função |
|---|---|
| POST /send | Gera o código e o envia pelo WhatsApp. phone é obrigatório; opcionais: code_length (4-8), ttl (60-900 s), lang, app_name. |
| POST /verify | Verifica o código digitado pelo usuário. phone e code são obrigatórios; se você informar request_id, essa requisição específica é conferida. |
| GET /status/:request_id | Retorna o status da requisição: queued, sent, delivered, read, failed, verified, expired. |
| GET /me | Mostra se a chave é válida, o plano, o número de contas conectadas e o uso da cota deste mês. |
Após 5 tentativas erradas, a requisição é bloqueada, e um código já verificado não pode ser usado novamente. Se você não informar request_id, é conferido o código válido mais recente enviado para esse número com esta chave. Como podem existir várias sessões, recomendamos guardar o request_id e enviá-lo de volta na verificação.
Um Primeiro Teste com 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"}'
Faça o primeiro teste com uma chave wfo_test_: nenhuma mensagem é enviada ao WhatsApp, nenhuma cota é consumida, e o código vem no campo test_code da resposta.
Exemplo em 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 */ }
Exemplo em Node.js
O exemplo usa o fetch nativo (Node.js 18 ou superior) e deve ser executado como módulo 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 */ }
Exemplo em 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
Tratamento de Erros
Trate separadamente os resultados de envio e de verificação. Se um envio retornar success: false, aja de acordo com o código de erro:
| HTTP / código | O que fazer? |
|---|---|
| 401 invalid_key | Verifique a chave; ela pode ter sido revogada ou digitada incorretamente. |
| 402 no_subscription, subscription_expired | Inicie ou renove a assinatura. |
| 422 invalid_phone | Peça ao usuário que digite o número novamente, com o código do país. |
| 429 rate_limited | Tente novamente após o número de segundos indicado em retry_after na resposta. |
| 429 quota_exceeded | A cota mensal se esgotou; faça upgrade do plano ou aguarde o próximo período. |
| 429 daily_limit_reached | As contas conectadas atingiram o limite diário; tente após retry_after (no dia seguinte, às 00:00, horário da Turquia). Nenhuma cota é consumida. |
| 503 no_account_connected, send_failed | Confirme que existe uma conta de WhatsApp conectada e ativa; tente novamente em instantes. |
Na verificação, uma resposta HTTP 200 ainda pode trazer valid como false. O campo reason informa o motivo: invalid_code, expired, too_many_attempts, already_verified ou not_found. Em caso de código errado, attempts_left mostra quantas tentativas restam; informar isso ao usuário melhora a experiência.
Limites de Uso e Experiência do Usuário
- Um número pode receber 1 código a cada 60 segundos, 5 por hora e 10 por dia. Coloque uma contagem regressiva de 60 segundos no botão "Reenviar".
- Há 60 envios por minuto por chave de API, 120 requisições por minuto por endereço IP e, na verificação, 10 tentativas por minuto por número.
- O limite diário e o aquecimento de números novos afetam o envio; para detalhes, veja nosso artigo sobre como reduzir o risco de banimento.
Checklist de Segurança
- Nunca use a chave de API em navegador, aplicativo móvel ou em qualquer código público; faça as chamadas a partir do seu servidor.
- Sempre confira o código no servidor com
/verify; não confie em uma informação de "verificado" vinda do navegador. - Guarde a chave em uma variável de ambiente e fora do seu repositório.
- Aplique o seu próprio limite de uso e, se necessário, um CAPTCHA antes de enviar um código; o abuso pode consumir a sua cota.
- Mantenha um canal de reserva (SMS ou e-mail) para ações críticas. O WapFlow OTP não é a API oficial do WhatsApp Business e não garante a entrega.
Se você usa WordPress ou WooCommerce, pode dispensar a programação e usar o plugin. Para os planos, veja a página de preços; para a visão geral do produto, a página do WapFlow OTP.
Perguntas Frequentes
O que muda quando eu passo para o ambiente de produção?
Apenas a chave. Uma chave de teste começa com wfo_test_, e suas regras de envio e de limite são as mesmas de uma chave ativa; ainda assim, é necessária uma assinatura ativa.
Preciso enviar o request_id?
Não, mas é recomendado. Se você não enviar, é conferido o código válido mais recente enviado para esse número.
Posso alterar o texto da mensagem?
Sim. No painel, você pode definir o nome do aplicativo, o modelo da mensagem, o tamanho do código, a validade e o idioma. O modelo usa as variáveis {code}, {app} e {minutes}. Em cada requisição, você pode substituí-las com app_name, code_length, ttl e lang.
Como sei que a mensagem foi entregue?
Consulte a requisição pelo endpoint /status/:request_id; você pode ver os status sent, delivered e read. A informação de entrega depende do WhatsApp e não é garantida.
Esta API também está disponível no aplicativo para Windows?
Não. O WapFlow OTP é um serviço separado, em nuvem.


