Selecionar Fundo
Introdução
Este recurso cria (ou reativa) uma adesão a fundo (fund_adhesion) durante a própria análise cadastral, vinculando o investidor a uma série de emissão (issuance_serie_key) de um fundo de investimento. É assim que um investidor declara, ainda no cadastro, interesse em aderir a um ou mais fundos — para que, ao final da análise, o termo de adesão já seja gerado e assinado junto com a ficha cadastral, em uma única leva de assinatura.
A seleção de fundos é opcional e está disponível para os três tipos de investidor (Pessoa Física, Pessoa Jurídica e Classe de Fundo — esta última tipicamente ao montar um fundo que aplica em cotas de outro fundo). Se nenhum fundo for selecionado durante o cadastro, o investidor é aprovado normalmente e a adesão a fundos passa a ser resolvida pelos fluxos usuais de aplicação (boletim de subscrição), fora da análise cadastral.
Só é possível criar uma adesão enquanto a análise está em pending_registry_data — ou seja, durante o preenchimento do cadastro, antes do submit.
Diferente do que a posição no fluxograma desta seção sugere, não há exigência de sequência com nenhuma outra etapa — o único requisito é o pending_registry_data acima. Você pode chamar este endpoint logo depois de criar o investidor, antes de patrimônio ou suitability: se investor_category/suitability ainda não tiverem sido enviados, a adesão fica em selected até a checagem de elegibilidade ser recalculada automaticamente depois. Chamar cedo é, inclusive, o padrão usado internamente — o modal de convite de investidor do Gestor cria a adesão logo após o POST de criação, antes de patrimônio/suitability existirem.
Input / Output
Como input envie o issuance_serie_key da série de emissão desejada. Na prática, o cliente raramente tem esse identificador de cara — normalmente só o CNPJ do fundo. Use Buscar Fundo por CNPJ primeiro para descobrir as séries de um fundo e obter o issuance_serie_key.
Como output será retornada a adesão criada, já com o resultado da checagem de elegibilidade.
Request
/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/fund_adhesionPOST201Request body
{
"issuance_serie_key": "1de4125b-48c7-40ca-b97b-0b65fb356468"
}
Body params
| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
issuance_serie_key | string | Chave (UUID) da série de emissão do fundo desejado | Sim |
Response
{
"fund_adhesion_key": "UUID",
"issuance_serie_key": "1de4125b-48c7-40ca-b97b-0b65fb356468",
"investor_adhesion_key": null,
"status": "selected",
"suitability_nonconformity": false
}
Fund Adhesion
| Campo | Tipo | Descrição |
|---|---|---|
fund_adhesion_key | string | Chave única da adesão |
issuance_serie_key | string | Chave da série de emissão selecionada |
investor_adhesion_key | string | Chave da adesão no sistema de aplicações — null até a adesão ser aprovada e gerar os termos |
status | string | Enumerador de Status da Adesão |
suitability_nonconformity | boolean | true quando o perfil de suitability do investidor é inferior ao exigido pela série |
Status da Adesão
| Enumerador | Descrição |
|---|---|
selected | Fundo escolhido, aguardando o resultado da checagem de elegibilidade. Estado inicial de toda adesão |
approved | Elegível — o enquadramento do investidor (investor_category) atende à qualificação exigida pela série |
rejected | Elegibilidade negada — o enquadramento do investidor é inferior ao exigido pela série |
adhered | Termo de adesão assinado — o vínculo com o fundo foi efetivado |
canceled | Adesão removida via Remover Fundo, ou cancelada automaticamente com a análise |
Quando você consulta a análise por investor_analysis_key (Consulta de Análise), o status pode vir como signed — um valor que só aparece ali, quando a adesão já virou uma aplicação assinada fora do cadastro. Não é um valor que você envia nem que aparece em Selecionar Fundo, Remover Fundo ou Listar Fundos Vinculados.
A elegibilidade (selected → approved/rejected) depende do enquadramento (investor_category, definido em Enviar Patrimônio) e é recalculada automaticamente sempre que o patrimônio ou o suitability do investidor forem atualizados — não é necessário selecionar o fundo novamente após uma correção de patrimônio.
Não há webhook para essa transição. Diferente da análise cadastral (que notifica por investor_analysis_status_change) e dos lotes de documentos (document_batch_status_change), a mudança de status de uma adesão causada por essa recálculo automático não gera webhook. Se sua integração precisa saber quando uma adesão selected foi resolvida, consulte Listar Fundos Vinculados por polling, ou releia a análise após reenviar patrimônio/suitability.
Uma série com qualificação qualified ou professional rejeita (status: rejected) um investidor retail. Enquanto houver uma adesão rejected, o Enviar Cadastro para Análise é recusado com IVR000233 — remova a adesão ou atualize o patrimônio do investidor para uma qualificação compatível antes de reenviar.
Enquanto a elegibilidade ainda não foi resolvida (status: selected), o submit também é recusado, com IVR000235.
Quando o perfil de suitability do investidor é inferior ao exigido pela série, a adesão não é bloqueada — mas suitability_nonconformity retorna true. Nesse caso, ao aprovar a adesão a QI Tech gera, além do termo de adesão, um termo de ciência de não conformidade (nonconformity_term) para assinatura, conforme exigido pela Resolução CVM nº 30. Veja os documentos gerados em Buscar Documentos Para Assinatura.
Erros específicos
| Código | HTTP | Situação |
|---|---|---|
IVR000231 | 404 | A série de emissão informada não foi encontrada |
IVR000234 | 403 | A integração está autenticada como Gestor e não é a gestora da classe de fundo da série informada |
IVR000236 | 409 | A série já está vinculada a este investidor — em outra análise ou já como uma adesão efetivada |