Criar investidor

---

Introdução

Este recurso tem como objetivo nos informar dados básicos para iniciar o cadastro de um investidor.

A criação de um investidor já dispara, em conjunto, a abertura de uma primeira análise cadastral vinculada a ele. Por isso, ao final desta chamada são retornadas duas chaves: investor_key (identifica o investidor) e investor_analysis_key (identifica a análise cadastral em andamento).

O campo person_type define se o investidor é pessoa física (natural_person) ou pessoa jurídica (legal_person). Dentro de pessoa jurídica, o campo investor_sub_type distingue uma empresa comum (default) de uma classe de fundo de investimento (fund_class), que segue regras próprias ao longo de todo o fluxo.

Regra de aprovação em sandbox

Em sandbox, o resultado da análise depende do primeiro dígito do CPF/CNPJ: início 1 → reprovação automática; início 8 → análise manual; os demais são aprovados automaticamente.

Usuário de acesso do investidor

Por padrão, a criação também cria o usuário de acesso do investidor na plataforma (query param create_investor_user, default true). Se o investidor não vai preencher o próprio cadastro, envie ?create_investor_user=false.

Input / Output

Como input envie os dados básicos do investidor. Os campos obrigatórios variam de acordo com person_type e investor_sub_type.

Como output serão retornadas a investor_key e a investor_analysis_key. A investor_key identifica o investidor; a investor_analysis_key identifica a análise cadastral aberta junto com a criação. Um mesmo investidor pode possuir mais de uma análise cadastral ao longo do tempo (renovações, atualizações).

Disponível em

Perfil	Host	Permissão exigida
Gestora	manager-api	Escrita
Consultoria	consultant-api	Liberada pelo time de integração

URL base de cada host: Ambientes (Hosts).

Request

ENDPOINT

/investor_registry/investor

MÉTODO

POST

STATUS

201

Request body

Caso 01: Pessoa Física

Request Body

{
    "name": "João da Silva",
    "document_number": "969.698.790-03",
    "person_type": "natural_person",
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "987654321"
    }
}

Caso 02: Pessoa Jurídica

Request Body

{
    "name": "Empresa XPTO Ltda",
    "document_number": "22.333.444/0001-81",
    "person_type": "legal_person",
    "investor_sub_type": "default",
    "registry_user": {
        "name": "José da Silva",
        "document_number": "969.698.790-03",
        "email": "jose.silva@example.com",
        "phone": {
            "international_dial_code": "55",
            "area_code": "11",
            "number": "987654321"
        }
    }
}

Caso 03: Classe de Fundo de Investimento (fund_class)

Request Body

{
    "name": "Fundo XPTO Multimercado",
    "document_number": "22.333.444/0001-81",
    "person_type": "legal_person",
    "investor_sub_type": "fund_class"
}

Campos obrigatórios

Os campos obrigatórios mudam de acordo com o person_type. A ausência de qualquer um deles é recusada com IVR000009, cuja mensagem lista a relação completa exigida.

• natural_person: name, document_number, person_type, email e phone
• legal_person: name, document_number, person_type. Para fund_class, não envie registry_user — a representação é feita pelos investor owners (administrador e gestora)

investor_sub_type é opcional. Se omitido, pessoa física fica default e, para pessoa jurídica residente, o subtipo é identificado pelo CNPJ: financial_institution se for uma instituição financeira registrada, fund_class se for uma classe registrada na CVM e default nos demais casos. Se você informar o subtipo, ele precisa bater com o CNPJ (veja Erros).

Classes de fundo: quem pode cadastrar

Pela gestora (manager-api), a criação de um investidor fund_class só é aceita se o CNPJ da gestora constar na CVM como gestora ou administradora da classe; caso contrário, IVR000260. A administradora e a gestora da classe também precisam estar cadastradas como investidoras na QI Tech. Veja Introdução para o detalhamento.

Apenas classes em funcionamento

Somente classes operacionais na CVM podem ser cadastradas. Classes pré-operacionais, encerradas, canceladas ou incorporadas são recusadas na análise. Se o CNPJ não constar na base da CVM, o submit é recusado com IVR000068.

O que a CVM preenche por você

