Referência da API — Central BM

Todos os endpoints do sistema: o painel interno (usado pelo app, com token de sessão), o webhook da Meta e a API pública v1 para integrações de terceiros.

Base https://SEU_DOMINIO/api Formato JSON Auth Bearer token (Sanctum)

Visão geral

Três superfícies, três níveis de acesso.

PainelToken de sessão (login do usuário). É o que o app consome — CRUD de BMs, campanhas, clientes, etc.

Pública v1Token de API por usuário (gerado pelo admin). Para terceiros enviarem mensagens pelo prefixo /api/v1.

WebhookPúblico, chamado pela Meta. Valida a assinatura e reencaminha para o webhook do cliente.

Como autenticar: envie Authorization: Bearer <token> e Accept: application/json em todo request do painel e da API v1. O token de sessão vem de POST /api/login.

Autenticação

Sessão do painel.

POST/api/loginpúblico

Autentica e devolve o token de sessão.

emailobrigatório

passwordobrigatório

GET/api/mesessão

Dados do usuário logado.

POST/api/logoutsessão

Revoga o token atual.

Estado & Dashboard

Leitura do painel.

GET/api/statesessão

Estado completo no formato do app (BMs, WABAs, números, clientes, templates, campanhas, tarefas, usuários). É o que o front carrega.

GET/api/dashboardsessão

KPIs de risco (BMs, WABAs, números, qualidade, chamados).

GET/api/alertassessão

Alertas ativos por severidade.

Inventário — BMs, WABAs e Números

Status, tier e qualidade vêm da Meta (via sincronização); não são editáveis manualmente.

GET/api/business-managerssessão

Lista BMs com WABAs, números e resumo. Aceita ?busca=, ?status=, ?qualidade=.

POST/api/business-managerssessão

Cadastra uma BM.

nomeobrigatório

clienteobrigatório

id_metaBusiness ID

access_tokentoken de usuário (System User)

app_id, app_secretcredenciais do app

GET/api/business-managers/{id}sessão

Detalhe de uma BM.

PUT/api/business-managers/{id}sessão

Edita a BM. Tokens em branco = mantém os atuais; cliente_id vincula um cliente.

DELETE/api/business-managers/{id}sessão

Remove a BM.

POST/api/business-managers/{id}/syncsessão

Sincroniza com a Meta: puxa WABAs, números, tier, qualidade, templates, fotos e status (banimento via health_status).

POST/api/wabas · PUT · DEL /api/wabas/{id}sessão

CRUD de WABA. PUT aceita status e cliente_id.

POST/api/phone-numbers · PUT · DEL /api/phone-numbers/{id}sessão

Número: criar, editar (nome_exibicao, cliente_id) e remover. Cada número pode ter seu próprio cliente.

POST/api/phone-numbers/{id}/fotosessão

Atualiza a foto de perfil do número na Meta (upload multipart foto).

Clientes

Empresas vinculáveis a BM, WABA ou número. Cada cliente pode ter um webhook.

GET/api/clientessessão

Lista clientes com contagem de vínculos.

POST/api/clientes · PUT · DEL /api/clientes/{id}sessão

CRUD de cliente.

nomeobrigatório

documentoCNPJ (opcional)

webhook_urlURL para receber eventos dos números do cliente

Templates

GET/api/templates · GET /api/templates/{id}sessão

Lista e detalhe (nome, categoria, status, corpo, variáveis).

POST/api/templates · PUT · DEL /api/templates/{id}sessão

CRUD de template.

Campanhas

Fluxo: criar (com CSV) → validar na Strong → pendente de aprovação → aprovar → disparar.

GET/api/campaigns · GET /api/campaigns/{id}sessão

Lista e detalhe.

POST/api/campaignssessão

Cria a campanha e envia os contatos para higienização (Strong).

nome, template_id, volumedados básicos

numeros[]números de envio

contatos[]{numero, nome, dados} do CSV

variaveis[], imagem_url, botao_variavelparâmetros do template

POST/api/campaigns/{id}/validatesessão

Consulta o relatório da Strong e marca contatos válidos/inválidos.

POST/api/campaigns/{id}/approveAdmin/Operador

Aprova e inicia os disparos (respeita DISPARO_ENABLED).

POST/api/campaigns/{id}/dispatchAdmin/Operador

(Re)dispara manualmente.

POST/api/campaigns/{id}/test-sendsessão

Envia um teste da campanha para um número (destino).

GET/api/campaigns/{id}/contacts · /report · /sends · /sends/exportsessão

Contatos (válidos/inválidos), KPIs, envios e exportação CSV.

PUT/api/campaigns/{id} · DELsessão

Editar (nome, status, volume) e remover.

Suporte & Usuários

GET/api/tasks · POST · PUT · DEL /api/tasks/{id}sessão

Chamados de suporte (kanban).

GET/api/users · POST · PUT · DEL /api/users/{id}sessão

CRUD de usuários. PUT permite trocar nome, e-mail, papel, status e escopo.

POST/api/users/{id}/api-tokenAdmin

Gera o token da API pública v1 para o usuário.

GET/api/client/context · /api/client/sendspapel Cliente

Consultas do usuário com papel Cliente (números e histórico).

Wiki

GET/api/wiki · GET /api/wiki/{slug} · POST · PUT · DELsessão

Base de conhecimento editável da equipe.

Webhook da Meta

Recebe eventos da Meta, valida a assinatura e reencaminha por número para o webhook do cliente.

Configuração na Meta: Callback URL https://SEU_DOMINIO/api/webhooks/meta · Verify token = META_WEBHOOK_VERIFY_TOKEN (do .env). A validação de assinatura usa o App Secret da BM (por WABA no payload).

GET/api/webhooks/metapúblico

Handshake de verificação. Responde o hub.challenge se o token confere.

POST/api/webhooks/metapúblico

Recebe eventos. Confere X-Hub-Signature-256; se válida (ou sem App Secret cadastrado ainda), reencaminha o evento daquele número para o webhook do cliente. Assinatura inválida = não reencaminha.

GET/api/webhook-logssessão

Tudo que a Meta tentou enviar (verificações e eventos), com status da assinatura e do reenvio. Visualização em /webhook-logs. Aceita ?tipo=evento|verificacao.

API pública v1 — envio por terceiros

Prefixo /api/v1 · Bearer token do usuário · limite 120 req/min.

GET/api/v1/numberstoken v1

Números disponíveis para o token, com enviadas nas últimas 24h.

GET/api/v1/templatestoken v1

Templates aprovados (deduplicados por nome).

POST/api/v1/messagestoken v1

Envia uma mensagem por template. Escolhe automaticamente um número elegível. Suporta dry_run.

todestino

templatenome do template

variables[], image_url, button_variableparâmetros

dry_runsimula sem enviar

GET/api/v1/messages/{id}token v1

Status de um envio.

Documentação interativa do envio por terceiros também em /docs.