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.
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:
Omitir certos campos de serem retornados na resposta. Para mais informações, consulte nosso artigo Filtrando respostas no DevPortal.
Retorne apenas os campos especificados na resposta. Para mais informações, consulte nosso artigo no DevPortal Filtrando respostas.
https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/accounts/{id}/
https://sandbox.belvo.com/api/accounts/{id}/
curl -i -X GET \
-u <username>:<password> \
'https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/accounts/{id}/?fields=string&omit=string'Ok
Identificador único da Belvo para o item atual.
O link.id ao qual os dados pertencem.
Detalhes sobre a instituição.
O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.
O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo.
O timestamp ISO-8601 do acesso mais recente e bem-sucedido da Belvo à instituição para o link fornecido.
O tipo de conta.
Retornamos um dos seguintes valores do enum:
ADVANCE_DEPOSIT_ACCOUNTCHECKING_ACCOUNTCREDIT_CARDFINANCING_ACCOUNTINVESTMENT_ACCOUNTINVOICE_FINANCING_ACCOUNTLOAN_ACCOUNTPENSION_FUND_ACCOUNTSAVINGS_ACCOUNTUNCATEGORIZEDIndica se esta conta é um ASSET ou um LIABILITY. Você pode considerar o saldo de um ASSET como positivo, enquanto o saldo de um LIABILITY como negativo.
O tipo de conta, conforme designado pela instituição.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.
O subtipo de conta, conforme designado pela instituição.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.
O nome da conta, conforme fornecido pela instituição.
O número da conta, conforme designado pela instituição.
O código da agência onde o produto foi aberto.
O dígito verificador do número do produto, se aplicável.
Detalhes sobre os saldos atual e disponível para a conta.
O saldo atual é calculado de maneira diferente de acordo com o tipo de conta.
O saldo da conta do usuário no timestamp collected_at.
O valor que o usuário gastou no período de faturamento atual do cartão (consulte credit_data.cutting_date para informações sobre quando o período de faturamento atual termina).
O valor restante a pagar no empréstimo do usuário.
O saldo que o titular da conta pode usar.
O saldo disponível pode ser diferente do saldo current devido a transações pendentes.
O valor de crédito que o usuário ainda tem disponível para o período atual. O valor é calculado como credit_data.credit_limit menos balance.current.
O valor presente necessário para quitar o empréstimo, conforme fornecido pela instituição.
Nota: Se a instituição não fornecer esse valor, retornamos null.
O valor que está atualmente bloqueado devido a transações pendentes.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo
balancesestiver disponível.
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 se o campo
balancesestiver disponível.
O nome público para o tipo de identificação. Para contas de poupança e corrente brasileiras 🇧🇷, este campo será AGENCY/ACCOUNT.
O valor para o public_identification_name.
Para contas de poupança e corrente 🇧🇷 OFDA brasileiras, este campo será o número da agência e da conta bancária, separados por uma barra. Por exemplo: 0444/45722-0.
Para contas de cartão de crédito 🇧🇷 OFDA brasileiras, retornaremos uma string de números de cartão de crédito concatenados associados à conta. Por exemplo: "8763,9076,5522"
A identificação interna da instituição para a conta.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo
balancesestiver disponível.
Detalhes sobre os cartões de crédito associados a esta conta.
O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.
O limite de crédito superior do cartão.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.
A data de vencimento da fatura do cartão de crédito.
O valor mínimo que o proprietário da conta precisa pagar no período de crédito atual.
A rede de crédito à qual o cartão está associado. Retornamos um dos seguintes valores:
VISAMASTERCARDAMERICAN_EXPRESSDINERS_CLUBHIPERCARDBANDEIRA_PROPRIACHEQUE_ELETRONICOELOOTHERNão anulável: Um valor deve ser retornado pela rede de open finance do Brasil.
Informações adicionais sobre a rede de cartão de crédito.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
As opções de empréstimo associadas a esta conta.
O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.
O número de contrato padronizado específico do país.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.
O valor total inicial do empréstimo quando o contrato foi assinado, calculado pela instituição. Este valor inclui o principal + juros + impostos + taxas.
O custo efetivo total inicial do empréstimo.
O tipo do empréstimo, de acordo com a instituição.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.
O valor restante a pagar no total, incluindo juros.
Detalhamento dos juros aplicados ao empréstimo. Com o OF Brasil, recomendamos fortemente o uso das informações em interest_rate_data para obter informações detalhadas.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.
O nome do tipo de taxa de juros aplicada ao empréstimo.
Nota: Para OFDA Brasil, recomendamos que você use o parâmetro interest_date_data.tax_type.
O período em que o juro é aplicado ao empréstimo.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.
A taxa de juros (em porcentagem ou valor monetário).
Nota: Para OFDA Brasil, recomendamos que você use os parâmetros interest_date_data.pre_fixed_rate e interest_date_data.post_fixed_rate.
Informações detalhadas sobre a taxa de juros.
O tipo de imposto sobre a taxa de juros. Retornamos um dos seguintes valores:
NOMINALEFFECTIVENão anulável: Um valor deve ser retornado pela rede de open finance do Brasil.
O tipo de taxa de juros. Retornamos um dos seguintes valores:
SIMPLECOMPOUNDNon-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.
O período em que o juro é aplicado ao empréstimo.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.
O cálculo base para a taxa de juros.
Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.
A taxa de índice de referência. Retornamos um dos seguintes valores:
WITHOUT_INDEX_TYPEPRE_FIXEDPOST_FIXEDFLOATINGINDEXED_PRICERURAL_CREDITOTHER_INDEXNão anulável: Um valor deve ser retornado pela rede de open finance do Brasil.
O subtipo da taxa de índice de referência.
Informações adicionais sobre a taxa de índice de referência.
A taxa de juros com percentual prefixado.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.
A taxa de juros com percentual pós-fixado.
Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.
Detalhamento das taxas aplicadas ao empréstimo.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
O valor total da taxa. Mesma moeda do empréstimo.
O nome da taxa.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo
feesestiver disponível.
O código de tarifa.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo
feesestiver disponível.
Indica o tipo de cobrança. Retornamos um dos seguintes valores:
SINGLEPER_INSTALLMENTNão anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo
feesestiver disponível.
Método de cobrança, conforme acordado com a instituição. Retornamos um dos seguintes valores:
MINIMUMMAXIMUMFIXEDPERCENTAGENão anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo
feesestiver disponível.
Parece que você não forneceu nenhum texto para tradução. Por favor, envie o texto que deseja que eu traduza do inglês para o português (Brasil).
Detalhes sobre quaisquer garantias de empréstimo que o indivíduo ou empresa forneceu.
O tipo de garantia, conforme definido pela instituição.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo
collateralsestiver disponível.
O subtipo da garantia, conforme definido pela instituição.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil se o campo
collateralsestiver disponível.
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 se o campo
collateralsestiver disponível.
Informações detalhadas sobre quaisquer pagamentos de balloon para o empréstimo, se aplicável.
A frequência dos pagamentos parcelados contratados, conforme definido quando o contrato foi assinado pela primeira vez. Retornamos um dos seguintes:
DAYWEEKMONTHYEARNO_DEADLINE_REMAININGnullA frequência com que as parcelas são pagas. Retornamos um dos seguintes valores:
IRREGULARWEEKLYFORTNIGHTLYMONTHLYBIMONTHLYQUARTERLYBIANNUALLYANNUALLYOTHERNon-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.
Informações adicionais sobre o installment_frequency.
A data em que a primeira parcela do empréstimo deve ser paga, no formato YYYY-MM-DD.
O número total de parcelas necessárias para quitar o empréstimo.
O número de parcelas restantes a pagar.
O número de parcelas já pagas.
O número de parcelas que estão em atraso.
Um array de datas em que o empréstimo foi desembolsado.
A data em que o empréstimo foi liquidado, no formato YYYY-MM-DD.
A data em que o contrato de empréstimo foi assinado, no formato YYYY-MM-DD.
Não anulável: Um valor deve ser retornado pela rede de open finance do Brasil.
A data em que se espera que o empréstimo seja concluído, no formato YYYY-MM-DD.
A frequência dos pagamentos das parcelas restantes contratadas, conforme definido quando o contrato foi assinado pela primeira vez. Retornamos um dos seguintes valores:
DAYWEEKMONTHYEARNO_DEADLINE_REMAININGnullO número total de parcelas restantes no empréstimo.
O cronograma de amortização do empréstimo.
Non-nullable: Um valor deve ser retornado pela rede de open finance do Brasil.
Informações adicionais sobre o amortization_schedule.
O ID do consignatário do empréstimo.
O número do contrato do empréstimo, conforme fornecido pela instituição.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Nota: Este campo não se aplica ao OF Brasil e retornará null.
Exemplo de uma conta corrente (OFDA Brasil).
{ "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "institution": { "name": "ofmockbank_br_retail", "type": "bank" }, "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "last_accessed_at": "2021-03-09T10:28:40.000Z", "category": "CHECKING_ACCOUNT", "balance_type": "ASSET", "overdraft": { "used": 10000.99, "arranged": 99.99, "unarranged": 99.99 }, "type": "CONTA_DEPOSITO_A_VISTA", "subtype": "INDIVIDUAL", "name": null, "number": "11188222", "agency": "6272", "check_digit": "4", "balance": { "current": 999.99, "available": 15000, "blocked": 41233.07, "automatically_invested": 15000 }, "currency": "BRL", "public_identification_name": "AGENCY/NUMBER", "public_identification_value": "6272/11188222", "internal_identification": "92792126019929279212650822221989319252576", "credit_data": null, "loan_data": null, "funds_data": null }
Excluir uma conta específica da sua conta Belvo.
Este endpoint possui limite de taxa. Você pode excluir apenas 5 itens por minuto. Se exceder esse limite, você receberá um código de status 429.
Ao excluir uma conta, todas as transações associadas e informações do proprietário para essa conta também são removidas.
https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/accounts/{id}/
https://sandbox.belvo.com/api/accounts/{id}/
curl -i -X DELETE \
-u <username>:<password> \
'https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/accounts/{id}/'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.