pt
Prévia gratuita

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

Por: Equipe WapFlow · 16 de novembro de 2026 · 7 min de leitura
Editor de código com uma chamada à API de OTP do WhatsApp e uma mensagem com código de verificação no celular

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 com wfo_live_, e as de teste, com wfo_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

EndpointFunção
POST /sendGera o código e o envia pelo WhatsApp. phone é obrigatório; opcionais: code_length (4-8), ttl (60-900 s), lang, app_name.
POST /verifyVerifica 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_idRetorna o status da requisição: queued, sent, delivered, read, failed, verified, expired.
GET /meMostra 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ódigoO que fazer?
401 invalid_keyVerifique a chave; ela pode ter sido revogada ou digitada incorretamente.
402 no_subscription, subscription_expiredInicie ou renove a assinatura.
422 invalid_phonePeça ao usuário que digite o número novamente, com o código do país.
429 rate_limitedTente novamente após o número de segundos indicado em retry_after na resposta.
429 quota_exceededA cota mensal se esgotou; faça upgrade do plano ou aguarde o próximo período.
429 daily_limit_reachedAs 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_failedConfirme 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.

Artigos relacionados