O número virtual para WhatsApp tem API e aviso automático, e os dois conversam com o n8n sem pacote nenhum. Esta página traz três fluxos prontos, o que cada um faz e como ligar.
Situação: os arquivos foram montados a partir da API e a conta da assinatura foi conferida, mas os fluxos ainda não rodaram em um n8n de verdade. Se algum nó aparecer com aviso ao importar, abra o nó e salve de novo, ou fale com o suporte.
Os três fluxos
| Fluxo | O que faz | Gasta saldo | Arquivo |
|---|---|---|---|
| Código chegou | Recebe o aviso assinado e entrega número e código para o resto do seu fluxo | Não | baixar |
| Comprar e ler o código | Confere estoque, compra um número e espera o código chegar | Sim | baixar |
| Vencimentos | Todo dia, lista os números que vencem em 3 dias | Não | baixar |
Para importar: no n8n, crie um fluxo novo, abra o menu de três pontos e escolha Import from File.
Antes de começar
- Crie a chave de API no painel, em API Keys. Guarde: ela aparece uma vez.
- No n8n, crie uma credencial do tipo Header Auth:
- Name:
Authorization - Value:
Bearer SUA_CHAVE
- Name:
- Escolha essa credencial em cada nó HTTP Request dos fluxos importados.
A conta precisa estar verificada no painel antes da primeira compra. Sem isso, a API responde verification_required e nada é cobrado.
Fluxo 1: o código chegou
É o mais útil. Em vez de consultar a API de tempos em tempos, a ProxyBox chama o seu n8n no instante em que o WhatsApp envia o código.
- Importe o arquivo e ative o fluxo.
- Abra o nó Webhook ProxyBox e copie a Production URL.
- No painel, em Número Virtual, abra Para desenvolvedores: aviso automático e API, cole a URL e salve.
- Copie o segredo que o painel mostra e cole no nó Calcular assinatura, no campo Secret.
- No painel, toque em Enviar teste. O n8n deve registrar uma execução que termina em Outros eventos.
- Troque o nó Usar o código pelo destino que você quer: uma planilha, uma mensagem para a equipe, o seu sistema.
O nó Usar o código já separa quatro campos: numero, apelido, codigo e recebido_em.
O que chega no aviso
{
"event": "code.received",
"sent_at": "2026-11-14T04:33:11+00:00",
"number": {
"id": 41,
"phone_number": "+5511998765432",
"ddd": "11",
"label": "Loja",
"status": "active",
"expires_at": "2026-12-14T04:30:00+00:00",
"auto_renew": true
},
"code": "482913",
"received_at": "2026-11-14T04:33:10+00:00"
}
Os eventos são code.received, number.ready, number.renewed, number.swapped, number.expired e test. O fluxo trata o primeiro e manda os outros para Outros eventos, onde você pode ligar o que quiser.
Como a assinatura é conferida
Cada aviso leva o cabeçalho X-ProxyBox-Signature: sha256=…, que é o HMAC-SHA256 do corpo com o seu segredo. O nó Calcular assinatura refaz a conta e o nó Assinatura confere? compara. Aviso que não confere para em Assinatura inválida e não segue adiante.
Não remova essa conferência. O endereço do Webhook é público, e é a assinatura que prova que o aviso veio da ProxyBox.
O n8n precisa responder em até 6 segundos. O fluxo já responde na hora (modo "Immediately"), antes de rodar o resto.
Fluxo 2: comprar e ler o código
Serve para quem cria contas dentro de um processo maior, com alguém digitando o número no WhatsApp logo em seguida.
- Importe e escolha a credencial nos três nós HTTP.
- Em Dados do pedido, ajuste:
ddd: dois dígitos, ou vazio para qualquer DDD;chave_do_pedido: identifica a compra. Repetir a mesma chave não cobra de novo.
- Rode o fluxo. Ele confere estoque e verificação da conta, compra, e passa a consultar o número a cada 15 segundos.
- Enquanto isso, digite o número no WhatsApp e peça o código por SMS.
Se o código não chegar em cerca de 5 minutos, o fluxo termina em Parou de esperar. O número continua seu. Dá para trocar por outro sem custo, enquanto nenhum código chegou, pelo painel ou pela rota de troca da API.
Atenção ao gatilho. O arquivo vem com gatilho manual de propósito. Se trocar por um agendamento ou por um Webhook, cada execução compra um número. Coloque um limite antes.
Fluxo 3: vencimentos
Roda todo dia às 9h, lê a lista de números e separa os que vencem em até 3 dias. Cada item sai com numero, apelido, vence_em e renova_sozinho.
Ligue a saída a um e-mail ou a uma mensagem. Números com renovação automática ligada e saldo na carteira renovam sozinhos; o fluxo serve para você conferir o saldo antes.
As rotas, para montar o seu próprio fluxo
Todas ficam em https://proxybox.com.br/api/v1 e usam o mesmo cabeçalho Authorization.
| O que fazer | Método e caminho |
|---|---|
| Planos, preço e estoque por DDD | GET /virtual-numbers/catalog?ddd=11 |
| Comprar | POST /virtual-numbers |
| Listar os números | GET /virtual-numbers |
| Ver um número e buscar códigos | GET /virtual-numbers/{id} |
| Renovar por mais 30 dias | POST /virtual-numbers/{id}/renew |
| Trocar antes de o código chegar | POST /virtual-numbers/{id}/swap |
| Ligar ou desligar a renovação automática | POST /virtual-numbers/{id}/auto-renew |
| Cadastrar o endereço do aviso | PUT /virtual-numbers/webhook |
Os campos de cada resposta estão na documentação da API.
Problemas comuns
- 401 nos nós HTTP. A credencial não foi escolhida no nó, ou o valor está sem a palavra
Bearerantes da chave. - 403
verification_required. A conta ainda não foi verificada no painel. - 402
insufficient_balance. Falta saldo na carteira. Nada foi cobrado. - Todo aviso cai em "Assinatura inválida". O segredo no nó não é o que o painel mostra. Copie de novo, inteiro e sem espaços, e cole no campo Secret.
- O aviso não chega. A URL precisa ser a de produção, com https, e o fluxo precisa estar ativo. A URL de teste do n8n só funciona com o editor aberto. Depois de muitas falhas seguidas, o painel desliga o aviso: salve o endereço de novo para religar.
- 429. Muitas chamadas em pouco tempo. Aumente o intervalo do nó Wait.
Depois do código
Com o WhatsApp criado no celular, dá para ligar a conta ao n8n e enviar e receber mensagens pela API de WhatsApp. O guia conectar o número à API de WhatsApp mostra a ordem.