Documentação da API Belvo (1.221.0)

Introdução

Alcance novos públicos e converta mais usuários conectando-se fácil e seguramente aos dados financeiros deles, entendendo seu comportamento e possibilitando pagamentos instantâneos com open finance. Através da nossa API, você pode acessar:

Informações Disponíveis e Métodos de Pagamento

A Belvo é uma API de open banking para a América Latina que permite que empresas acessem informações bancárias e fiscais de maneira segura e ágil.

Através da nossa API, você pode acessar:

  • Informações Bancárias no Brasil
  • Informações de Emprego no Brasil
  • Informações de Emprego no México
  • Informações Fiscais no México
  • Informações Fiscais no Chile

Você também pode usar nossa API para realizar pagamentos em:

  • Brasil
  • México

Dicionários de Dados

Se você deseja a documentação de resposta em formato Excel ou CSV, por favor, faça o download a partir do nosso Repositório Público no GitHub: Belvo Open Finance Data Dictionaries.

Nossos arquivos EXCEL e CSV estão adicionalmente localizados em Espanhol e Português (Brasil).

Ambientes

Atualmente, oferecemos dois ambientes: sandbox e produção.

Sandbox

Disponível para:

  • 🟢 Agregação e Enriquecimento
  • ⚪️ Iniciação de Pagamento

Use nosso ambiente Sandbox para construir sua integração. Oferecemos dados fictícios que imitam casos de uso do mundo real, o que significa que você pode testar todos os endpoints, usar o widget e implementar webhooks - exatamente como faria com dados reais!

Tudo o que você precisa para começar com o ambiente Sandbox é obter suas chaves de API. Recomendamos fortemente que você comece a criar sua integração neste ambiente.

Produção

Disponível para:

  • 🟢 Agregação e Enriquecimento
  • 🟢 Iniciação de Pagamento

Depois de testar sua integração no ambiente Sandbox e estar pronto para entrar em operação, você precisará solicitar acesso ao nosso ambiente de Produção. Após solicitar o acesso, nossa equipe de Vendas entrará em contato para agendar uma reunião apenas para garantir que suas necessidades sejam atendidas, e então você precisará passar por um processo de certificação com um de nossos engenheiros para garantir que sua integração esteja funcionando de forma otimizada. Para se preparar para a reunião de certificação, basta seguir nossa lista de verificação de Integração.

Uma vez que sua integração esteja certificada, tudo o que você precisará fazer é:

  • Solicitar chaves de API de Produção (e alterar suas chaves de API do Sandbox no código para estas novas).
  • Alterar a URL base para a qual você faz solicitações de sandbox.belvo.com para api.belvo.com.
  • Se você estiver usando webhooks, certifique-se de definir uma URL de Produção para seus webhooks.

Códigos de Resposta

Usamos o seguinte código de status HTTP na resposta, dependendo do sucesso ou falha:

Código de StatusDescrição
200✅ Sucesso - O conteúdo está disponível no corpo da resposta.
201✅ Sucesso - O conteúdo foi criado com sucesso na Belvo.
204✅ Sucesso - Nenhum conteúdo para retornar.
400❌ Erro de Solicitação Inválida - A solicitação retornou um erro, detalhe no conteúdo.
401❌ Não Autorizado - As credenciais da Belvo fornecidas não são válidas.
404❌ Não Encontrado - O recurso que você tentou acessar não pode ser encontrado.
405❌ Método Não Permitido - O método HTTP que você está usando não é aceito para este recurso.
408❌ Tempo de Solicitação Esgotado - A solicitação expirou e foi encerrada pelo servidor.
428❌ Token MFA Necessário - O token MFA foi exigido pela instituição para conectar.
500❌ Erro Interno do Servidor - O detalhe do erro está disponível no corpo da resposta.

Tratamento de Erros

Os erros da API Belvo são retornados em formato JSON. Por exemplo, um erro pode ser assim:

[
    {
      "request_id": "a6e1c493d7a29d91aed4338e6fcf077d",
      "message": "Este campo é obrigatório.",
      "code": "required",
      "field": "link"
    }
]

Normalmente, uma resposta de erro terá os seguintes parâmetros:

  • request_id: um ID único para a solicitação, você deve compartilhá-lo com a equipe de suporte da Belvo para investigações.
  • message: descrição legível do erro.
  • code: um código único para o erro. Verifique a tabela abaixo para ver como lidar com cada código de erro.
  • field (opcional): O campo específico no corpo da solicitação que tem um problema.

Identificador de Solicitação

Quando você precisar de ajuda com um erro específico, inclua o identificador de solicitação (request_id) em sua mensagem para a equipe de suporte da Belvo. Isso acelerará as investigações e fará com que você volte a funcionar rapidamente.

Códigos de Erro e Solução de Problemas

Para uma lista completa de erros e como solucioná-los, consulte nosso artigo dedicado Tratamento de Erros.

Política de Repetição

Erros 50x

Implemente uma repetição automática exponencial de até cinco tentativas. Recomendamos usar um intervalo base de três segundos com um fator de dois. Por exemplo, a primeira repetição deve ser após três segundos, a segunda repetição após seis segundos (2 * 3), a terceira repetição após 12 segundos (2 * 6), a quarta repetição após 24 segundos (2 * 12) e a quinta repetição após 48 segundos (2 * 24).

Erros 40x

Você não deve tentar novamente fazer solicitações se receber uma resposta 40x, pois isso é um erro do cliente.

A única exceção é o erro "Muitas Sessões", pois isso significa que seu usuário final está acessando a conta de outro navegador ao mesmo tempo. Nesse caso, implemente a mesma política de repetição que para erros 50x.

Campos Obsoletos

Em nosso esquema, você pode ver que um campo foi marcado como deprecated. Isso significa que este campo não é mais mantido pela equipe da Belvo. Você ainda pode receber dados para este campo dependendo da instituição, no entanto, você não deve confiar neste campo.

OpenAPI: campos obrigatórios e anuláveis

Em nossa especificação de API, você verá que alguns parâmetros de resposta terão uma anotação required. De acordo com a especificação OpenAPI, quando um parâmetro de resposta é marcado como required, isso significa que a chave de resposta deve ser retornada. No entanto, o valor desse parâmetro de resposta pode ser null.

📘 Informação

Em resumo, qualquer parâmetro de resposta marcado como obrigatório será retornado pela nossa API, mas o valor pode ser definido como nulo.

Baixar o arquivo de descrição OpenAPI
BelvoOpenApiSpec.json
BelvoOpenApiSpec.yaml
Visão Geral
URL

https://developers.belvo.com

Need help?

support@belvo.com

Idiomas
Servidores
Mock server

https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/

Ambiente de Testes

https://sandbox.belvo.com/

Institutions

Uma instituição é uma entidade da qual a Belvo pode acessar informações. Pode ser uma:

  • instituição bancária, como o Nubank Brasil.
  • instituição fiscal, como o Servicio de Administración Tributaria (SAT) no México.
  • instituição de emprego, como o Instituto Mexicano del Seguro Social (IMSS) no México ou o Instituto Nacional do Seguro Social (INSS) no Brasil.
Operações

Links

Um Link é um conjunto de credenciais associado ao acesso de um usuário final a uma instituição. Você precisará registrar um Link antes de acessar informações desse usuário final específico, como detalhes de conta ou transações.

Recomendamos usar o Belvo Hosted Widget para gerenciar o processo de conexão.

Operações

Widget Access Token

Operações

Consents

Um consentimento é uma permissão dada pelo usuário final para acessar seus dados financeiros na Rede de Open Finance no Brasil.

Operações

Owners

Um proprietário representa a pessoa que tem acesso a um Link e é o proprietário de todas as contas dentro do Link.

