Ciclo de vida da análise cadastral
Introdução
Depois do submit, a análise cadastral deixa de depender de você e passa a evoluir de forma assíncrona. Esta página descreve as etapas do fluxo, em quais situações o cadastro volta a exigir a sua ação e como acompanhar tudo isso por webhook.
As etapas do fluxo
O cadastro percorre a sequência abaixo. As etapas 3 e 4 são condicionais: um cadastro sem pendências vai direto da análise automática para a aprovação.
| # | Etapa | Status da análise | Quem age |
|---|---|---|---|
| 1 | Preenchimento — dados cadastrais, endereço, patrimônio, suitability, contas, partes relacionadas e documentos | created → pending_registry_data | Você |
| 2 | Análise automática — motores de risco e PLD processam o cadastro e produzem uma decisão: aprovação, recusa, ou encaminhamento para revisão humana | sent_to_analysis | QI Tech (automático) |
| 3 | Análise manual (condicional) — um analista revisa os dados cadastrais. Esta etapa é pulada quando o cadastro é aprovado automaticamente | in_manual_analysis | QI Tech (analista) |
| 4 | Análise de compliance (condicional) — revisão de PLD/compliance. Também é pulada quando o cadastro é aprovado automaticamente | in_compliance_analysis | QI Tech (analista) |
| 5 | Documentos e assinatura — aprovada a análise, a QI Tech gera o lote de documentos de formalização e o cadastro segue para assinatura | automatically_approved / manually_approved → pending_documents | Depende da configuração da sua conta |
| 6 | Conclusão — o investidor está apto a operar | analysis_complete | — |
Um cadastro completo e sem indicadores de risco vai de sent_to_analysis direto para automatically_approved. Quando você observa in_manual_analysis ou in_compliance_analysis, significa apenas que aquele cadastro foi encaminhado para revisão humana — não é um erro e não exige ação sua enquanto durar.
A geração dos documentos e a coleta da assinatura variam conforme a sua integração seja configurada para que a QI Tech assuma essas responsabilidades, para assinatura por opt-in, ou para geração e assinatura externas. Consulte Buscar Lotes de Documentos para Assinatura e confirme com o seu contato técnico como a sua conta está configurada.
Quando o cadastro precisa da sua ação
Existem três situações, e só três, em que a bola está do seu lado depois do submit:
| Situação | Status | O que fazer |
|---|---|---|
| Devolução para esclarecimentos | pending_registry_data | Prestar o esclarecimento pedido e reenviar com o submit, na mesma análise. |
| Recusa manual | manually_reproved | Abrir uma nova análise cadastral com as correções do parecer. |
| Assinatura | pending_documents | Submeter documentos assinados, ou aguardar assinatura do cotista, dependendo da configuração/papel. |
Em todos os demais status — sent_to_analysis, in_manual_analysis, in_compliance_analysis, automatically_approved, manually_approved — o cadastro está com a QI Tech e não há nada a fazer além de aguardar.
Devolução para esclarecimentos
Acontece na etapa 4, a análise de compliance. Quando o analista de compliance precisa de um complemento ou de um esclarecimento para concluir a avaliação, ele abre um feedback e devolve a análise para pending_registry_data. A análise volta a ser editável e o ciclo recomeça na etapa 1: você atende ao que foi pedido e chama o submit de novo, na mesma análise.
O feedback é o canal desse pedido — é nele que está o texto do que precisa ser esclarecido.
- Consulte os feedbacks com Listar Feedbacks, usando
origin_type=investor_analysiscom ainvestor_analysis_key, eorigin_type=related_party_analysiscom cadaexternal_related_party_key - Atenda ao que foi pedido — reenvie o documento, atualize a parte relacionada, complemente o dado cadastral
- Registre a resposta, se quiser deixar um esclarecimento por escrito, com Enviar Mensagem em Feedback
- Reenvie a análise com o
submit
A etapa de análise manual (etapa 3) não abre feedbacks: ela termina em aprovação ou em recusa. Se a sua integração recebeu um feedback, ele veio da análise de compliance.
Não existe endpoint para marcar um feedback como respondido. Ele permanece open até que um analista da QI Tech avalie o que você enviou e o encerre. Isso é esperado — o que destrava o fluxo é o submit, não o status do feedback.
Recusa
A recusa é o caminho mais comum quando um cadastro não é aprovado, e vem em duas formas:
automatically_reproved— recusa de compliance, aplicada automaticamente logo após osubmit, ainda na etapa 2. O cadastro sequer chega à revisão humana.manually_reproved— recusa por um analista, na etapa 3 ou 4, quando o cadastro não reúne os dados mínimos para aprovação. Vem acompanhada de um parecer.
Nos dois casos a análise é terminal: ela não volta atrás, e nenhum dado dela pode mais ser alterado — tentativas de atualizar partes relacionadas, contas ou documentos são recusadas com IVR000185.
O caminho é abrir uma nova análise cadastral para o mesmo investidor, por meio de Atualização Cadastral, e refazer o preenchimento com as correções indicadas.
A devolução (pending_registry_data) mantém a mesma análise e pede um esclarecimento pontual de compliance. A recusa encerra a análise e exige começar uma nova. Se a sua integração trata os dois casos igual, ela vai abrir análises desnecessárias — ou deixar de abrir as que precisa.
Referência de status da análise
| Status | Etapa | Significado | Ação esperada de você |
|---|---|---|---|
created | 1 | Análise recém-aberta | Preencher os dados cadastrais |
pending_registry_data | 1 | Aguardando dados e documentos — ou devolvida para esclarecimentos | Completar/esclarecer e enviar o submit |
sent_to_analysis | 2 | Em processamento | Aguardar |
in_manual_analysis | 3 | Em revisão por um analista (etapa condicional) | Aguardar |
in_compliance_analysis | 4 | Em revisão de compliance (etapa condicional) | Aguardar |
automatically_approved | 5 | Aprovada sem intervenção humana | Aguardar a geração dos documentos |
manually_approved | 5 | Aprovada por um analista | Aguardar a geração dos documentos |
pending_documents | 5 | Documentos gerados, aguardando assinatura | Depende da configuração da sua conta |
automatically_reproved | — | Recusada automaticamente pela análise de compliance | Abrir nova análise cadastral |
manually_reproved | — | Recusada por um analista, com parecer | Abrir nova análise cadastral com as correções |
analysis_complete | 6 | Cadastro concluído — o investidor está apto a operar | Nenhuma |
expired | — | Cadastro vencido (2 anos após a conclusão) | Abrir nova análise para renovação |
Webhooks
O acompanhamento por webhook é a forma recomendada de seguir a análise — a alternativa é consultar periodicamente Busca informações do investidor, o que não escala.
Os webhooks são configurados internamente pela QI Tech, por integração. Não há endpoint público de cadastro. Informe ao seu contato técnico a URL que deve receber as notificações e quais eventos deseja assinar.
Eventos disponíveis
| Evento | Quando dispara |
|---|---|
investor_registry.investor_analysis_result | Resultado da análise automática — saída de sent_to_analysis para automatically_approved, in_manual_analysis ou automatically_reproved |
investor_registry.investor_analysis_status_change | Qualquer outra mudança de status da análise, incluindo a devolução para pending_registry_data e as decisões manuais (manually_approved, manually_reproved) |
investor_registry.feedback_status_change | Abertura e encerramento de feedback — dispara quando um feedback passa a open e quando é encerrado (closed) |
investor_registry.document_batch_status_change | A cada mudança de status do lote de documentos para assinatura |
Formato do evento
Eventos de análise carregam a chave da análise e o novo status:
{
"webhook_type": "investor_registry.investor_analysis_status_change",
"webhook_datetime": "2026-07-31T21:47:46Z",
"data": {
"investor_analysis_key": "UUID",
"status": "pending_registry_data"
}
}
Eventos de feedback carregam também a identificação do feedback e da sua origem:
{
"webhook_type": "investor_registry.feedback_status_change",
"webhook_datetime": "2026-07-31T21:47:46Z",
"data": {
"investor_analysis_key": "UUID",
"feedback_key": "UUID",
"status": "open",
"origin_type": "investor_analysis",
"origin_key": "UUID"
}
}
O evento carrega apenas as chaves e o novo status. Ao recebê-lo, consulte a análise — ou o feedback — para obter o detalhe.
Assine, no mínimo, investor_analysis_result e investor_analysis_status_change. Juntos, eles cobrem as três situações da seção Quando o cadastro precisa da sua ação: a recusa automática chega no primeiro; a devolução para pending_registry_data e a recusa manual, no segundo. O feedback_status_change complementa, avisando qual pedido foi aberto na devolução.