Template
Um template é a configuração do bureau criada no dashboard. Ele define:
- Quais fontes de dados consultar
- Quais regras de risco aplicar
- Quais checks geram bloqueio vs. pendência vs. análise manual
A API recebe um template_id e executa exatamente o que o compliance configurou — você não precisa entender as regras internas. Quando o compliance ajustar as regras, os próximos runs usam as novas configurações automaticamente.
Run
Um run é a execução do bureau para um CPF ou CNPJ específico. Cada chamada ao POST /bureau/runs cria um run.
Ciclo de vida
queued → running → completed (decisão: approved / review)
→ blocked (decisão: rejected — bloqueado por regra crítica)
→ pending_review (aguardando análise manual do compliance officer)
→ partial (algumas fontes falharam, mas decisão possível)
→ failed (falha técnica — reenviar o run)
| Status | Significado |
|---|
queued | Run criado, aguardando início |
pending / running | Bureau em execução |
completed | Finalizado com decisão |
blocked | Bloqueado por regra crítica |
pending_review | Análise manual necessária |
partial | Resultado parcial — algumas fontes falharam |
failed | Falha técnica — envie novamente |
Decision
O campo decision é o resultado final do bureau:
decision | Significado |
|---|
approved | Aprovado para prosseguir com onboarding ou operação |
rejected | Bloqueado por regra crítica — não reverter sem análise manual |
review | Requer análise do compliance officer no dashboard |
null | Run ainda em andamento ou com falha técnica |
Risk band
Classificação de risco calculada pelo engine com base nos checks:
risk_band | Nível |
|---|
baixo | Risco baixo, sem apontamentos relevantes |
medio | Risco médio, apontamentos de pendência identificados |
alto | Risco alto, apontamentos críticos identificados |
null | Run ainda não concluído |
Checks
Cada fonte de dados gera um ou mais checks — verificações individuais com 4 status possíveis:
| Status | Significado |
|---|
VALID | Informação verificada, sem problema |
INVALID | Informação verificada, com problema (ex: CPF cancelado, PEP ativo, sanção OFAC) |
NO_DATA | Fonte não encontrou dados para o CPF/CNPJ |
ERROR | Falha técnica nesta fonte específica |
NO_DATA não é necessariamente um problema — significa que a fonte não tem registro daquele documento. A interpretação depende do contexto e das regras do template.
Status de bureau run vs status de cliente
A API usa dois vocabulários de status distintos que coexistem:
| Sistema | Valores | Onde aparece |
|---|
| Bureau run | completed, running, blocked, failed, pending_review | GET /bureau/runs |
| Cliente (onboarding) | aprovado, em_analise, pendencia, recusado | GET /customers |
decision: "approved" resulta em cliente com status: "aprovado".
Os valores de status de bureau run estão em inglês; os de cliente estão em português. Isso é intencional — os dois sistemas têm origens distintas e nunca são usados nos mesmos endpoints.