Você pode usar este endpoint para obter informações úteis sobre seu cliente, como:

  • seu nome completo
  • informações de contato principais
  • informações sobre o documento de identidade que usaram ao abrir a conta
Operações

Listar proprietários

Requisição

▶️ Uso

Com o método List Owners, você pode:

  1. Listar proprietários relacionados a um link.id específico (usando o parâmetro de consulta link).
  2. Obter os detalhes de um owners.id específico (usando o parâmetro de consulta id).
  3. [Não Recomendado] Listar todos os proprietários relacionados à sua conta Belvo (sem usar nenhum parâmetro de consulta).

📖 Paginação

Este método retorna uma resposta paginada (padrão: 100 itens por página). Você pode usar o parâmetro de consulta page_size para aumentar o número de itens retornados até um máximo de 1000 itens. Você pode usar o parâmetro de consulta page para navegar pelos resultados. Para mais detalhes sobre como navegar nas respostas paginadas da Belvo, consulte nosso artigo Dicas de Paginação.

🔦 Filtrando Respostas

Consulte a lista de consultas abaixo para ver uma lista de campos pelos quais você pode filtrar suas respostas. Para mais informações sobre como usar filtros, consulte nosso artigo Filtrando respostas.

🚨 Campos Obsoletos

Este recurso pode retornar campos obsoletos. Na documentação de resposta, você pode ver que um campo foi marcado como obsoleto. Isso significa que este campo não é mais mantido pela equipe da Belvo. Você ainda pode receber dados para este campo dependendo da instituição, no entanto, não deve confiar neste campo.

Security
basicAuth
Consulta
linkstring(uuid)

O link.id pelo qual você deseja filtrar.

ℹ️ Recomendamos fortemente adicionar o filtro link.id para melhorar seu desempenho.

Exemplo: link=8848bd0c-9c7e-4f53-a732-ec896b11d4c4
page_sizeinteger(int32)[ 1 .. 1000 ]

Indica quantos resultados retornar por página. Por padrão, retornamos 100 resultados por página.

ℹ️ O número mínimo de resultados retornados por página é 1 e o máximo é 1000. Se você inserir um valor maior que 1000, nossa API usará o valor máximo por padrão (1000).

Padrão 100
Exemplo: page_size=100
pageinteger(int32)>= 1

Um número de página dentro do conjunto de resultados paginados.

Exemplo: page=1
omitstring

Omitir certos campos de serem retornados na resposta. Para mais informações, consulte nosso artigo Filtrando respostas no DevPortal.

fieldsstring

Retorne apenas os campos especificados na resposta. Para mais informações, consulte nosso artigo no DevPortal Filtrando respostas.

link__inArray of strings(uuid)

Retorne resultados apenas para esses link.ids.

Exemplo: link__in=5722d0ba-69d7-42dc-8ff5-33767b83c5d6
idstring(uuid)

Retorne informações apenas para este recurso id.

Exemplo: id=24ccab1d-3a86-4136-a6eb-e04bf52b356f
id__inArray of strings(uuid)

Retorne informações para esses ids de recurso.

Exemplo: id__in=6b3dea0f-be29-49d1-aabe-1a6d588642e6
created_atstring(date)

Retorne itens que foram atualizados pela última vez no banco de dados da Belvo nesta data (no formato YYYY-MM-DD).

Exemplo: created_at=2022-05-05
created_at__gtstring(date)

Retorne itens que foram atualizados pela última vez no banco de dados da Belvo após esta data (no formato YYYY-MM-DD).

Exemplo: created_at__gt=2022-05-05
created_at__gtestring(date)

Retorne itens que foram atualizados pela última vez no banco de dados da Belvo após ou nesta data (no formato YYYY-MM-DD).

Exemplo: created_at__gte=2022-05-04
created_at__ltstring(date)

Retorne itens que foram atualizados pela última vez no banco de dados da Belvo antes desta data (no formato YYYY-MM-DD).

Exemplo: created_at__lt=2022-04-01
created_at__ltestring(date)

Retorne itens que foram atualizados pela última vez no banco de dados da Belvo antes ou na data especificada (no formato YYYY-MM-DD).

Exemplo: created_at__lte=2022-03-30
created_at__rangeArray of strings(date)<= 2 items

Retorne contas que foram atualizadas pela última vez no banco de dados do Belvo entre duas datas (no formato YYYY-MM-DD).

Exemplo: created_at__range=2022-03-03
emailstring(email)

Retorna proprietários cujo endereço de e-mail corresponde à sua consulta.

Exemplo: email=lopes.d@gmail.com
display_name__icontainsstring>= 3 characters

Retorne proprietários cujo nome completo de exibição corresponda parcialmente à sua consulta. Por exemplo, mar retornará resultados para Mark, Maria, Neymar, Remarque, e assim por diante.

Exemplo: display_name__icontains=Daniela
curl -i -X GET \
  -u <username>:<password> \
  'https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/owners/?created_at=2022-05-05&created_at__gt=2022-05-05&created_at__gte=2022-05-04&created_at__lt=2022-04-01&created_at__lte=2022-03-30&created_at__range=2022-03-03&display_name__icontains=Daniela&email=lopes.d%40gmail.com&fields=string&id=24ccab1d-3a86-4136-a6eb-e04bf52b356f&id__in=6b3dea0f-be29-49d1-aabe-1a6d588642e6&link=8848bd0c-9c7e-4f53-a732-ec896b11d4c4&link__in=5722d0ba-69d7-42dc-8ff5-33767b83c5d6&omit=string&page=1&page_size=100'

Respostas

Ok

Corpoapplication/json
countinteger(int32)

O número total de resultados na sua conta Belvo.

Exemplo: 130
nextstring or null(uri)

A URL para a próxima página de resultados. Cada página consiste em até 100 itens. Se não houver resultados suficientes para uma página adicional, o valor será null.

Em nosso exemplo de documentação, usamos {endpoint} como um valor de espaço reservado. Em produção, esse valor será substituído pelo endpoint real que você está usando atualmente (por exemplo, accounts ou owners).

Exemplo: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2"
previousstring or null(uri)

A URL para a página anterior de resultados. Se não houver uma página anterior, o valor será null.

Exemplo: null
resultsArray of Proprietário Individual (OFDA Brasil) (object) or Proprietário de Negócios (OFDA Brasil) (object) or Proprietário Padrão (Multi-Região) (object)

Uma matriz de:

  • objetos Owner Individual (OFDA Brazil)
  • objetos Owner Business (OFDA Brazil)
  • objetos Owner Standard (Multi-Region)

🚧 Um tipo de esquema por resposta

A resposta conterá uma matriz de um dos tipos de esquema descritos acima. Em outras palavras, não haverá uma mistura de tipos de esquema na resposta.

Resposta
application/json

Exemplo de um indivíduo (OFDA Brasil).

{
  "count": 108,
  "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2",
  "previous": null,
  "results": [
    { … }
  ]
}

Recuperar proprietários de um link

Requisição

Recupere informações do proprietário a partir de um link específico.

Este recurso pode retornar campos obsoletos. Por favor, verifique a documentação da resposta para mais informações.

Security
basicAuth
Consulta
omitstring

Omitir certos campos de serem retornados na resposta. Para mais informações, consulte nosso artigo Filtrando respostas no DevPortal.

fieldsstring

Retorne apenas os campos especificados na resposta. Para mais informações, consulte nosso artigo no DevPortal Filtrando respostas.

Corpoapplication/jsonobrigatório
linkstring(uuid)obrigatório

O link.id para o qual você deseja recuperar informações.

Exemplo: "c81a1dea-6dd6-4999-8b9f-541ee8197058"
tokenstring

O token MFA gerado pela instituição, que é necessário para continuar uma sessão.

Exemplo: "1234ab"
save_databoolean

