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. Nenhuma etapa devolve a análise para o preenchimento: quando a QI Tech precisa de um esclarecimento, ela abre um feedback sem alterar o status da análise.
Legenda: caixa tracejada é status interno, que você não verá na prática (created é substituído na mesma operação por pending_registry_data); azul, status intermediário; verde, conclusão do cadastro; vermelho, status final sem aprovação (recusa ou cancelamento).
| # | Etapa | Status da análise | Quem age |
|---|---|---|---|
| 1 | Preenchimento — dados cadastrais, endereço, patrimônio, suitability, contas, partes relacionadas e documentos | pending_registry_data | Você |
| 2 | Análise automática — motores de risco e PLD processam o cadastro e produzem uma decisão: aprovação, encaminhamento para revisão humana ou, para classes de fundo, recusa | sent_to_analysis | QI Tech (automático) |
| 3 | Análise manual (condicional) — um analista revisa os dados cadastrais. É aqui que podem ser abertos feedbacks de dados cadastrais (registry_data) | in_manual_analysis | QI Tech (analista) — e você, se um feedback for aberto |
| 4 | Análise de compliance (condicional) — revisão de PLD/compliance. Pode abrir feedbacks de compliance | 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 lote foi assinado e 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. Fique atento apenas a feedbacks abertos.
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 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 não muda de status | Responder à mensagem do feedback. Não há novo submit. |
| Recusa | manually_reproved ou automatically_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. |
Nos demais status — sent_to_analysis, in_manual_analysis e 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
Quando o analista precisa de um complemento ou de um esclarecimento, ele abre um feedback com a mensagem do que precisa ser esclarecido:
- feedback de dados cadastrais (
category: registry_data) — aberto com a análise emin_manual_analysis; - feedback de compliance (
category: compliance) — aberto com a análise emin_manual_analysisouin_compliance_analysis.
A análise não volta atrás. Ela 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: nasce open, passa a answered quando você responde, e a QI Tech o encerra (closed) quando a resposta resolve o pedido.
- 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 — o feedback passa a
answered. Não há webhook nesse momento - A QI Tech encerra o feedback (
closed) e um novoinvestor_registry.feedback_status_changeé disparado
Pelos hosts manager-api e consultant-api não há como responder a um feedback pela API: a consultoria só consegue listá-los. Para responder, fale com o time de integração em integracao.dtvm@qitech.com.br.
Como a análise não muda de status, nenhuma mudança de status sinaliza um feedback aberto. O aviso é o webhook investor_registry.feedback_status_change, emitido apenas para feedbacks abertos por um analista (type: manual). Feedbacks automáticos não geram webhook: consulte Listar Feedbacks enquanto a análise estiver em in_manual_analysis ou in_compliance_analysis.
Fora de pending_registry_data, os endpoints de preenchimento — dados cadastrais, documentos, partes relacionadas, contas — recusam alterações. O canal de resposta ao feedback é a mensagem. Se o esclarecimento exigir alterar o cadastro em si, a análise será recusada e uma nova precisará ser aberta.
Recusa
A recusa vem em duas formas:
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.automatically_reproved— recusa automática. Ocorre na validação de classes de fundo e, em sandbox, para documentos que começam com 1. Em produção, uma reprovação dos motores de risco de PF e PJ não encerra a análise: ela vai parain_manual_analysis, onde um analista decide.
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 e refazer o preenchimento com as correções indicadas. A exceção é a recusa definitiva: a análise volta com is_definitive_reproval: true, sem parecer, o investidor é inativado e uma nova análise é recusada com IVR000272.
O feedback não altera o status da análise 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 | — | Status interno de criação, substituído na mesma operação por pending_registry_data | — |
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 (classe de fundo; em sandbox, documento com início 1) | 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 |
canceled | — | Análise cancelada antes da conclusão. Encerra a análise e os lotes de documentos ainda não assinados | Abrir nova análise, se necessário |
expired | — | Reservado. Hoje o vencimento do cadastro é sinalizado no status do investidor (registry_expired), não no da análise | — |
pending_registry_data não é status de retornoEle aparece no preenchimento, antes do submit. Nenhuma etapa posterior do fluxo automático 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, in_compliance_analysis ou automatically_reproved |
investor_registry.investor_analysis_status_change | Decisões do analista: manually_approved, manually_reproved e as passagens entre in_manual_analysis e in_compliance_analysis. A entrada em pending_documents, o cancelamento e a conclusão (analysis_complete) não geram este evento |
investor_registry.feedback_status_change | Abertura e encerramento de feedback manual — 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 o feedback não altera o status da análise, nenhum evento de análise é disparado junto — quem não assinar este evento não fica sabendo do pedido. Ele é emitido apenas para feedbacks abertos por um analista (type: manual); a passagem para answered, quando você responde, não emite evento.
O mesmo webhook_type cobre as duas pontas do ciclo, diferenciadas pelo campo status:
status | Quando dispara | Ação esperada de você |
|---|---|---|
open | A QI Tech abriu um feedback com um pedido de esclarecimento | Ler o pedido e responder com Enviar Mensagem em Feedback |
closed | A QI Tech encerrou o feedback depois de avaliar a 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 quando a QI Tech o encerra:
{
"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, feedback_status_change e document_batch_status_change. Juntos, eles cobrem as três situações da seção Quando o cadastro precisa da sua ação: as recusas chegam pelos eventos de análise, a ida para assinatura pelo evento do lote e o pedido de esclarecimento pelo de feedback.