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	—

As etapas 3 e 4 não são obrigatórias

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 etapa 5 depende da configuração da sua conta

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 em in_manual_analysis;
• feedback de compliance (category: compliance) — aberto com a análise em in_manual_analysis ou in_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.

1. Receba o aviso pelo webhook investor_registry.feedback_status_change, com status: open
2. Leia o pedido com Listar Feedbacks, usando origin_type=investor_analysis com a investor_analysis_key, e origin_type=related_party_analysis com cada external_related_party_key. O texto está em description e no histórico de messages
3. Responda com Enviar Mensagem em Feedback — o feedback passa a answered. Não há webhook nesse momento
4. A QI Tech encerra o feedback (closed) e um novo investor_registry.feedback_status_change é disparado

Gestora e consultoria

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.

Não acompanhe feedbacks pelo status da análise

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.

A análise continua bloqueada para edição

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 para in_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.

Recusa e feedback são coisas diferentes

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 retorno

Ele 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.

Configuração

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 Body — análise

{
    "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 Body — feedback aberto

{
    "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 Body — feedback encerrado

{
    "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.

Os eventos que exigem ação sua

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.