Indica se os dados devem ou não ser persistidos no Belvo. Por padrão, isso é definido como true e retornamos uma resposta 201 Created.

Quando definido como false, os dados não serão persistidos e retornamos uma resposta 200 OK.

Padrão true
Exemplo: true
curl -i -X POST \
  -u <username>:<password> \
  'https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/owners/?fields=string&omit=string' \
  -H 'Content-Type: application/json' \
  -d '{
    "link": "c81a1dea-6dd6-4999-8b9f-541ee8197058",
    "token": "1234ab",
    "save_data": true
  }'

Respostas

Ok (quando save_data=false)

Corpoapplication/jsonArray [
One of:
idstring(uuid)obrigatório

Identificador único da Belvo para o item atual.

Exemplo: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
linkstring or null(uuid)obrigatório

O link.id ao qual os dados pertencem.

Exemplo: "30cb4806-6e00-48a4-91c9-ca55968576c8"
internal_identificationstring or nullobrigatório

O identificador interno da instituição para o proprietário.

Exemplo: "7e5838e4"
collected_atstring(date-time)obrigatório

O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.

Exemplo: "2022-02-09T08:45:50.406032Z"
created_atstring(date-time)obrigatório

O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo.

Exemplo: "2022-02-09T08:45:50.406032Z"
display_namestring<= 128 characters^[\w\W]{0,128}$obrigatório

O nome completo do indivíduo, conforme fornecido pela instituição.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "Jack Oswald White"
social_namestring or null<= 128 characters^[\w\W]{0,128}$obrigatório

O nome social do indivíduo, conforme geralmente aceito pelo país.

Exemplo: "O Piadista"
birth_datestring(date)<= 10 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

A data de nascimento do indivíduo, no formato YYYY-MM-DD.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "1988-07-15"
marital_statusstring or nullobrigatório

O estado civil do indivíduo. Retornamos um dos seguintes valores:

  • SINGLE
  • MARRIED
  • WIDOWED
  • SEPARATED
  • DIVORCED
  • CIVIL_UNION
  • OTHER
Enum"SINGLE""MARRIED""WIDOWED""SEPARATED""DIVORCED""CIVIL_UNION""OTHER"
Exemplo: "SINGLE"
marital_status_additional_infostring or null<= 50 characters^[\w\W]{0,50}$obrigatório

Informações adicionais sobre o estado civil do indivíduo.

Exemplo: "It's complicated"
genderstring or nullobrigatório

O gênero do indivíduo. Retornamos um dos seguintes valores:

  • FEMALE
  • MALE
  • OTHER
Enum"FEMALE""MALE""OTHER"
Exemplo: "FEMALE"
companies_idArray of stringsnon-emptyobrigatório

As instituições responsáveis pela criação e verificação do proprietário.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: ["01773247000103"]
is_local_residentbooleanobrigatório

Boolean para indicar se o indivíduo é residente local do país.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: true
document_idobjectobrigatório

Informações sobre o documento de identificação que o proprietário forneceu ao banco.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

document_typestringobrigatório

O tipo de documento que o proprietário forneceu à instituição para abrir a conta. Tipos comuns de documentos são:

🇧🇷 Brasil

  • CPF (Cadastro de Pessoas Físicas)
  • CNPJ (Cadastro Nacional de Pessoas Jurídicas)

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "CPF"
document_numberstringobrigatório

O número de identificação do documento.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "235578435-S"
additional_documentsArray of objects or nullnon-emptyobrigatório

Informações detalhadas sobre documentos adicionais fornecidos para comprovar a identidade dos indivíduos.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

typestring or nullobrigatório

O tipo de documento de identificação. Retornamos um dos seguintes valores:

  • DRIVERS_LICENSE
  • PASSPORT
  • ID_CARD
  • FISCAL_ID
  • FOREIGNER_REGISTRATION_CARD
  • OTHER
  • null
Enum"DRIVERS_LICENSE""PASSPORT""ID_CARD""FISCAL_ID""FOREIGNER_REGISTRATION_CARD""OTHER"null
Exemplo: "DRIVERS_LICENSE"
type_additional_infostring or null<= 70 characters^[\w\W\s]{0,70}$obrigatório

Informações adicionais sobre o tipo de documento.

Nota: Para documentos de ID Empresarial, este campo deve retornar um valor da rede de open finance do Brasil.

Exemplo: "Learner's licence"
numberstring<= 40 characters^[\w\W\s]{0,40}$obrigatório

O número do documento de identidade.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "DL-7896829-7"
check_digitstring<= 2 characters^[\w\W\s]{0,2}$obrigatório

O dígito verificador do documento de identidade.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "7"
issue_datestring or null(date)<= 10 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

A data em que o documento de identificação foi emitido, no formato YYYY-MM-DD.

Exemplo: "2019-01-01"
expiration_datestring or null(date)<= 10 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

A data de expiração do documento de identidade, no formato YYYY-MM-DD.

Exemplo: "2019-01-01"
country_of_issuancestring or null<= 3 characters^[\w]{3}$obrigatório

O código de país de três letras que emitiu o documento (no formato ISO-3166 Alpha 3).

Este campo deve ser retornado quando o type for PASSPORT.

Exemplo: "CAN"
additional_infostring or null<= 100 characters^[\w\W\s]{0,100}$obrigatório

Informações adicionais sobre o documento de identificação.

Exemplo: "The document has water damage"
nationalitiesArray of objects or nullnon-emptyobrigatório

Informações detalhadas sobre as nacionalidades do indivíduo.

Só é necessário retornar quando is_local_resident estiver definido como false.

infostring or null<= 40 characters^\S[\s\S]*$obrigatório

A nacionalidade do indivíduo.

Exemplo: "CAN"
documentsArray of objects or nullobrigatório
typestring or nullobrigatório

O tipo de documento de identificação. Retornamos um dos seguintes valores:

  • DRIVERS_LICENSE
  • PASSPORT
  • ID_CARD
  • FISCAL_ID
  • FOREIGNER_REGISTRATION_CARD
  • OTHER
  • null
Enum"DRIVERS_LICENSE""PASSPORT""ID_CARD""FISCAL_ID""FOREIGNER_REGISTRATION_CARD""OTHER"null
Exemplo: "DRIVERS_LICENSE"
numberstring<= 40 characters^[\w\W\s]{0,40}$obrigatório

O número do documento de identidade.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "DL-7896829-7"
issue_datestring or null(date)<= 10 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

A data em que o documento de identificação foi emitido, no formato YYYY-MM-DD.

Exemplo: "2019-01-01"
expiration_datestring or null(date)<= 10 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

A data de expiração do documento de identidade, no formato YYYY-MM-DD.

Exemplo: "2019-01-01"
country_of_issuancestring or null<= 3 characters^[\w]{3}$obrigatório

O código de país de três letras que emitiu o documento (no formato ISO-3166 Alpha 3).

Este campo deve ser retornado quando o type for PASSPORT.

Exemplo: "CAN"
additional_infostring or null<= 100 characters^[\w\W\s]{0,100}$obrigatório

Informações adicionais sobre o documento de identificação.

Exemplo: "The document has water damage"
emailstring or null(email)<= 320 charactersobrigatório

O endereço de e-mail registrado do proprietário da conta.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "johndoe@belvo.com"
emailsArray of objects or null>= 0 itemsobrigatório

Lista adicional de e-mails fornecida pelo proprietário.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

is_mainbooleanobrigatório

Boolean para indicar se este é o endereço de e-mail principal do usuário.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: true
emailstring<= 320 characters^[\w\W\s]{0,320}$obrigatório

O endereço de e-mail do usuário.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "homen_morcego@gmail.com"
addressstring or nullobrigatório

O endereço registrado do proprietário da conta.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "Carrer de la Llacuna, 162, 08018 Barcelona"
addressesArray of objects or nullnon-emptyobrigatório

Informações detalhadas sobre os endereços do proprietário.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

is_mainbooleanobrigatório

Boolean para indicar se este é o endereço principal do usuário.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: true
addressstring<= 150 characters^[\w\W\s]{0,150}$obrigatório

O endereço do usuário.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "Av Naburo Ykesaki, 1270"
additional_infostring or null<= 150 characters^[\w\W\s]{0,150}$obrigatório

Informações adicionais sobre o endereço do usuário.

Exemplo: "In between two palm trees"
district_namestring or null<= 50 characters^[\w\W\s]{0,50}$obrigatório

O distrito do endereço.

Exemplo: "CENTRO"
townstring<= 50 characters^[\w\W\s]{0,50}$obrigatório

A cidade do usuário.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "Brasilia"
town_codestring or null<= 7 characters\d{7}$obrigatório

O código de sete dígitos para a cidade, se aplicável.

Para o Brasil, este é o código do município do IBGE.

Exemplo: "3550308"
statestring or null<= 2 characters^[\w\W\s]{0,2}$obrigatório

O estado em que o endereço está localizado.

Exemplo: "SP"
postcodestring<= 8 characters^\d{8}$obrigatório

O código postal do endereço.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "17500001"
country_namestring<= 80 characters^[\w\W\s]{0,80}$obrigatório

O nome do país.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "Brasil"
country_codestring or null<= 3 characters^([A-Z]{3})$obrigatório

O código de país de três letras (conforme ISO-3166 Alpha 3).

Exemplo: "BRA"
latitudestring or null<= 13 characters^-?\d{1,2}\.\d{1,9}$obrigatório

A coordenada de latitude geográfica.

Exemplo: "-23.5475000"
longitudestring or null<= 13 characters^-?\d{1,3}\.\d{1,8}$obrigatório

A coordenada de longitude geográfica.

Exemplo: "-46.6361100"
phone_numberstring or nullobrigatório

O número de telefone registrado do proprietário da conta.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "+52-XXX-XXX-XXXX"
phone_numbersArray of objects or null>= 0 itemsobrigatório

Informações detalhadas sobre os números de telefone do proprietário.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

is_mainbooleanobrigatório

Boolean para indicar se este é o número de telefone principal do usuário.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: true
typestring or nullobrigatório

O tipo de número de telefone. Retornamos um dos seguintes valores:

  • LANDLINE
  • MOBILE
  • OTHER
  • null
Enum"LANDLINE""MOBILE""OTHER"null
Exemplo: "MOBILE"
additional_infostring or null<= 100 characters^[\w\W\s]{0,100}$obrigatório

Informações adicionais sobre o número de telefone.

Exemplo: "This is their work mobile number."
numberstring<= 11 characters^([0-9]{8,11})$obrigatório

O número de telefone (não incluindo o código do país, área ou ramal).

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "29875132"
country_codestring or null<= 4 characters^\d{1,4}$obrigatório

O código de discagem do país. Por exemplo: 351 (sem +).

Exemplo: "351"
area_codestring or null<= 2 characters^\d{1,2}$obrigatório

O código de discagem da área.

Exemplo: "21"
extensionstring or null<= 5 characters^\d{1,5}$obrigatório

O código da extensão.

Exemplo: "932"
filiationsArray of objectsnon-emptyobrigatório

Informações sobre quaisquer relações familiares do indivíduo.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

typestring or nullobrigatório

A relação familiar. Retornamos um dos seguintes valores:

  • MOTHER
  • FATHER
  • null
Enum"MOTHER""FATHER"null
Exemplo: "MOTHER"
civil_namestring<= 70 characters^[\w\W\s]{0,70}$obrigatório

O nome completo da pessoa.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "Bruce Wayne"
social_namestring or null<= 70 characters^[\w\W\s]{0,70}$obrigatório

O nome social da pessoa.

Exemplo: "The Dark Knight"
financial_profileobject or nullobrigatório

Informações sobre o perfil financeiro do indivíduo.

company_idstring or null<= 14 characters^\d{14}$obrigatório

O identificador da empresa onde o indivíduo está empregado.

Exemplo: "50685362000135"
occuptation_codestring or null

A área de emprego do indivíduo. Retornamos um dos seguintes valores:

  • BRAZIL_PUBLIC_OFFICE
  • BRAZIL_OCCUPATION_CODE
  • OTHER
  • null
Enum"BRAZIL_PUBLIC_OFFICE""BRAZIL_OCCUPATION_CODE""OTHER"null
Exemplo: "BRAZIL_OCCUPATION_CODE"
occupation_descriptionstring or null<= 100 characters[\w\W\s]*obrigatório

Informações sobre a ocupação do indivíduo.

Exemplo: "01"
informed_incomeobjectobrigatório

Informações sobre a renda declarada do indivíduo.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

frequencystring or nullobrigatório

Indica com que frequência o indivíduo recebe seu salário. Retornamos um dos seguintes valores:

  • DAILY
  • WEEKLY
  • FORTNIGHTLY
  • MONTHLY
  • BIMONTHLY
  • QUARTERLY
  • BIANNUALLY
  • ANNUALLY
  • OTHERS
Enum"DAILY""WEEKLY""FORTNIGHTLY""MONTHLY""BIMONTHLY""QUARTERLY""BIANNUALLY""ANNUALLY""OTHERS"
Exemplo: "MONTHLY"
amountnumber(float)[ 1 .. 20 ] characters^\d{1,15}\.\d{2,4}$obrigatório

A renda declarada que o indivíduo recebe.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: 45391.89
currencystring<= 3 characters^[A-Z]{3}$obrigatório

O código de moeda de três letras (ISO-4217).

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "BRL"
datestring(date)<= 10 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

Data em que o indivíduo recebeu seu salário pela última vez.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "2020-03-19"
patrimonyobject or nullobrigatório

Informações sobre os ativos relatados do indivíduo (se disponíveis).

amountnumber(float)^\d{1,15}\.\d{2,4}$obrigatório

Os ativos relatados do indivíduo.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil quando o objeto patrimony estiver disponível.

Exemplo: 45391.89
currencystring<= 3 characters^[A-Z]{3}$obrigatório

O código de moeda de três letras (ISO-4217).

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil quando o objeto patrimony estiver disponível.

Exemplo: "BRL"
yearinteger(int32)[ 1700 .. 2090 ]obrigatório

O ano ao qual os ativos reportados se aplicam.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil quando o objeto patrimony estiver disponível.

Exemplo: 2020
financial_relationobject or nullobrigatório

Detalhes sobre qualquer relacionamento adicional que o indivíduo tenha com a instituição (por exemplo, outras contas ou produtos que ele possua com a instituição).

start_datestring(date-time)<= 20 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

O carimbo de data/hora ISO-8601 quando o relacionamento financeiro entre o indivíduo e a instituição começou.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "2021-05-21T08:30:00Z"
product_servicesArray of stringsnon-emptyobrigatório

Uma lista de produtos que o indivíduo possui com a instituição.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: ["CONTA_DEPOSITO_A_VISTA"]
product_services_additional_infostring or null<= 100 characters^[\w\W]*$obrigatório

Informações adicionais sobre os produtos que o indivíduo possui.

Exemplo: "Joint account with Robin"
procuratorsArray of objects or nullobrigatório

Informações sobre quaisquer indivíduos ou empresas que possam agir em nome do proprietário.

typestring or nullobrigatório

O tipo de representante que pode acessar e fazer alterações na conta. Retornamos um dos seguintes valores:

  • LEGAL_REPRESENTATIVE
  • ATTORNEY
  • null
Enum"LEGAL_REPRESENTATIVE""ATTORNEY"null
Exemplo: "LEGAL_REPRESENTATIVE"
civil_namestring<= 70 characters^[\w\W]*$obrigatório

O nome completo dos representantes.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo procurators estiver disponível.

Exemplo: "Alfred Thaddeus Pennyworth"
social_namestring or null<= 70 characters^[\w\W]*$obrigatório

O nome social da pessoa.

Exemplo: "Alfred Pennyworth"
document_numberstring<= 11 characters^\d{11}$obrigatório

O número do documento do representante.

Nota: Para indivíduos, este é o número do CPF do Brasil. Para empresas, este é o número do CNPJ do Brasil.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo procurators estiver disponível.

Exemplo: "73677831148"
productsArray of objects or nullobrigatório

Detalhes sobre quaisquer produtos adicionais que o indivíduo possua com a instituição.

typestring or nullobrigatório

Os produtos adicionais que o indivíduo possui na instituição. Retornamos um dos seguintes valores:

  • SAVINGS_ACCOUNT
  • CHECKING_ACCOUNT
  • null
Enum"SAVINGS_ACCOUNT""CHECKING_ACCOUNT"null
Exemplo: "SAVINGS_ACCOUNT"
subtypestring or nullobrigatório

O subtipo do produto que o indivíduo possui na instituição.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil se o campo products estiver disponível.

Exemplo: "CONJUNTA_SIMPLES"
agencystring or null<= 4 characters^\d{1,4}$obrigatório

O código da agência onde o produto foi aberto.

Exemplo: "6272"
clearing_codestring<= 3 characters^\d{3}$obrigatório

O código de compensação bancária para o produto.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo products estiver disponível.

Exemplo: "001"
numberstring<= 20 characters^\d{8,20}$obrigatório

O número da conta do produto.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo procurators estiver disponível.

Exemplo: "24550245"
check_digitstring<= 2 characters[\w\W\s]*obrigatório

O dígito verificador do número do produto.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo products estiver disponível.

Exemplo: "7"
salary_portability_requestsArray of objects

Detalhes sobre quaisquer solicitações de portabilidade de salário que o indivíduo tenha feito com a instituição.

Uma portabilidade de salário é uma solicitação para transferir o salário do indivíduo da conta bancária de 'folha de pagamento' do empregador para outra conta bancária.

📘

Por favor, note que a conta bancária receptora não pode encerrar uma portabilidade de salário (ou ser informada de que ela foi encerrada). Apenas o banco da folha de pagamento do empregador pode fornecer essa informação. Assim, as portabilidades listadas aqui podem não estar atualizadas.

payroll_accountsArray of objects

Detalhes sobre quaisquer contas bancárias de folha de pagamento associadas ao indivíduo. Ou seja, cada vez que o indivíduo tiver um novo empregador do qual recebe salário, isso deve ser listado aqui.

📘

Empregadores anteriores podem não fechar a conta de folha de pagamento do indivíduo. Assim, as contas de folha de pagamento listadas aqui podem não estar atualizadas.

]
Resposta
application/json

