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`	—

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 e não exige ação sua enquanto durar.

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, 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_analysis com a investor_analysis_key, e origin_type=related_party_analysis com cada external_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

Feedback só existe na análise de compliance

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.

Você não fecha um feedback

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 o submit, 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.

Recusa e devolução são coisas diferentes

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.

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` 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 Body — análise
{
    "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 Body — 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"
    }
}

O evento carrega apenas as chaves e o novo status. Ao recebê-lo, consulte a análise — ou o feedback — para obter o detalhe.

Os dois eventos que exigem ação sua

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.

Introdução​

As etapas do fluxo​

Quando o cadastro precisa da sua ação​

Devolução para esclarecimentos​

Recusa​

Referência de status da análise​

Webhooks​

Eventos disponíveis​

Formato do evento​