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

Existem 3 tipos principais de investidor, definidos pelo campo person_type: pessoa física (natural_person), pessoa jurídica (legal_person) e PCO ('nominee'). Para pessoas jurídicas, o campo investor_sub_type distingue subtipos como fundo de investimento (fund_class), que possuem regras próprias ao longo do fluxo de cadastro.

Atenção

Para os casos de investidores distribuídos por conta e ordem (PCO | nominee) não existe uma esteira cadastral e portanto, apenas o POST de criação é necessário para torná-lo apto em todo o sistema.

Informação

No ambiente de Homologação, temos a seguinte regra para aprovações: CPF/CNPJ com início 1: reprovação automática; CPF/CNPJ com início 8: pendente de validação manual; o restante é aprovado automaticamente.

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

Request

ENDPOINT

/investor_registry/v2/investor

MÉTODO

POST

STATUS

201

Request body

Caso 01: Pessoa Física

Request Body

{
    "name": "João da Silva",
    "document_number": "123.456.789-00",
    "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": "12.345.678/0001-90",
    "person_type": "legal_person",
    "investor_sub_type": "default",
    "registry_user": {
        "name": "José da Silva",
        "document_number": "123.456.789-00",
        "email": "jose.silva@example.com",
        "phone": {
            "international_dial_code": "55",
            "area_code": "11",
            "number": "987654321"
        }
    }
}

Caso 03: Pessoa Jurídica — Fundo de Investimento (fund_class)

Request Body

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

Caso 04: Nominee (PCO)

Request Body

{
    "name": "Nominee XPTO",
    "person_type": "nominee",
    "external_distribution_key": "ID-DISTRIBUICAO-001"
}

Campos obrigatórios por person_type

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, investor_sub_type
• legal_person: name, document_number, person_type, investor_sub_type
• nominee: name, person_type, external_distribution_key

investor_sub_type é obrigatório também para pessoa física — envie default quando não houver subtipo específico. email e phone são opcionais para um distribuidor, mas recomendados: sem email, nenhum usuário de acesso é criado para o investidor.

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.

Quando enviado, o objeto exige name, document_number e email. Se omitido em pessoa física, o usuário é derivado do email do próprio investidor — e, se o investidor também não tiver email, nenhum usuário é criado.

investor_owner_type não é aceito de distribuidores

Apesar de existir no schema, investor_owner_type é recusado quando o investidor é criado por uma integração de distribuidor com person_type natural_person ou legal_person. Vínculos de carteira administrada e de fundo são estabelecidos pelo endpoint Criar Investor Owner, dentro da análise cadastral.

Investidor não residente

A residência é definida na criação do investidor e é imutável depois disso. Ela é controlada pelo campo resident.

Request Body — pessoa física não residente

{
    "name": "Maria Fernandes",
    "document_number": "123.456.789-00",
    "person_type": "natural_person",
    "investor_sub_type": "default",
    "resident": false,
    "non_resident_type": "third_party_representation",
    "investor_owners": [
        {
            "type": "non_resident_representative",
            "name": "Representante Legal Brasil Ltda",
            "document_number": "12.345.678/0001-90"
        }
    ]
}

Campo	Tipo	Descrição	Obrigatório
resident	boolean	Define a residência da análise cadastral. Default true	Não
non_resident_type	string	self_representation ou third_party_representation. Obrigatório quando resident: false (IVR000222)	Condicional
investor_owners	array	Representante legal residente no Brasil, com type: "non_resident_representative"	Não

Tipos de representação

non_resident_type declara como o investidor não residente é representado no Brasil. É essa escolha que determina quais entidades você precisa cadastrar e quais documentos serão exigidos no envio para análise.