Exemplo de um indivíduo (OFDA Brasil).

[
  {
    "id": "c749315b-eec2-435d-a458-06912878564f",
    "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
    "internal_identification": "7e5838e4",
    "collected_at": "2019-09-27T13:01:41.941Z",
    "created_at": "2022-02-09T08:45:50.406032Z",
    "display_name": "Jack Oswald White",
    "social_name": "O Piadista",
    "birth_date": "1988-07-15",
    "marital_status": "SINGLE",
    "marital_status_additional_info": "It's complicated",
    "gender": "MALE",
    "companies_id": [ … ],
    "is_local_resident": true,
    "document_id": { … },
    "additional_documents": [ … ],
    "nationalities": [ … ],
    "email": "johndoe@belvo.com",
    "emails": [ … ],
    "address": "Carrer de la Llacuna, 162, 08018 Barcelona",
    "addresses": [ … ],
    "phone_number": "+52-XXX-XXX-XXXX",
    "phone_numbers": [ … ],
    "filiations": [ … ],
    "financial_profile": { … },
    "financial_relation": { … }
  }
]

Concluir uma solicitação do proprietário

Requisição

Usado para retomar uma sessão de recuperação de Proprietário que foi pausada porque um token MFA foi exigido pela instituição.

Este recurso pode retornar campos obsoletos. Por favor, verifique a documentação da resposta para mais informações.

