Conceitos

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	Webhook event	Significado
`queued`	—	Run criado, aguardando início
`pending` / `running`	—	Bureau em execução
`completed`	`run.completed`	Finalizado com decisão de aprovação ou revisão
`blocked`	`run.completed`	Bloqueado por regra crítica (`decision: rejected`)
`pending_review`	`run.completed`	Análise manual necessária
`partial`	`run.completed`	Resultado parcial — algumas fontes falharam mas decisão foi possível
`failed`	`run.failed`	Falha técnica irrecuperável — run sem resultado de decisão

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

operative_decision

O campo operative_decision indica a decisão operacional do run. Na maioria dos casos é idêntico a decision, mas pode divergir quando uma fonte crítica (tier-1) falhou durante a execução. Disponível em: GET /bureau/runs/{id} e GET /bureau/runs/{id}/analysis. Não está presente no payload de webhook — use decision para automações baseadas em evento. Exemplo: se a Receita Federal estiver offline, decision pode ser "approved" (o engine aprovou com as fontes disponíveis), mas operative_decision será "rejected" porque uma fonte crítica não pôde ser consultada.

Cenário	`decision`	`operative_decision`	Ação recomendada
Aprovação plena	`approved`	`approved`	Prosseguir
Aprovação com fonte crítica offline	`approved`	`rejected`	Bloquear
Reprovação por regra	`rejected`	`rejected`	Bloquear
Revisão manual	`review`	`review`	Aguardar analista

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.

Diferenças entre webhook payload e GET `/runs/{id}`

Os dois formatos expõem campos distintos — não são idênticos:

Campo	Webhook payload	GET `/runs/{id}`
Identificador do run	`id`	`run_id`
Tipo do sujeito	`subject_type` ✓	ausente
Template	`template_id` ✓	ausente
Resumo de checks	`checks_summary` ✓	ausente
Nome do template	ausente	`template_name` ✓
Mensagem de decisão	ausente	`summary_message` ✓
Revisão manual pendente	ausente	`manual_review` ✓

Use o webhook para reagir a eventos em tempo real. Use o GET quando precisar dos campos adicionais (template_name, summary_message, manual_review) após o run completar.

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`

O status do cliente é derivado do resultado do bureau run mais recente. Um run com 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.

Começando

Guias

Webhooks

Referência da API

Template

Run

Ciclo de vida

Decision

operative_decision

Risk band

Checks

Diferenças entre webhook payload e GET `/runs/{id}`

Status de bureau run vs status de cliente

​Template

​Run

​Ciclo de vida

​Decision

​operative_decision

​Risk band

​Checks

​Diferenças entre webhook payload e GET /runs/{id}

​Status de bureau run vs status de cliente

Template

Run

Ciclo de vida

Decision

operative_decision

Risk band

Checks

Diferenças entre webhook payload e GET `/runs/{id}`

Status de bureau run vs status de cliente