Documentação da API Belvo (1.222.0)
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:
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
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).
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.
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
paraapi.belvo.com
. - Se você estiver usando webhooks, certifique-se de definir uma URL de Produção para seus webhooks.
Usamos o seguinte código de status HTTP na resposta, dependendo do sucesso ou falha:
Código de Status | Descriçã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. |
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.
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.
Para uma lista completa de erros e como solucioná-los, consulte nosso artigo dedicado Tratamento de Erros.
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).
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.
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.
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.
https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/
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.
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.
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
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.
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)
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)
Current Employments Mexico
O recurso de Empregos Atuais fornece acesso em tempo real ao status de emprego atual de indivíduos no México. Este recurso oferece informações detalhadas sobre se um indivíduo está atualmente empregado ou desempregado, juntamente com seus registros de emprego ativos.
- Status de Emprego em Tempo Real: Obtenha informações atualizadas sobre a situação de emprego atual de um indivíduo
- Atual vs Histórico: Ao contrário dos Registros de Emprego, este recurso foca especificamente no status de emprego atual em vez de dados históricos de emprego
- Detalhes Completos de Emprego: Quando empregado, receba informações detalhadas, incluindo detalhes do empregador, informações salariais e duração do emprego
- Status de Desemprego: Indicação clara quando um indivíduo está atualmente desempregado
Quando um indivíduo está empregado, você receberá:
- Dados de identificação pessoal (nome, data de nascimento, NSS, CURP)
- Status de emprego atual
- Informações do empregador (nome, RFC, ID)
- Local de trabalho (estado)
- Duração do emprego (dias empregados)
- Informações salariais (salário base e mensal)
Requisição
Este recurso está atualmente em desenvolvimento e, como tal, certos nomes de campos ou valores podem mudar.
▶️ Uso
Com o método List Current Employments, você pode:
- Listar empregos atuais relacionados a um
link.id
específico (usando o parâmetro de consultalink
). - Obter os detalhes de um
current-employment.id
específico (usando o parâmetro de consultaid
). - [Não Recomendado] Listar todos os empregos atuais 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 pelas 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, veja nosso artigo Filtrando respostas.
Retorne informações apenas para este recurso id
.
Retorne informações para esses id
s de recurso.
O link.id
pelo qual você deseja filtrar.
ℹ️ Recomendamos fortemente adicionar o filtro link.id
para melhorar seu desempenho.
Retorne resultados apenas para esses link.id
s.
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).
Um número de página dentro do conjunto de resultados paginados.
Retorne itens que foram recuperados da instituição nesta data (YYYY-MM-DD
ou timestamp completo ISO-8601
).
Retorne itens que foram recuperados da instituição após esta data (YYYY-MM-DD
ou timestamp completo ISO-8601
).
Retorne itens que foram recuperados da instituição após ou nesta data (YYYY-MM-DD
ou timestamp completo ISO-8601
).
Retorne itens que foram recuperados da instituição antes desta data (YYYY-MM-DD
ou timestamp completo ISO-8601
).
Retorne itens que foram recuperados da instituição antes ou nesta data (YYYY-MM-DD
ou timestamp completo ISO-8601
).
Retorne itens que foram recuperados da instituição entre duas datas (YYYY-MM-DD
ou timestamp completo ISO-8601
).
Retorne itens que foram atualizados pela última vez no banco de dados da Belvo nesta data (no formato YYYY-MM-DD
).
Retorne itens que foram atualizados pela última vez no banco de dados da Belvo após esta data (no formato YYYY-MM-DD
).
Retorne itens que foram atualizados pela última vez no banco de dados da Belvo após ou nesta data (no formato YYYY-MM-DD
).
Retorne itens que foram atualizados pela última vez no banco de dados da Belvo antes desta data (no formato YYYY-MM-DD
).
Retorne itens que foram atualizados pela última vez no banco de dados da Belvo antes ou na data especificada (no formato YYYY-MM-DD
).
- Mock server
https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/mx/current-employments/
- Ambiente de Testes
https://sandbox.belvo.com/api/mx/current-employments/
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/mx/current-employments/?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&page_size=100&page=1&collected_at=2022-05-01&collected_at__gt=2022-05-05&collected_at__gte=2022-05-04&collected_at__lt=2022-04-01&collected_at__lte=2022-03-30&collected_at__range=2022-05-04&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'
Ok
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
).
A URL para a página anterior de resultados. Se não houver uma página anterior, o valor será null
.
{ "count": 130, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { … } ] }
O link.id
para o qual você deseja recuperar informações.
- Mock server
https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/mx/current-employments/
- Ambiente de Testes
https://sandbox.belvo.com/api/mx/current-employments/
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/mx/current-employments/ \
-H 'Content-Type: application/json' \
-d '{
"link": "c81a1dea-6dd6-4999-8b9f-541ee8197058",
"save_data": true
}'
Ok (quando existente)
Identificador único da Belvo para o item atual.
O link.id
ao qual os dados pertencem.
O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo.
O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.
O mês para o qual o status atual de emprego é reportado, no formato YYYY-MM
. Se o status
for UNEMPLOYED
, este campo é null
.
ID único para o usuário de acordo com a instituição. Para IMSS e ISSSTE México, este é o CURP. Se status
for UNEMPLOYED
, este campo é null
.
Detalhes sobre as informações pessoais do indivíduo.
A data de nascimento do indivíduo, no formato YYYY-MM-DD
.
O status atual de emprego do indivíduo.
Detalhes sobre o emprego atual do indivíduo. Se status
for UNEMPLOYED
, este campo será null
.
[ { "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "created_at": "2022-02-09T08:45:50.406032Z", "collected_at": "2022-02-09T08:45:50.406032Z", "month": "2023-01", "internal_identification": "BLPM230130IONVGR54", "personal_data": { … }, "status": "EMPLOYED", "current_employment_records": [ … ] } ]
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.
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.
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).
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 arrayform_fields
, você deve enviar esse valor na sua solicitação PATCH.
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.