Dinâmica dos status

A API de Análise cadastral trabalha com três enumeradores de status independentes. Entender a diferença entre eles é o passo que mais evita erro de integração:

Enumerador	Quem define o valor	Quem devolve	O que representa
analysis_status	Você, na sua política	QI Tech	O resultado da execução da sua árvore de decisão.
risk_level	Você, na sua política	QI Tech	O nível de risco atribuído pela sua árvore de decisão.
client_status	Você	—	A situação do cliente na sua plataforma.

analysis_status e risk_level saem da sua própria política

Esses dois campos não são um veredito nosso sobre o cadastro. Eles são definidos por você, no motor de regras, através das caixinhas de decisão e de nível de risco que você posiciona ao longo da sua árvore.

A cada requisição, a QI Tech executa essa árvore contra os dados analisados e devolve o resultado que a sua política determinou. Se você quer que um cenário passe a cair em in_manual_analysis em vez de automatically_reproved, ou que um perfil receba risk_level: high em vez de medium, a mudança é no motor de regras — não há nada a alterar na integração.

A regra prática

analysis_status é o resultado da sua política, executada por nós. client_status é a sua decisão de negócio, que você registra via PUT conforme a jornada do cliente evolui.

Como a decisão é produzida

1. Você desenha a árvore de decisão no motor de regras, posicionando as caixinhas de decisão (analysis_status) e de nível de risco (risk_level) conforme a sua política.
2. Você envia o cadastro para a API.
3. A QI Tech executa a árvore contra os dados do cadastro e os enriquecimentos disponíveis.
4. A resposta traz o analysis_status e o risk_level que a sua árvore determinou para aquele caso.

Por isso, dois clientes que enviam exatamente o mesmo cadastro podem receber respostas diferentes: cada um tem a sua própria política configurada.

---

analysis_status

Resultado da execução da sua árvore de decisão. Os status abaixo se dividem em três grupos pelo que você deve fazer com cada um.

Decisões finais

Status	Significado	Ação
automatically_approved	A sua árvore de decisão terminou em uma caixinha de aprovação automática.	Pode aprovar o cadastro.
automatically_reproved	A sua árvore de decisão terminou em uma caixinha de reprovação automática.	Recuse o cadastro.
manually_approved	Aprovado por um analista.	Pode aprovar o cadastro.
manually_reproved	Reprovado por um analista.	Recuse o cadastro.
approved_by_time	Aprovado automaticamente após expirar o prazo de análise.	Pode aprovar o cadastro.
reproved_by_time	Reprovado automaticamente após expirar o prazo de análise.	Recuse o cadastro.

Aguardando — o resultado chega por webhook

Status	Significado	Ação
in_queue	Análise assíncrona em fila.	Aguarde o Webhook.
pending	As consultas estão demorando mais que o esperado.	Aguarde o Webhook.
in_manual_analysis	Derivado para análise manual por um analista.	Aguarde o Webhook.
waiting_for_data	Aguardando dados complementares para processar.	Aguarde o Webhook.
on_hold	Análise pausada, aguardando retorno do cliente.	Aguarde o Webhook.

Não trate "aguardando" como recusa

in_queue, pending, in_manual_analysis, waiting_for_data e on_hold não são negativas. Tratá-los como reprovação é o erro de integração mais comum nesta API — recusa cadastros legítimos que seriam aprovados minutos depois.

Contestação e casos especiais

Status	Significado	Ação
automatically_challenged	A sua árvore terminou em uma caixinha de contestação.	O cadastro precisa passar pelo fluxo de contestação.
manually_challenged	Contestado por um analista.	Idem.
manually_cancelled	Análise cancelada.	Nenhuma decisão será emitida.
failed	A análise falhou durante o processamento.	Reenvie com um novo id ou acione o suporte.
not_analysed	Enviado com analyze=false.	Nenhuma recomendação será emitida; siga sua própria decisão.

---

client_status

Situação cadastral do cliente na sua plataforma. Você é responsável por manter esse status atualizado via PUT — ele alimenta os modelos e melhora análises futuras.

Status	Significado
registered	Registrado, sem decisão de aprovação ainda.
approved	Aprovado na sua plataforma.
reproved	Reprovado na sua plataforma.
fraud_blocked	Bloqueado por suspeita ou confirmação de fraude.
default_blocked	Bloqueado por inadimplência.
cancelled	O cliente cancelou o uso do serviço.

Grafia do enumerador

O valor correto é cancelled, com dois L. Versões antigas desta documentação grafavam canceled — esse valor é rejeitado com HTTP 400.

Quais valores podem ser enviados

O método usado determina os valores aceitos:

Tipo de cadastro	Valores aceitos no PUT
Natural Person	approved, reproved, fraud_blocked, default_blocked, cancelled
Legal Person	fraud_blocked, default_blocked, cancelled

Legal Person aceita menos valores

Em Legal Person, o PUT não aceita approved nem reproved — apenas os três valores de bloqueio e cancelamento. Enviar approved em um cadastro PJ retorna HTTP 400.

Detalhes em Atualizar um cadastro.

---

risk_level

Nível de risco atribuído ao cadastro pela caixinha de nível de risco que a sua árvore percorreu. Presente na resposta do GET e nos eventos de análise.

Valor	Significado
low	Risco baixo.
medium	Risco médio.
high	Risco alto.
critical	Risco crítico.
undefined	Nenhuma avaliação de risco foi realizada.

---

Fluxo típico

1. Você envia o cadastro — POST /onboarding/natural_person.
2. A resposta traz um analysis_status.
   • Se for uma decisão final, siga o que a sua política determinou.
   • Se for aguardando, espere o webhook.
3. Ao decidir na sua plataforma, envie o client_status via PUT.