Security
basicAuth
Consulta
omitstring

Omitir certos campos de serem retornados na resposta. Para mais informações, consulte nosso artigo Filtrando respostas no DevPortal.

fieldsstring

Retorne apenas os campos especificados na resposta. Para mais informações, consulte nosso artigo no DevPortal Filtrando respostas.

Corpoapplication/jsonobrigatório
sessionstring[a-f0-9]{32}obrigatório

A sessão que você deseja retomar. Você precisa usar o valor session que é fornecido na resposta 428 Token Required que você recebe após fazer sua solicitação POST.

Exemplo: "6e7b283c6efa449c9c028a16b5c249fa"
tokenstring

O token MFA gerado pela instituição, que é necessário para continuar uma sessão.

Exemplo: "1234ab"
linkstring(uuid)obrigatório

O link.id que você deseja retomar. Deve ser o mesmo link.id que você recebe na resposta 428 Token Required que contém o ID da session.

Exemplo: "683005d6-f45c-4adb-b289-f1a12f50f80c"
save_databoolean

Indica se os dados devem ou não ser persistidos no Belvo. Por padrão, isso é definido como true e retornamos uma resposta 201 Created.

Quando definido como false, os dados não serão persistidos e retornamos uma resposta 200 OK.

Padrão true
Exemplo: true
curl -i -X PATCH \
  -u <username>:<password> \
  'https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/owners/?fields=string&omit=string' \
  -H 'Content-Type: application/json' \
  -d '{
    "session": "6e7b283c6efa449c9c028a16b5c249fa",
    "token": "1234ab",
    "link": "683005d6-f45c-4adb-b289-f1a12f50f80c",
    "save_data": true
  }'

Respostas

Ok (quando save_data=false)

