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 — sempre para a frente. As etapas 3 e 4 são condicionais: um cadastro sem pendências vai direto da análise automática para a aprovação. Nenhuma etapa devolve a análise para o preenchimento: quando a compliance precisa de um esclarecimento, ela abre um feedback sem alterar o status da análise.
| # | 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. É a etapa em que um feedback pode ser aberto pedindo esclarecimentos | in_compliance_analysis | QI Tech (analista) — e você, se um feedback for aberto |
| 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 | Sinal | O que fazer |
|---|---|---|
| Feedback aberto | Um feedback com status: open — a análise permanece em in_compliance_analysis | Responder à mensagem do feedback. A sua resposta o encerra (closed) e a compliance retoma a avaliação. Não há novo submit. |
| 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 sem feedback aberto, automatically_approved, manually_approved — o cadastro está com a QI Tech e não há nada a fazer além de aguardar.
Feedback: pedido de esclarecimento
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 com a mensagem do que precisa ser esclarecido.
A análise não volta atrás. Ela permanece em in_compliance_analysis durante todo o ciclo do feedback — não retorna para pending_registry_data, não reabre para edição e não precisa de um novo submit. O feedback corre em paralelo à análise: abre em open, você responde, ele passa a closed e a compliance segue de onde parou.
- Receba o aviso pelo webhook
investor_registry.feedback_status_change, comstatus: open - Leia o pedido com Listar Feedbacks, usando
origin_type=investor_analysiscom ainvestor_analysis_key, eorigin_type=related_party_analysiscom cadaexternal_related_party_key. O texto está emdescriptione no histórico demessages - Responda com Enviar Mensagem em Feedback — a sua mensagem é a resposta ao pedido
- O feedback é encerrado (
closed) e um novoinvestor_registry.feedback_status_changeé disparado. Nada mais é exigido de você
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.
Como a análise continua em in_compliance_analysis, nenhuma mudança de status sinaliza um feedback aberto. A única notificação é o webhook investor_registry.feedback_status_change. Uma integração que só observa o status da análise não perceberá o pedido — e o cadastro ficará parado na compliance à espera de uma resposta que não virá.
Permanecer em in_compliance_analysis significa que os endpoints de preenchimento — dados cadastrais, documentos, partes relacionadas, contas — continuam recusando alterações. O canal de resposta ao feedback é a mensagem. Se o esclarecimento exigir alterar o cadastro em si, a compliance recusará a análise e você abrirá uma nova por meio de Atualização Cadastral.
Enviar a mensagem move o feedback de open para closed — não é preciso aguardar um analista da QI Tech encerrá-lo. Se a resposta não for suficiente, a compliance abre um novo 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.
O feedback não altera o status da análise: ela segue em in_compliance_analysis e o pedido é resolvido com uma mensagem. 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 para o envio inicial | Completar 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 — ou responder o feedback, se algum for aberto |
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 |
pending_registry_data não é status de retornoEle aparece uma única vez, no preenchimento inicial, antes do primeiro submit. Nenhuma etapa posterior devolve a análise para esse status — em particular, a abertura de um feedback não o faz.
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 as decisões manuais (manually_approved, manually_reproved) e a entrada em pending_documents |
investor_registry.feedback_status_change | Abertura e encerramento de feedback — ver Webhooks de feedback |
investor_registry.document_batch_status_change | A cada mudança de status do lote de documentos para assinatura |
Formato do evento — análise
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": "in_compliance_analysis"
}
}
Webhooks de feedback
O investor_registry.feedback_status_change é o único aviso de que um feedback foi aberto ou encerrado. Como a análise permanece em in_compliance_analysis durante todo o ciclo do feedback, nenhum evento de análise é disparado junto — quem não assinar este evento não fica sabendo do pedido.
O mesmo webhook_type cobre as duas pontas do ciclo, diferenciadas pelo campo status:
status | Quando dispara | Ação esperada de você |
|---|---|---|
open | A compliance abriu um feedback com um pedido de esclarecimento | Ler o pedido e responder com Enviar Mensagem em Feedback |
closed | O feedback foi encerrado pela sua resposta | Nenhuma — é a confirmação de que o pedido foi resolvido |
Abertura do feedback:
{
"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"
}
}
Encerramento do feedback, disparado logo após a sua mensagem:
{
"webhook_type": "investor_registry.feedback_status_change",
"webhook_datetime": "2026-07-31T22:12:03Z",
"data": {
"investor_analysis_key": "UUID",
"feedback_key": "UUID",
"status": "closed",
"origin_type": "investor_analysis",
"origin_key": "UUID"
}
}
| Campo | Tipo | Descrição |
|---|---|---|
investor_analysis_key | string | Análise cadastral à qual o feedback pertence |
feedback_key | string | Identificador do feedback |
status | string | open ou closed — enumerador de Feedback Status |
origin_type | string | Enumerador de Origin Type — investor_analysis ou related_party_analysis |
origin_key | string | Chave da entidade de origem: a investor_analysis_key ou a external_related_party_key |
O evento carrega apenas as chaves e o novo status — não traz o texto do pedido. Ao receber um open, chame Listar Feedbacks com o origin_type e o origin_key do evento para ler a description e o histórico de messages.
Assine, no mínimo, investor_analysis_result, investor_analysis_status_change e feedback_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 recusa manual e a ida para assinatura, no segundo; o pedido de esclarecimento, no terceiro — e só no terceiro.