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 ao fundo já seja gerado e assinado junto com a ficha cadastral, em uma única leva de assinatura.
O Termo de Adesão é o documento que formaliza a adesão do investidor ao fundo, e o investidor só pode aportar no fundo depois de assiná-lo. Cada adesão aprovada nesta etapa gera um Termo de Adesão (document_type: "adhesion_term") no lote de documentos para assinatura; a adesão passa a adhered quando o termo é assinado.
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, mas ainda não pode aportar em nenhum fundo — os serviços de adesão e de cotas recusam o aporte sem Termo de Adesão assinado. O termo precisa ser obtido depois, fora da análise cadastral, por Solicitar Termo de Adesão.
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 para Termo de Adesão 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.
| Perfil | Host |
|---|---|
| Distribuidor | distributor-api |
URL base de cada host: Ambientes (Hosts).
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, releia a análise por polling em Consulta Informações de uma Análise Cadastral do Investidor (campo fund_adhesions), por exemplo 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
| 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 |
Erros de autenticação, permissão e host: veja Erros da API.