Enumerador	Tipo de conta	Significado
third_party_representation	Conta 4373	O INR opera por meio de terceiros: existe um custodiante, responsável pela guarda dos ativos, e um representante legal brasileiro, responsável por representá-lo no país. Na prática, costumam ser a mesma entidade.
self_representation	Conta CNR (autocustódia / representação tributária)	O investidor é seu próprio custodiante e representante. Não existe custodiante nem representante terceiro.

O que muda entre os dois:

	third_party_representation	self_representation
Custodiante	Parte relacionada do tipo asset_custodian	Não existe
Representante	Investor owner do tipo non_resident_representative — sempre residente, com CPF/CNPJ	Não existe
Documentos de representação	custody_contract (no custodiante) e representation_contract (no representante) — ou uma única simplified_declaration na análise	Nenhum

Como a exigência documental é verificada

Em third_party_representation, o custody_contract só é reconhecido quando enviado em uma parte relacionada ativa do tipo asset_custodian, e o representation_contract só é reconhecido quando enviado em um investor owner ativo do tipo non_resident_representative. Enviar os dois contratos como documentos da análise cadastral não satisfaz a regra.

Se a combinação não for encontrada no submit, a resposta é IVR000029.

Regras que valem para os dois tipos:

• nif_number é obrigatório no envio dos dados cadastrais (IVR000224);
• parte relacionada estrangeira sem CPF/CNPJ precisa de passport ou foreign_id;
• pessoa física nascida no Brasil (natural_person.place_of_birth.country: "BRA") precisa de final_departure_tax_return.

non_resident_type é imutável

O valor é fixado na criação do investidor. Você pode reenviá-lo nos dados cadastrais, mas apenas com o mesmo valor — divergência, ou envio em um cadastro residente, resulta em IVR000225.

Residência e endereço precisam concordar

Com resident: true (default), o endereço enviado na Etapa 3 precisa ter country: "BRA", senão IVR000227. Com resident: false, o country não pode ser BRA, senão IVR000226.

postal_code e uf não têm validação de formato, então códigos postais estrangeiros são aceitos como estão. Use EX em uf para endereços no exterior.

Investidores fund_class

Para fundos de investimento (investor_sub_type: "fund_class"), parte dos dados cadastrais é preenchida automaticamente a partir da base da CVM no momento do envio para análise — incluindo razão social, data de constituição, patrimônio e vínculos com administrador, gestor e (quando aplicável) investidor exclusivo. Veja o documento Criar Investor Owner para o cadastro de relações de propriedade adicionais.

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
investor_sub_type	string	Enumerador de Investor Sub Type. Exigido para natural_person e legal_person	-	Sim
document_number	string	CPF (XXX.XXX.XXX-XX) ou CNPJ (XX.XXX.XXX/XXXX-XX)	14 ou 18	Sim*
external_distribution_key	string	Identificador externo da distribuição (obrigatório para nominee)	1 - 100	Sim*
resident	boolean	Residência da análise cadastral. Default true. Veja Investidor não residente	-	Não
non_resident_type	string	self_representation ou third_party_representation. Exigido quando resident: false	-	Condicional
investor_owners	array	Representante legal residente, para investidor não residente	-	Não
email	string	E-mail do investidor	1 - 255	Não
phone	object	Objeto de Phone	-	Não
registry_user	object	Objeto de Registry User	-	Não
external_id	string	Identificador do investidor no seu sistema	1 - 50	Não

* document_number não deve ser enviado para person_type: nominee. external_distribution_key é exigido apenas para nominee.

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	-	Sim

Person Type

Enumerador	Descrição
natural_person	Pessoa física
legal_person	Pessoa jurídica
nominee	Nominee / PCO (sem documento obrigatório)

Investor Sub Type

Enumerador	Descrição
default	Investidor regular, pessoa física ou jurídica
fund_class	Fundo de investimento — dispara enriquecimento automático com dados públicos da CVM
financial_institution	Instituição financeira. Segue as mesmas regras de default
non_resident	Subtipo de classificação. Não define a residência da análise — para isso use resident

Response

Response Body

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