URL
Need help?
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:
Você também pode usar nossa API para realizar pagamentos em:
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:
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:
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 é:
sandbox.belvo.com para api.belvo.com.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/
Uma instituição é uma entidade da qual a Belvo pode acessar informações. Pode ser uma:
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.
O parâmetro scopes contém uma lista de permissões que permitem criar um link para o usuário. Este é um parâmetro obrigatório e deve ser enviado exatamente como mostrado.
Indica por quanto tempo qualquer dado derivado do usuário deve ser armazenado no banco de dados da Belvo para o link (tanto único quanto recorrente). Por exemplo, se você enviar 90d, a Belvo removerá qualquer dado relacionado ao usuário de seu banco de dados após 90 dias. Para mais informações, confira a seção stale_in do nosso artigo sobre controles de retenção de dados.
📘 Informação
A Belvo removerá dados apenas para links que não foram atualizados no período que você fornecer em
stale_in. A Belvo removerá dados apenas para links que não foram atualizados no período que você fornecer emstale_in.
Por padrão, a Belvo armazena dados do usuário por 365 dias, a menos que o link seja deletado.
Uma matriz de recursos para os quais você gostaria de receber uma atualização histórica.
Para instituições bancárias, você pode selecionar os seguintes recursos:
ACCOUNTSOWNERSTRANSACTIONSBILLS (apenas para instituições OFDA do Brasil)INCOMESRECURRING_EXPENSESRISK_INSIGHTSO objeto widget contém informações adicionais sobre como configurar o widget, incluindo personalização de marca, seus termos e condições, URLs de callback e informações sobre o usuário para o qual você deseja extrair dados.
No parâmetro purpose, você pode personalizar a mensagem que é exibida ao seu usuário sobre para qual caso de uso você está solicitando os dados dele. Para mais informações, confira a seção purpose no nosso guia do Hosted Widget (OFDA).
O parâmetro openfinance_feature indica que o usuário final passará pelo fluxo OFDA. Ele deve ser configurado como consent_link_creation.
No objeto callback_urls, você deve adicionar links para onde seu usuário deve ser redirecionado nos seguintes casos:
Para mais informações, confira a seção callback_urls no nosso guia do Hosted Widget (OFDA).
📘 Eventos de Callback
A Belvo também enviará informações adicionais sobre o evento, dependendo do evento. Para mais informações, certifique-se de conferir a seção Handling callback events do guia do Hosted Widget (OFDA).
A URL para a qual o usuário é redirecionado quando conecta sua conta com sucesso.
A URL para a qual o usuário é redirecionado quando sai do processo antes de conectar sua conta.
No objeto branding, você deve adicionar seu:
Você também pode, opcionalmente, adicionar uma cor de fundo personalizada para quando o widget abrir, assim como desativar a mensagem da Belvo sobre quantas contas foram conectadas.
Para mais informações sobre as opções de personalização e branding do widget, confira nosso guia dedicado.
Você pode adicionar o ícone da sua empresa ao widget para alinhá-lo melhor com sua marca. Para mais informações, consulte a seção company_icon do nosso guia de Branding e personalização (OFDA).
Você pode adicionar o logotipo da sua empresa ao widget para alinhá-lo melhor com sua marca. Para mais informações, consulte a seção company_icon do nosso guia de Branding e personalização (OFDA).
Você pode adicionar o nome da sua empresa para ser exibido quando o widget for iniciado pela primeira vez. Por padrão, será exibido apenas "Link your account". Quando você adiciona o nome da sua empresa, a mensagem seguirá o formato "[company_name] uses Belvo to connect your account". Para mais informações, consulte a seção company_name do nosso guia de Branding e personalização (OFDA).
Você pode adicionar um link para sua política de privacidade (ou termos e condições) na tela inicial do widget que, quando clicado, redirecionará seus usuários para a página da web vinculada. Isso ajuda seus usuários a entenderem melhor qual é o seu caso de uso em relação aos dados que você está solicitando. Para mais informações, consulte a seção company_terms_url do nosso guia de Branding e personalização (OFDA).
Você pode adicionar uma cor de sobreposição personalizada para quando o widget carregar em seu aplicativo desktop. Para mais informações, consulte a seção overlay_background_color do nosso guia de Branding e personalização (OFDA).
Você pode optar por ocultar a mensagem "Mais de 5 milhões de usuários já conectaram com segurança suas contas." que aparece quando seu usuário seleciona sua instituição no widget. Para mais informações, consulte a seção social_proof do nosso guia de Branding e personalização (OFDA).
Você pode adicionar opcionalmente as cores da sua marca ao widget usando o parâmetro theme.
Para mais informações sobre onde essas cores aparecerão no widget, consulte a seção dedicada Adicionar cores personalizadas ao widget do nosso guia de Branding.
O objeto consent é exclusivo do widget OFDA e deve ser enviado.
No parâmetro terms_and_conditions_url, você deve fornecer um link para os termos e condições da sua empresa.
O parâmetro permissions contém os recursos que você deseja extrair da Rede de Open Finance do Brasil para o usuário. Este valor deve ser definido como ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"].
No array identification_info, você precisa fornecer as informações de identificação do usuário para o qual deseja recuperar informações. As informações fornecidas aqui devem corresponder às informações que a instituição regulada possui para o usuário (por exemplo, para empresas, o CPF e o nome devem ser de um usuário com acesso à conta empresarial).
Para mais informações, consulte a seção identification_info do nosso guia Hosted Widget (OFDA).
https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/token/
https://sandbox.belvo.com/api/token/
curl -i -X POST \
-u <username>:<password> \
https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/token/ \
-H 'Content-Type: application/json' \
-d '{
"id": "string",
"password": "string",
"scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
"stale_in": "42d",
"fetch_resources": [
"ACCOUNTS",
"TRANSACTIONS",
"OWNERS",
"BILLS"
],
"widget": {
"purpose": "Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito.",
"openfinance_feature": "consent_link_creation",
"callback_urls": {
"success": "your_deeplink_here://success",
"exit": "your_deeplink_here://exit",
"event": "your_deeplink_here://error"
},
"branding": {
"company_icon": "https://mysite.com/icon.svg",
"company_logo": "https://mysite.com/logo.svg",
"company_name": "ACME",
"company_terms_url": "https://belvo.com/terms-service/",
"overlay_background_color": "#F0F2F4",
"social_proof": true
},
"theme": [
{
"css_key": "--color-primary-base",
"value": "#907AD6"
}
],
"consent": {
"terms_and_conditions_url": "https://www.your_terms_and_conditions.com",
"permissions": [
"REGISTER",
"ACCOUNTS",
"CREDIT_CARDS",
"CREDIT_OPERATIONS"
],
"identification_info": [
{
"type": "CPF",
"number": 76109277673,
"name": "Ralph Bragg"
}
]
}
}
}'Operação bem-sucedida
O token de acesso a ser usado para autenticar o widget.
O token de atualização a ser usado para autenticar o widget.
{ "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI3MzYwMTk1LCJpYXQiOjE3MjczNTg5OTUsImp0aSI6ImRhN2Q3OTM1ZDZlZTQ0MTBhYTMwYTc3NWQ1OWMxZWIzIiwidXNlcl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsIm9yZ2FuaXphdGlvbl9uYW1lIjoiRG9taW5payBDaG9sZXdza2kncyB0ZWFtIiwib3JnYW5pemF0aW9uX2lkIjoiNmU5YmU4ODQtNDc4MS00MTQzLWI2NzMtYWNhMDI0NzVlZThjIiwic2NvcGVzIjpbInJlYWRfaW5zdGl0dXRpb25zIiwid3JpdGVfbGlua3MiXSwiZW52aXJvbm1lbnQiOiJzYW5kYm94IiwiYXBpX3VybCI6InNhbmRib3guYmVsdm8uY29tIiwiY3JlZGVudGlhbHNfc3RvcmFnZSI6IjMwZCIsInN0YWxlX2luIjoiMzY1ZCIsImZldGNoX3Jlc291cmNlcyI6WyJPV05FUlMiLCJFTVBMT1lNRU5UUyJdLCJpc3MiOiJzYW5kYm94LmJlbHZvLmNvbSJ9.DaQ8xVTEjA4BD-0SbBCQDylO3NrjhsHiWXTaoPdKWRucS2E0jxNUHC5lwrejrz73-GytgcXTeiI1fhZBYW719A", "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjM0OTQzODk5NSwiaWF0IjoxNzI3MzU4OTk1LCJqdGkiOiI2YmUyMGFmNTcxZDU0NjQzYjA0Y2U3YTVhNjI5ZDRiMSIsInVzZXJfaWQiOiI2ZTliZTg4NC00NzgxLTQxNDMtYjY3My1hY2EwMjQ3NWVlOGMiLCJvcmdhbml6YXRpb25fbmFtZSI6IkRvbWluaWsgQ2hvbGV3c2tpJ3MgdGVhbSIsIm9yZ2FuaXphdGlvbl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsInNjb3BlcyI6WyJyZWFkX2luc3RpdHV0aW9ucyIsIndyaXRlX2xpbmtzIl0sImVudmlyb25tZW50Ijoic2FuZGJveCIsImFwaV91cmwiOiJzYW5kYm94LmJlbHZvLmNvbSIsImNyZWRlbnRpYWxzX3N0b3JhZ2UiOiIzMGQiLCJzdGFsZV9pbiI6IjM2NWQiLCJmZXRjaF9yZXNvdXJjZXMiOlsiT1dORVJTIiwiRU1QTE9ZTUVOVFMiXSwiaXNzIjoic2FuZGJveC5iZWx2by5jb20ifQ.T-tnX2BwAjQI0MaYCO686bZD6H7EMIgi_CbOWtHDexGIiTKLer0d7RJGisXJqM6oA_L4y_A_774LEj8NNb7YXQ" }
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:
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:
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:
No momento, o recurso de empregos está disponível para:
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:
No momento, o recurso de registros de emprego está disponível para:
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.
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.
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.
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_typeno arrayform_fields, você deve enviar esse valor na sua solicitação PATCH.