API Interna

Contratos entre camadas, endpoints HTTP internos e rotas nomeadas.

1. Rotas nomeadas

Públicas

Autenticadas

2. Contratos de services

ClienteService

listar(int $usuarioId, ?string $busca, int $page, int $perPage): array
buscar(int $id, int $usuarioId): array
criar(int $usuarioId, array $dados): array
atualizar(int $id, int $usuarioId, array $dados): array
excluir(int $id, int $usuarioId): void
resumo(int $usuarioId): array
total(int $usuarioId): int

Lançam RuntimeException com mensagem pronta para exibição.

CampanhaService

Análogo ao ClienteService, com resumo() e topPorOrcamento().

DiagnosticoService

iniciar(int $campanhaId, int $usuarioId): array
responder(int $diagnosticoId, int $usuarioId, int $perguntaId, string $valor): void
concluir(int $diagnosticoId, int $usuarioId): array
buscar(int $id, int $usuarioId): array
porCampanha(int $campanhaId, int $usuarioId): array
resumo(int $usuarioId): array
recomendacoesPorPrioridade(array $respostas): array
calcular(array $perguntas, array $respostas): array

PlanoCampanhaService

criarAPartirDoDiagnostico(int $diagnosticoId, int $usuarioId): array
criarManual(int $usuarioId, array $dados): array
atualizar(int $id, int $usuarioId, array $dados): array
excluir(int $id, int $usuarioId): void
marcarItem(int $planoId, int $itemId, int $usuarioId, bool $concluido): array
buscar(int $id, int $usuarioId): array

MetricaService

lancar(int $usuarioId, array $dados): array
excluir(int $id, int $usuarioId): void
resumoCampanha(int $campanhaId, int $usuarioId, ?string $de, ?string $ate): array
resumoUsuario(int $usuarioId, ?string $de, ?string $ate): array
serieUsuario(int $usuarioId, string $de, string $ate): array
serieCampanha(int $campanhaId, int $usuarioId, string $de, string $ate): array
topCampanhas(int $usuarioId, string $de, string $ate, string $ordem, int $limite): array

RelatorioService

gerar(int $usuarioId, array $dados): array
buscar(int $id, int $usuarioId): array
listar(int $usuarioId, array $filtros, int $page, int $perPage): array
porCliente(int $clienteId, int $usuarioId): array
resumo(int $usuarioId): array
atualizarSnapshot(int $id, int $usuarioId): array

LeadService

criar(int $usuarioId, array $dados): array
atualizar(int $id, int $usuarioId, array $dados): array
mover(int $id, int $usuarioId, string $novoEstagio, ?string $motivoPerda): array
registrarInteracao(int $leadId, int $usuarioId, string $tipo, string $descricao): array
excluir(int $id, int $usuarioId): void
pipeline(int $usuarioId, array $filtros): array
coluna(int $usuarioId, string $estagio, array $filtros, int $offset, int $limit): array
resumo(int $usuarioId): array

WebhookService

receber(string $origem, string $corpo, array $headers, ?string $ip): array

O serviço valida a assinatura configurada para a origem, evita reprocessar
eventos da mesma origem/ID que já estejam processando ou processados, persiste
o evento em webhook_eventos e enfileira ProcessarWebhookJob na fila
webhooks. O retorno contém aceito e, quando aplicável, evento_id,
duplicado ou motivo.

Integração de formulário próprio

POST /integracoes/leads é uma rota pública, sem sessão e sem CSRF, destinada
ao backend de uma landing page. A rota não recebe nem utiliza a URL da landing
page: o backend do formulário envia os dados para este endpoint.

O id precisa ser único por envio e serve à deduplicação. Um reenvio só retorna
200 already_accepted se o evento anterior já estiver processando ou
processado; enquanto estiver pendente, pode ser aceito e enfileirado novamente.
O job também verifica se o lead daquele formulário já existe antes de criá-lo.
campanha_id deve identificar uma campanha existente; o processamento deriva
dela o cliente e o usuário proprietários, e cria o lead com origem
formulario_proprio. O segredo FORMULARIO_SECRET deve estar configurado no
.env da plataforma e no backend da landing page, nunca no JavaScript entregue
ao navegador. Consulte
CONECTOR-FORMULARIO-PROPRIO.md para o
exemplo completo de integração e configuração.

QueueWorker

tick(?string $fila): int
work(?string $fila, ?int $maxCiclos): int

3. Eventos canônicos (EventoUsoService::EVENTOS)

auth.registro
auth.confirmacao
auth.login
cliente.criado
campanha.criada
diagnostico.iniciado
diagnostico.concluido
plano.criado
metrica.lancada
relatorio.gerado
lead.criado
lead.convertido
onboarding.passo
onboarding.completo
webhook.processado

Eventos fora dessa lista são gravados com prefixo outros. para auditoria,
mas não contam no funil canônico.