Corpoapplication/jsonArray [
One of:
idstring(uuid)obrigatório

Identificador único da Belvo para o item atual.

Exemplo: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
linkstring or null(uuid)obrigatório

O link.id ao qual os dados pertencem.

Exemplo: "30cb4806-6e00-48a4-91c9-ca55968576c8"
internal_identificationstring or nullobrigatório

O identificador interno da instituição para o proprietário.

Exemplo: "7e5838e4"
collected_atstring(date-time)obrigatório

O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.

Exemplo: "2022-02-09T08:45:50.406032Z"
created_atstring(date-time)obrigatório

O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo.

Exemplo: "2022-02-09T08:45:50.406032Z"
display_namestring<= 128 characters^[\w\W]{0,128}$obrigatório

O nome completo do indivíduo, conforme fornecido pela instituição.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "Jack Oswald White"
social_namestring or null<= 128 characters^[\w\W]{0,128}$obrigatório

O nome social do indivíduo, conforme geralmente aceito pelo país.

Exemplo: "O Piadista"
birth_datestring(date)<= 10 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

A data de nascimento do indivíduo, no formato YYYY-MM-DD.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "1988-07-15"
marital_statusstring or nullobrigatório

O estado civil do indivíduo. Retornamos um dos seguintes valores:

  • SINGLE
  • MARRIED
  • WIDOWED
  • SEPARATED
  • DIVORCED
  • CIVIL_UNION
  • OTHER
Enum"SINGLE""MARRIED""WIDOWED""SEPARATED""DIVORCED""CIVIL_UNION""OTHER"
Exemplo: "SINGLE"
marital_status_additional_infostring or null<= 50 characters^[\w\W]{0,50}$obrigatório

Informações adicionais sobre o estado civil do indivíduo.

Exemplo: "It's complicated"
genderstring or nullobrigatório

O gênero do indivíduo. Retornamos um dos seguintes valores:

  • FEMALE
  • MALE
  • OTHER
Enum"FEMALE""MALE""OTHER"
Exemplo: "FEMALE"
companies_idArray of stringsnon-emptyobrigatório

As instituições responsáveis pela criação e verificação do proprietário.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: ["01773247000103"]
is_local_residentbooleanobrigatório

Boolean para indicar se o indivíduo é residente local do país.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: true
document_idobjectobrigatório

Informações sobre o documento de identificação que o proprietário forneceu ao banco.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

document_typestringobrigatório

O tipo de documento que o proprietário forneceu à instituição para abrir a conta. Tipos comuns de documentos são:

🇧🇷 Brasil

  • CPF (Cadastro de Pessoas Físicas)
  • CNPJ (Cadastro Nacional de Pessoas Jurídicas)

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "CPF"
document_numberstringobrigatório

O número de identificação do documento.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "235578435-S"
additional_documentsArray of objects or nullnon-emptyobrigatório

Informações detalhadas sobre documentos adicionais fornecidos para comprovar a identidade dos indivíduos.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

typestring or nullobrigatório

O tipo de documento de identificação. Retornamos um dos seguintes valores:

  • DRIVERS_LICENSE
  • PASSPORT
  • ID_CARD
  • FISCAL_ID
  • FOREIGNER_REGISTRATION_CARD
  • OTHER
  • null
Enum"DRIVERS_LICENSE""PASSPORT""ID_CARD""FISCAL_ID""FOREIGNER_REGISTRATION_CARD""OTHER"null
Exemplo: "DRIVERS_LICENSE"
type_additional_infostring or null<= 70 characters^[\w\W\s]{0,70}$obrigatório

Informações adicionais sobre o tipo de documento.

Nota: Para documentos de ID Empresarial, este campo deve retornar um valor da rede de open finance do Brasil.

Exemplo: "Learner's licence"
numberstring<= 40 characters^[\w\W\s]{0,40}$obrigatório

O número do documento de identidade.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "DL-7896829-7"
check_digitstring<= 2 characters^[\w\W\s]{0,2}$obrigatório

O dígito verificador do documento de identidade.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "7"
issue_datestring or null(date)<= 10 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

A data em que o documento de identificação foi emitido, no formato YYYY-MM-DD.

Exemplo: "2019-01-01"
expiration_datestring or null(date)<= 10 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

A data de expiração do documento de identidade, no formato YYYY-MM-DD.

Exemplo: "2019-01-01"
country_of_issuancestring or null<= 3 characters^[\w]{3}$obrigatório

O código de país de três letras que emitiu o documento (no formato ISO-3166 Alpha 3).

Este campo deve ser retornado quando o type for PASSPORT.

Exemplo: "CAN"
additional_infostring or null<= 100 characters^[\w\W\s]{0,100}$obrigatório

Informações adicionais sobre o documento de identificação.

Exemplo: "The document has water damage"
nationalitiesArray of objects or nullnon-emptyobrigatório

Informações detalhadas sobre as nacionalidades do indivíduo.

Só é necessário retornar quando is_local_resident estiver definido como false.

infostring or null<= 40 characters^\S[\s\S]*$obrigatório

A nacionalidade do indivíduo.

Exemplo: "CAN"
documentsArray of objects or nullobrigatório
typestring or nullobrigatório

O tipo de documento de identificação. Retornamos um dos seguintes valores:

  • DRIVERS_LICENSE
  • PASSPORT
  • ID_CARD
  • FISCAL_ID
  • FOREIGNER_REGISTRATION_CARD
  • OTHER
  • null
Enum"DRIVERS_LICENSE""PASSPORT""ID_CARD""FISCAL_ID""FOREIGNER_REGISTRATION_CARD""OTHER"null
Exemplo: "DRIVERS_LICENSE"
numberstring<= 40 characters^[\w\W\s]{0,40}$obrigatório

O número do documento de identidade.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "DL-7896829-7"
issue_datestring or null(date)<= 10 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

A data em que o documento de identificação foi emitido, no formato YYYY-MM-DD.

Exemplo: "2019-01-01"
expiration_datestring or null(date)<= 10 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

A data de expiração do documento de identidade, no formato YYYY-MM-DD.

Exemplo: "2019-01-01"
country_of_issuancestring or null<= 3 characters^[\w]{3}$obrigatório

O código de país de três letras que emitiu o documento (no formato ISO-3166 Alpha 3).

Este campo deve ser retornado quando o type for PASSPORT.

Exemplo: "CAN"
additional_infostring or null<= 100 characters^[\w\W\s]{0,100}$obrigatório

Informações adicionais sobre o documento de identificação.

Exemplo: "The document has water damage"
emailstring or null(email)<= 320 charactersobrigatório

O endereço de e-mail registrado do proprietário da conta.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "johndoe@belvo.com"
emailsArray of objects or null>= 0 itemsobrigatório

Lista adicional de e-mails fornecida pelo proprietário.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

is_mainbooleanobrigatório

Boolean para indicar se este é o endereço de e-mail principal do usuário.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: true
emailstring<= 320 characters^[\w\W\s]{0,320}$obrigatório

O endereço de e-mail do usuário.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "homen_morcego@gmail.com"
addressstring or nullobrigatório

O endereço registrado do proprietário da conta.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "Carrer de la Llacuna, 162, 08018 Barcelona"
addressesArray of objects or nullnon-emptyobrigatório

Informações detalhadas sobre os endereços do proprietário.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

is_mainbooleanobrigatório

Boolean para indicar se este é o endereço principal do usuário.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: true
addressstring<= 150 characters^[\w\W\s]{0,150}$obrigatório

O endereço do usuário.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "Av Naburo Ykesaki, 1270"
additional_infostring or null<= 150 characters^[\w\W\s]{0,150}$obrigatório

Informações adicionais sobre o endereço do usuário.

Exemplo: "In between two palm trees"
district_namestring or null<= 50 characters^[\w\W\s]{0,50}$obrigatório

O distrito do endereço.

Exemplo: "CENTRO"
townstring<= 50 characters^[\w\W\s]{0,50}$obrigatório

A cidade do usuário.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "Brasilia"
town_codestring or null<= 7 characters\d{7}$obrigatório

O código de sete dígitos para a cidade, se aplicável.

Para o Brasil, este é o código do município do IBGE.

Exemplo: "3550308"
statestring or null<= 2 characters^[\w\W\s]{0,2}$obrigatório

O estado em que o endereço está localizado.

Exemplo: "SP"
postcodestring<= 8 characters^\d{8}$obrigatório

O código postal do endereço.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "17500001"
country_namestring<= 80 characters^[\w\W\s]{0,80}$obrigatório

O nome do país.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "Brasil"
country_codestring or null<= 3 characters^([A-Z]{3})$obrigatório

O código de país de três letras (conforme ISO-3166 Alpha 3).

Exemplo: "BRA"
latitudestring or null<= 13 characters^-?\d{1,2}\.\d{1,9}$obrigatório

A coordenada de latitude geográfica.

Exemplo: "-23.5475000"
longitudestring or null<= 13 characters^-?\d{1,3}\.\d{1,8}$obrigatório

A coordenada de longitude geográfica.

Exemplo: "-46.6361100"
phone_numberstring or nullobrigatório

O número de telefone registrado do proprietário da conta.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "+52-XXX-XXX-XXXX"
phone_numbersArray of objects or null>= 0 itemsobrigatório

Informações detalhadas sobre os números de telefone do proprietário.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

is_mainbooleanobrigatório

Boolean para indicar se este é o número de telefone principal do usuário.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: true
typestring or nullobrigatório

O tipo de número de telefone. Retornamos um dos seguintes valores:

  • LANDLINE
  • MOBILE
  • OTHER
  • null
Enum"LANDLINE""MOBILE""OTHER"null
Exemplo: "MOBILE"
additional_infostring or null<= 100 characters^[\w\W\s]{0,100}$obrigatório

Informações adicionais sobre o número de telefone.

Exemplo: "This is their work mobile number."
numberstring<= 11 characters^([0-9]{8,11})$obrigatório

O número de telefone (não incluindo o código do país, área ou ramal).

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "29875132"
country_codestring or null<= 4 characters^\d{1,4}$obrigatório

O código de discagem do país. Por exemplo: 351 (sem +).

Exemplo: "351"
area_codestring or null<= 2 characters^\d{1,2}$obrigatório

O código de discagem da área.

Exemplo: "21"
extensionstring or null<= 5 characters^\d{1,5}$obrigatório

O código da extensão.

Exemplo: "932"
filiationsArray of objectsnon-emptyobrigatório

Informações sobre quaisquer relações familiares do indivíduo.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

typestring or nullobrigatório

A relação familiar. Retornamos um dos seguintes valores:

  • MOTHER
  • FATHER
  • null
Enum"MOTHER""FATHER"null
Exemplo: "MOTHER"
civil_namestring<= 70 characters^[\w\W\s]{0,70}$obrigatório

O nome completo da pessoa.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "Bruce Wayne"
social_namestring or null<= 70 characters^[\w\W\s]{0,70}$obrigatório

O nome social da pessoa.

Exemplo: "The Dark Knight"
financial_profileobject or nullobrigatório

Informações sobre o perfil financeiro do indivíduo.

company_idstring or null<= 14 characters^\d{14}$obrigatório

O identificador da empresa onde o indivíduo está empregado.

Exemplo: "50685362000135"
occuptation_codestring or null

A área de emprego do indivíduo. Retornamos um dos seguintes valores:

  • BRAZIL_PUBLIC_OFFICE
  • BRAZIL_OCCUPATION_CODE
  • OTHER
  • null
Enum"BRAZIL_PUBLIC_OFFICE""BRAZIL_OCCUPATION_CODE""OTHER"null
Exemplo: "BRAZIL_OCCUPATION_CODE"
occupation_descriptionstring or null<= 100 characters[\w\W\s]*obrigatório

Informações sobre a ocupação do indivíduo.

Exemplo: "01"
informed_incomeobjectobrigatório

Informações sobre a renda declarada do indivíduo.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

frequencystring or nullobrigatório

Indica com que frequência o indivíduo recebe seu salário. Retornamos um dos seguintes valores:

  • DAILY
  • WEEKLY
  • FORTNIGHTLY
  • MONTHLY
  • BIMONTHLY
  • QUARTERLY
  • BIANNUALLY
  • ANNUALLY
  • OTHERS
Enum"DAILY""WEEKLY""FORTNIGHTLY""MONTHLY""BIMONTHLY""QUARTERLY""BIANNUALLY""ANNUALLY""OTHERS"
Exemplo: "MONTHLY"
amountnumber(float)[ 1 .. 20 ] characters^\d{1,15}\.\d{2,4}$obrigatório

A renda declarada que o indivíduo recebe.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: 45391.89
currencystring<= 3 characters^[A-Z]{3}$obrigatório

O código de moeda de três letras (ISO-4217).

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "BRL"
datestring(date)<= 10 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

Data em que o indivíduo recebeu seu salário pela última vez.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "2020-03-19"
patrimonyobject or nullobrigatório

Informações sobre os ativos relatados do indivíduo (se disponíveis).

amountnumber(float)^\d{1,15}\.\d{2,4}$obrigatório

Os ativos relatados do indivíduo.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil quando o objeto patrimony estiver disponível.

Exemplo: 45391.89
currencystring<= 3 characters^[A-Z]{3}$obrigatório

O código de moeda de três letras (ISO-4217).

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil quando o objeto patrimony estiver disponível.

Exemplo: "BRL"
yearinteger(int32)[ 1700 .. 2090 ]obrigatório

O ano ao qual os ativos reportados se aplicam.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil quando o objeto patrimony estiver disponível.

Exemplo: 2020
financial_relationobject or nullobrigatório

Detalhes sobre qualquer relacionamento adicional que o indivíduo tenha com a instituição (por exemplo, outras contas ou produtos que ele possua com a instituição).

start_datestring(date-time)<= 20 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

O carimbo de data/hora ISO-8601 quando o relacionamento financeiro entre o indivíduo e a instituição começou.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: "2021-05-21T08:30:00Z"
product_servicesArray of stringsnon-emptyobrigatório

Uma lista de produtos que o indivíduo possui com a instituição.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.

Exemplo: ["CONTA_DEPOSITO_A_VISTA"]
product_services_additional_infostring or null<= 100 characters^[\w\W]*$obrigatório

Informações adicionais sobre os produtos que o indivíduo possui.

Exemplo: "Joint account with Robin"
procuratorsArray of objects or nullobrigatório

Informações sobre quaisquer indivíduos ou empresas que possam agir em nome do proprietário.

typestring or nullobrigatório

O tipo de representante que pode acessar e fazer alterações na conta. Retornamos um dos seguintes valores:

  • LEGAL_REPRESENTATIVE
  • ATTORNEY
  • null
Enum"LEGAL_REPRESENTATIVE""ATTORNEY"null
Exemplo: "LEGAL_REPRESENTATIVE"
civil_namestring<= 70 characters^[\w\W]*$obrigatório

O nome completo dos representantes.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo procurators estiver disponível.

Exemplo: "Alfred Thaddeus Pennyworth"
social_namestring or null<= 70 characters^[\w\W]*$obrigatório

O nome social da pessoa.

Exemplo: "Alfred Pennyworth"
document_numberstring<= 11 characters^\d{11}$obrigatório

O número do documento do representante.

Nota: Para indivíduos, este é o número do CPF do Brasil. Para empresas, este é o número do CNPJ do Brasil.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo procurators estiver disponível.

Exemplo: "73677831148"
productsArray of objects or nullobrigatório

Detalhes sobre quaisquer produtos adicionais que o indivíduo possua com a instituição.

typestring or nullobrigatório

Os produtos adicionais que o indivíduo possui na instituição. Retornamos um dos seguintes valores:

  • SAVINGS_ACCOUNT
  • CHECKING_ACCOUNT
  • null
Enum"SAVINGS_ACCOUNT""CHECKING_ACCOUNT"null
Exemplo: "SAVINGS_ACCOUNT"
subtypestring or nullobrigatório

O subtipo do produto que o indivíduo possui na instituição.

Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil se o campo products estiver disponível.

Exemplo: "CONJUNTA_SIMPLES"
agencystring or null<= 4 characters^\d{1,4}$obrigatório

O código da agência onde o produto foi aberto.

Exemplo: "6272"
clearing_codestring<= 3 characters^\d{3}$obrigatório

O código de compensação bancária para o produto.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo products estiver disponível.

Exemplo: "001"
numberstring<= 20 characters^\d{8,20}$obrigatório

O número da conta do produto.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo procurators estiver disponível.

Exemplo: "24550245"
check_digitstring<= 2 characters[\w\W\s]*obrigatório

O dígito verificador do número do produto.

Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo products estiver disponível.

Exemplo: "7"
salary_portability_requestsArray of objects

Detalhes sobre quaisquer solicitações de portabilidade de salário que o indivíduo tenha feito com a instituição.

Uma portabilidade de salário é uma solicitação para transferir o salário do indivíduo da conta bancária de 'folha de pagamento' do empregador para outra conta bancária.

📘

Por favor, note que a conta bancária receptora não pode encerrar uma portabilidade de salário (ou ser informada de que ela foi encerrada). Apenas o banco da folha de pagamento do empregador pode fornecer essa informação. Assim, as portabilidades listadas aqui podem não estar atualizadas.

payroll_accountsArray of objects

Detalhes sobre quaisquer contas bancárias de folha de pagamento associadas ao indivíduo. Ou seja, cada vez que o indivíduo tiver um novo empregador do qual recebe salário, isso deve ser listado aqui.

📘

Empregadores anteriores podem não fechar a conta de folha de pagamento do indivíduo. Assim, as contas de folha de pagamento listadas aqui podem não estar atualizadas.

]
Resposta
application/json