Para fund_class, parte dos dados cadastrais é preenchida automaticamente a partir da base pública da CVM no momento do envio para análise — incluindo razão social, data de constituição, patrimônio e os vínculos com administrador, gestora e (quando aplicável) investidor exclusivo.

Como consequência, endereço, patrimônio, suitability, grupos de assinantes e documentos do investidor não são enviados para esse subtipo. Consulte Quais etapas se aplicam a cada tipo.

Sobre o registry_user

O registry_user representa o usuário (pessoa física) responsável por preencher os dados cadastrais do investidor. Para pessoa física, normalmente este usuário é o próprio investidor e o campo pode ser omitido. Para pessoa jurídica, é o representante que responderá pelo preenchimento.

Body params

Campo	Tipo	Descrição	Caracteres	Obrigatório
name	string	Nome (ou razão social) do investidor	1 - 255	Sim
person_type	string	Enumerador de Person Type	-	Sim
document_number	string	CPF (XXX.XXX.XXX-XX) ou CNPJ (XX.XXX.XXX/XXXX-XX). Para fund_class, o CNPJ da classe registrada na CVM	14 ou 18	Sim*
investor_sub_type	string	Enumerador de Investor Sub Type. Se omitido, é inferido (veja acima)	-	Não
email	string	E-mail do investidor. Obrigatório para natural_person	1 - 255	Condicional
phone	object	Objeto de Phone. Obrigatório para natural_person	-	Condicional
registry_user	object	Objeto de Registry User	-	Não
resident	boolean	Se o investidor é residente no Brasil. Default true	-	Não
non_resident_type	string	self_representation ou third_party_representation. Obrigatório quando resident: false	-	Condicional

Phone

Campo	Tipo	Descrição	Caracteres	Obrigatório
international_dial_code	string	Código internacional (ex.: 55)	1 - 3	Sim
area_code	string	DDD	2	Sim
number	string	Número do telefone	8 - 9	Sim

Registry User

Campo	Tipo	Descrição	Caracteres	Obrigatório
name	string	Nome do usuário cadastrador	1 - 255	Sim
document_number	string	CPF do usuário (formato XXX.XXX.XXX-XX)	14	Sim
email	string	E-mail do usuário	1 - 255	Sim
phone	object	Objeto de Phone	-	Não

Person Type

Enumerador	Descrição
natural_person	Pessoa física
legal_person	Pessoa jurídica

Investor Sub Type

Enumerador	Descrição
default	Investidor regular, pessoa física ou jurídica
financial_institution	Instituição financeira (somente legal_person)
fund_class	Classe de fundo de investimento (somente legal_person) — dispara o enriquecimento automático com os dados públicos da CVM e segue regras próprias de etapas, partes relacionadas e investor owners

O valor non_resident é recusado com IVR000255: a residência é declarada pelos campos resident e non_resident_type, não pelo subtipo.

Response

Response Body

{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID",
    "resident": true
}

A resposta também traz o objeto distributor e, para investidor não residente, non_resident_type.

Investidor que já existe

Se outro agente já cadastrou um investidor com o mesmo documento, nenhum investidor novo é criado: ele passa a ser vinculado a você e a resposta traz apenas a investor_key.

Erros

Status	Código	Quando acontece
400	IVR000004	CPF/CNPJ com dígito verificador inválido, ou CPF enviado com legal_person (e vice-versa)
400	IVR000009	Falta um campo obrigatório do person_type — por exemplo, email ou phone em pessoa física
400	IVR000222	resident: false sem non_resident_type
400	IVR000064	investor_sub_type fund_class ou financial_institution enviado com natural_person
400	IVR000255	investor_sub_type: non_resident. Use resident: false e non_resident_type
400	IVR000256 / IVR000257	Subtipo declarado não confere com o CNPJ: financial_institution sem instituição registrada, ou fund_class sem classe na CVM
400	IVR000258 / IVR000259	Subtipo default declarado para um CNPJ que é instituição financeira registrada ou classe na CVM
403	IVR000260	Gestora tentando cadastrar uma classe de fundo da qual não é gestora nem administradora
409	IVR000007	Você já cadastrou um investidor com este documento

Erros de autenticação, permissão e host: veja Erros da API.