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

Atenção

Os campos obrigatórios mudam de acordo com o person_type:

natural_person: name, document_number, person_type (email e phone recomendados para criação de usuário)
legal_person: name, document_number, person_type, investor_sub_type e registry_user
nominee: name, person_type, external_distribution_key

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.

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
`document_number`	string	CPF (`XXX.XXX.XXX-XX`) ou CNPJ (`XX.XXX.XXX/XXXX-XX`)	14 ou 18	Sim*
`investor_sub_type`	string	Enumerador de Investor Sub Type	-	Não
`external_distribution_key`	string	Identificador externo da distribuição (uso típico para `nominee`)	1 - 100	Não
`email`	string	E-mail do investidor	1 - 255	Não
`phone`	object	Objeto de Phone	-	Não
`investor_owner_type`	string	Tipo de relação de propriedade (utilizado em integrações específicas, ex. fund class)	1 - 255	Não
`registry_user`	object	Objeto de Registry User	-	Não

* document_number não deve ser enviado para person_type: 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`	Pessoa jurídica regular (default quando o campo não é informado)
`fund_class`	Fundo de investimento — dispara enriquecimento automático com dados públicos da CVM

Response

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

Introdução​

Input / Output​

Request​

Request body​

Body params​

Phone​

Registry User​

Person Type​

Investor Sub Type​

Response​