Exemplo de um indivíduo (OFDA Brasil).

[
  {
    "id": "c749315b-eec2-435d-a458-06912878564f",
    "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
    "internal_identification": "7e5838e4",
    "collected_at": "2019-09-27T13:01:41.941Z",
    "created_at": "2022-02-09T08:45:50.406032Z",
    "display_name": "Jack Oswald White",
    "social_name": "O Piadista",
    "birth_date": "1988-07-15",
    "marital_status": "SINGLE",
    "marital_status_additional_info": "It's complicated",
    "gender": "MALE",
    "companies_id": [ … ],
    "is_local_resident": true,
    "document_id": { … },
    "additional_documents": [ … ],
    "nationalities": [ … ],
    "email": "johndoe@belvo.com",
    "emails": [ … ],
    "address": "Carrer de la Llacuna, 162, 08018 Barcelona",
    "addresses": [ … ],
    "phone_number": "+52-XXX-XXX-XXXX",
    "phone_numbers": [ … ],
    "filiations": [ … ],
    "financial_profile": { … },
    "financial_relation": { … }
  }
]

Accounts

Uma conta é a representação de uma conta bancária dentro de uma instituição financeira. Um usuário pode ter uma ou mais contas em uma instituição.

Por exemplo, um usuário (ou link) pode ter uma conta corrente, vários cartões de crédito e uma conta de empréstimo.

