Contratos previsíveis e sem dados sensíveis.
Os endpoints abaixo servem ao painel autenticado. Integrações externas devem consumir webhooks assinados; uma credencial de sessão nunca deve sair do navegador.
Autenticação
As rotas usam cookie seguro de sessão e o cabeçalho X-CSRF-Token nas mutações JSON. O token CSRF está no <meta name="csrf-token">. Respostas são JSON UTF-8 e incluem apenas IDs públicos.
Content-Type: application/json Accept: application/json X-CSRF-Token: <token-da-sessao>
Endpoints autenticados
| Método | Rota | Uso |
|---|---|---|
| GET/POST/PUT/DELETE | /painel/api/campaigns.php | Consultar, criar, atualizar, duplicar, testar, ativar, pausar ou arquivar campanhas. |
| GET/POST | /painel/api/instances.php | Listar conexões; consultar status/QR; reiniciar, desconectar ou sincronizar grupos. |
| GET/POST | /painel/api/validations.php | Listar e iniciar validação em lote. |
| GET/POST | /painel/api/extractions.php | Listar e iniciar extração de contatos. |
| GET/POST | /painel/api/contacts.php | Consultar contatos mascarados e registrar evidência de consentimento. |
| GET/POST | /painel/api/suppressions.php | Gerenciar opt-out e supressões. |
| GET/POST | /painel/api/webhooks.php | CRUD, teste e rotação dos webhooks externos. |
| GET/POST | /painel/api/subscription.php | Consultar ou alterar cancelamento no fim do período. |
| POST | /painel/api/group_toggle.php | Incluir ou remover um grupo da exclusão global. |
/painel/api/. IDs sequenciais e nomes internos de sessão nunca autorizam uma operação.Ações de campanha
POST aceita create, activate, pause, archive, duplicate ou test; PUT faz atualização integral da configuração JSON e DELETE arquiva. O PUT preserva as mídias atuais; alterações de mídia permanecem no formulário multipart autenticado. Toda campanha nasce como draft. O campo active permanece compatível com o scheduler, e lifecycle_status informa draft|active|paused|archived.
{
"action": "activate",
"id": "uuid-publico-da-campanha"
}Ações de conexão
Para estado ou QR, use GET /painel/api/instances.php?action=status&id=UUID ou action=qr. Mutações usam JSON, CSRF e uma das ações abaixo:
{
"action": "restart | disconnect | sync_groups",
"id": "uuid-publico-da-conexao"
}Paginação e filtros
Campanhas e conexões aceitam page e per_page (máximo 50). A resposta informa página atual, tamanho, total de páginas e total de itens.
q, state=all|draft|active|paused|archived, run_status, instance_id ou id.
q, connection_status, provisioning_status, billing_status ou id.
Históricos aceitam limit (máximo 100) e cursor. Resultados aceitam até 1.000 por página. O cursor é opaco e vinculado ao usuário e ao job.
{
"page": 2,
"per_page": 20,
"pages": 8,
"total": 153
}{
"limit": 1000,
"has_more": true,
"next_cursor": "v1:token-opaco"
}Formato de resposta
{
"status": "success",
"campaign": {
"id": "uuid",
"lifecycle_status": "active",
"active": true,
"latest_run": {
"status": "completed",
"totals": {"targets": 150, "sent": 148, "failed": 2},
"costs": {"reserved_cents": 3750, "charged_cents": 3700}
},
"queue": {"active": 0, "review": 0, "sent": 148, "failed": 2}
}
}Falhas usam status: error, código estável, mensagem segura e status HTTP correspondente. 401 indica sessão ausente, 402 acesso financeiro inativo, 404 recurso inexistente ou de outro proprietário, 419 CSRF inválido, 422 entrada inválida e 429 limite temporário.
Privacidade das respostas
Telefones podem ser mascarados nas listagens; tokens, segredos, chaves, cabeçalhos de autenticação e respostas internas são removidos. Segredos de webhook são retornados somente na criação ou rotação.