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

Os tipos de investidor são definidos pelo campo person_type: pessoa física (natural_person), pessoa jurídica (legal_person) e por conta e ordem (nominee). O campo investor_sub_type distingue subtipos como fundo de investimento (fund_class), que possuem regras próprias ao longo do fluxo de cadastro.

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.

Essa regra é exclusiva do sandbox. Em produção toda análise passa pelo fluxo real de compliance.

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/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"
        }
    }
}

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 e, quando o investidor é criado pela gestora ou pela consultoria, email e phone
legal_person: name, document_number, person_type
nominee: name, person_type, external_distribution_key

investor_sub_type é opcional. Se omitido, pessoa física fica default e, para pessoa jurídica residente, o subtipo é identificado pelo CNPJ (financial_institution, fund_class ou default). Para um distribuidor, email e phone de pessoa física são opcionais, 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

O campo 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": "969.698.790-03",
    "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": "22.333.444/0001-81"
        }
    ]
}

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 de endereço precisa ter country: "BRA", senão IVR000227. Com resident: false, o country não pode ser BRA, senão IVR000226.

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. Se omitido, é inferido	-	Não
`document_number`	string	CPF (`XXX.XXX.XXX-XX`) ou CNPJ (`XX.XXX.XXX/XXXX-XX`). Não exigido para `nominee`	14 ou 18	Sim*
`external_distribution_key`	string	Chave da distribuição externa. Exigido apenas 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. Obrigatório para `natural_person` criado por gestora ou consultoria	1 - 255	Condicional
`phone`	object	Objeto de Phone. Obrigatório para `natural_person` criado por gestora ou consultoria	-	Condicional
`registry_user`	object	Objeto de Registry User	-	Não
`external_id`	string	Identificador do investidor no seu sistema	1 - 50	Não

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
`nominee`	Por conta e ordem (PCO)

Cadastro nominee (PCO)

O fluxo por conta e ordem precisa ser previamente habilitado e acordado para uso em Produção. Fale com seu contato comercial antes de planejar a integração desse caso.

Investor Sub Type

Enumerador	Descrição
`default`	Investidor regular, pessoa física ou jurídica
`fund_class`	Fundo de investimento. Possui regras próprias de partes relacionadas, documentos e investor owners
`financial_institution`	Instituição financeira. Segue as mesmas regras de `default`
`non_resident`	Recusado com `IVR000255`. A residência é declarada por `resident` e `non_resident_type`

Response

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

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`
400	`IVR000064`	`investor_sub_type` `fund_class` ou `financial_institution` enviado com `natural_person`
400	`IVR000222`	`resident: false` sem `non_resident_type`
400	`IVR000255`	`investor_sub_type: non_resident`
400	`IVR000256` a `IVR000259`	Subtipo declarado não confere com o CNPJ (instituição financeira registrada / classe na CVM)
409	`IVR000007`	Você já cadastrou um investidor com este documento

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

Introdução​

Input / Output​

Request​

Request body​

Investidor não residente​

Tipos de representação​

Body params​

Phone​

Registry User​

Person Type​

Investor Sub Type​

Response​

Erros​