Consultar as informações da conta de um usuário é útil, pois você pode obter informações sobre:

  • quais tipos de contas o usuário possui.
  • o saldo de cada conta (poupança, corrente, cartão de crédito, empréstimo, etc.).
  • informações detalhadas sobre os gastos com cartão de crédito.
  • a situação atual de quaisquer empréstimos que possam ter.
Operações

Balances

Um saldo é a quantidade de dinheiro disponível em uma determinada conta bancária (corrente ou poupança) em um determinado momento.

Operações

Transactions

Uma transação contém as informações detalhadas de cada movimento dentro de uma conta. Por exemplo, uma compra em uma loja ou em um restaurante.

Operações

Bills

Uma bill refere-se à fatura do cartão de crédito que um usuário recebe para uma determinada conta.

Operações

Investments Brazil

Operações

Investment Transactions Brazil

Operações

Employments Brazil

Nosso recurso de empregos para o Brasil permite que você obtenha uma visão abrangente do histórico de emprego atual e das informações salariais do seu usuário.

Para cada usuário, nós retornamos:

  • histórico de trabalho (incluindo ocupações e dados do empregador)
  • informações salariais históricas e atuais (por empregador)

No momento, o recurso de empregos está disponível para:

  • 🇧🇷 Brasil (INSS)
Operações

Employment Records Mexico

Nosso recurso de registros de emprego para o México permite que você obtenha uma visão abrangente das contribuições atuais para a seguridade social e do histórico de emprego do seu usuário.

Com o recurso de registros de emprego da Belvo para o México, você pode acessar informações sobre as contribuições atuais para a seguridade social e o histórico de emprego do seu usuário. Para cada usuário, retornamos:

  • dados pessoais
  • histórico de trabalho
  • salário base diário histórico e atual
  • e mais!

No momento, o recurso de registros de emprego está disponível para:

  • 🇲🇽 México (IMSS)
  • 🇲🇽 México (ISSSTE)
Operações

Invoices

Operações

Tax compliance status

Operações

Tax returns

Operações

Tax retentions

Operações

Tax status

Operações

Financial Statements

Operações

Invoices Chile

Operações

Tax Status Chile

Operações

Debt Reports Chile

Operações

Incomes

Use o endpoint Incomes para obter insights sobre as fontes de renda de uma conta nos últimos 365 dias. O endpoint é particularmente útil quando você deseja verificar a renda de uma pessoa.

📘 Info

O recurso incomes está disponível apenas para contas Corrente e Poupança associadas a links bancários.

Operações

Recurring Expenses

A API de Despesas Recorrentes da Belvo permite que você identifique os pagamentos regulares de um usuário para serviços de assinatura, como Netflix ou assinaturas de academia, bem como pagamentos de serviços públicos, como contas de eletricidade ou telefone. Nós retornamos informações de até 365 dias.

📘 Informação

O recurso de despesas recorrentes está disponível apenas para contas Corrente, Poupança e de Cartão de Crédito associadas a links bancários.

Operações

Risk Insights

Operações

Employment Metrics

Operações

Payment Institutions (Brazil)

Uma instituição de pagamento é uma entidade da qual a Belvo pode acessar informações. Você pode ver uma lista completa de instituições disponíveis para pagamentos fazendo uma solicitação de List para este endpoint.

Operações

Customers (Brazil)

Um customer é o pagador que vai transferir fundos para sua conta bancária. Você precisa criar um customer para receber pagamentos de entrada na conta bancária da sua organização.

Operações

Bank Accounts (Brazil)

Para receber pagamentos de entrada na conta bancária da sua organização, você deve registrar as contas bancárias (individuais e empresariais) usando a Payments API da Belvo.

  • Contas bancárias individuais devem ser criadas para cada pagador (seu cliente).
  • Contas bancárias empresariais precisam ser criadas para o beneficiário do pagamento (sua organização).
Operações

Payment Links (Brazil)

Este é um link de pagamento.

Operações

Payment Intents (Brazil)

Um payment intent é um ponto único de acesso para criar pagamentos usando qualquer método de pagamento oferecido pela Belvo.

Um payment intent captura todas as informações de pagamento (como o valor a ser cobrado, a descrição do pagamento, o provedor, etc.) e guia seus clientes através do fluxo de pagamento.

Nota: Para instituições que exigem o username_type no array form_fields, você deve enviar esse valor na sua solicitação PATCH.

Operações

Payment Authorizations (Brazil)

Uma Autorização de Pagamento é o consentimento que seu usuário dá para que você debite dinheiro de suas contas. Você precisa realizar uma Autorização de Pagamento por ‘contrato’ (por exemplo, se sua empresa fornece tanto eletricidade quanto água, mas elas são cobradas separadamente, então você criará duas Autorizações de Pagamento separadas).

Assim que o usuário confirmar a autorização, você precisará escutar um webhook PAYMENT_AUTHORIZATION com o status definido como AUTHORIZED. Assim que você receber esse webhook, o processo de autorização estará completo, e você poderá cobrar seu usuário.

O que é uma cobrança?

Uma cobrança representa o pagamento individual (débito) que seu cliente fará.

Cabeçalho de Versão

O recurso de Autorização de Pagamento requer que você envie o cabeçalho X-Belvo-API-Resource-Version configurado para Payments-BR.V2.

Operações

Biometric Pix Widget Access Token (Brazil)

Use as solicitações de Token do Biometric Pix Widget para criar um token de acesso para Pagamentos Biométricos.

Operações

Enrollments (Brazil)

Operações

Payment Transactions (Brazil)

Cada vez que você recebe um pagamento de entrada de um cliente, uma transação é criada no banco de dados da Belvo.

Você pode usar o recurso de Transações de Pagamento para obter informações úteis sobre uma transação, bem como a cobrança específica associada a ela.

Operações
Copyright © 2020-2025 Belvo. All rights reserved