WhatsApp Platform

A Venddor atende o WhatsApp no modelo de Tech Provider (provedor de tecnologia da Meta): a plataforma tem uma única conta empresarial do WhatsApp (WABA), com um token de acesso permanente, e cada loja conecta o seu próprio número dentro dessa conta. A loja nunca preenche token nem segredo da Meta; ela herda o que o operador da plataforma configurou aqui.

Esta seção reúne as rotas do operador da plataforma (credenciais, números, webhook, roteamento de mensagens recebidas e Flows globais) e as duas rotas públicas do storefront que alimentam o mini-shop de WhatsApp (botão flutuante e telas).

Como funciona

1. Configure as credenciais
   Grave a URL da Cloud API, o token permanente, o id da WABA, o token de verificação do webhook e o segredo do app em Credenciais da plataforma.
2. Confira a saúde e assine o webhook
   Use Saúde, números e webhook para ver se a Meta responde e para assinar o app nos webhooks da WABA.
3. Conecte o número de uma loja
   Percorra os 3 passos de Conectar um número. Ao verificar o número, a plataforma tenta criar a rota de callback sozinha.
4. Ajuste as rotas
   Se precisar mover um número para outro destino, ou cadastrar um número externo, use Rotas de callback.
5. Publique Flows globais
   Monte Flows (formulários nativos do WhatsApp) uma vez e disponibilize a todas as lojas com Flows globais.

Estados que você vai encontrar

Conceitos importantes

WABA, número e phone_number_id

WABA (WhatsApp Business Account) é a conta empresarial da Meta que agrupa os números. Cada número tem um phone_number_id (texto numérico da Meta, não é o telefone). O telefone legível é display_phone_number ou business_phone (formato +5511999998888).

Loja, seller e store_id

Nas rotas de conexão de número, store_id identifica a loja que vai ser dona do número. Aceita o UUID do tenant ou o storefront_id numérico. O número fica ligado a um seller (lojista) dessa loja; se você não informar vendor_id, a plataforma usa o seller mais antigo da loja.

Token e segredo

O token de acesso e o segredo do app ficam criptografados. Em PUT /config, campo vazio significa "manter o valor atual": dá para salvar o formulário sem reenviar o segredo.

Rotas de callback

Uma rota associa um telefone (somente dígitos, com DDI) a uma URL de destino e a um token de verificação. O destino especial platform significa "processar dentro da plataforma Venddor"; uma URL comum encaminha a mensagem para um sistema externo (por exemplo, uma loja antiga ainda não migrada). Cada rota tem sua própria api_key de 64 caracteres.

Flows

Um Flow é um formulário nativo do WhatsApp (telas com campos, listas e botões) descrito por um JSON no formato da Meta. A Venddor guarda o JSON, valida e publica na Meta. Flows globais ficam no banco mestre e valem para todas as lojas; uma loja pode ter um Flow próprio com a mesma flow_key, que prevalece sobre o global.

Endpoints

Erros comuns

• Esperar 200 num erro de validação de número. Campos faltando no cadastro do número (phone_number, display_name) voltam como 500, não 400. Valide antes de chamar.
• Chamar com o token de um administrador comum. Só root_admin passa; o retorno é 403 insufficient permissions.
• Achar que o GET /routes/config só lê. Na primeira leitura ele gera e grava a chave mestra.
• Salvar um Flow sem reenviar o status. O PUT do Flow volta o status para draft quando o campo vem vazio, mesmo que o Flow estivesse publicado.
• Pedir o código de verificação várias vezes seguidas. Há espera mínima de 60 segundos entre pedidos do mesmo método, que dobra a cada bloqueio imposto pela Meta, até 15 minutos.
• Usar um telefone estrangeiro nas rotas. O número ganha o prefixo 55 quando não começa com 55, então um telefone de outro país é gravado errado.

Próximos passos