Pular para o conteúdo

Documentação da API Belvo (1.223.0)

Introdução

Alcance novos públicos e converta mais usuários conectando-se fácil e seguramente aos seus dados financeiros, 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 forma 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, baixe-a 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 ao Tratamento de Erros.

Política de Retentativa

Erros 50x

Implemente um backoff exponencial automatizado de até cinco tentativas. Recomendamos usar um intervalo base de três segundos com um fator de dois. Por exemplo, a primeira tentativa deve ser após três segundos, a segunda tentativa após seis segundos (2 * 3), a terceira tentativa após 12 segundos (2 * 6), a quarta tentativa após 24 segundos (2 * 12) e a quinta tentativa 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 significa que seu usuário final está acessando a conta de outro navegador ao mesmo tempo. Nesse caso, implemente a mesma política de retentativa 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.

📘 Info

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
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.
SchemasOperaçõ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.

SchemasOperaçõ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

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.
SchemasOperações

Balances

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

SchemasOperações

Exchanges

Uma troca é uma operação de câmbio na Rede de Open Finance do Brasil. O recurso contém detalhes das operações de câmbio, incluindo taxas de câmbio, valores em moedas locais e estrangeiras, e informações de liquidação. Cada operação de câmbio pode ter eventos históricos associados que registram quaisquer modificações no contrato original.

SchemasOperações

Objeto de Histórico de Câmbio (Brasil)

Detalhes sobre eventos de modificação para uma operação de câmbio na Rede de Open Finance do Brasil.

Cada entrada no histórico representa um evento de modificação (uma trilha de auditoria) para uma operação de câmbio. O objeto Exchange contém os dados originais do contrato, enquanto quaisquer alterações no contrato (modificações, alterações em liquidações, etc.) são registradas como eventos no histórico.

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"
exchange_idstring(uuid)obrigatório

O identificador único gerado pela Belvo para a operação de câmbio original.

Exemplo: "c4bfecf9-4eb6-4920-9f9f-e1f1e60ef321"
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"
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"
operation_identifierstring<= 100 characters^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$obrigatório

O identificador único da rede para a operação de troca.

Exemplo: "92792126019929240"
event_sequence_numberstring<= 12 characters^\d{12}$obrigatório

O número de sequência do registro do evento no Banco Central (Bacen).

Exemplo: "493874649457"
event_typeintegerobrigatório

O tipo de evento que ocorreu para a operação de câmbio.

Retornamos um dos seguintes valores do enum:

  • 1 - Contrato no mercado primário
  • 2 - Modificação de operação de câmbio no mercado primário
  • 3 - Cancelamento de operação de câmbio no mercado primário
  • 4 - Liquidação de operação de câmbio no mercado primário
  • 5 - Baixa de valor pendente a liquidar no mercado primário
  • 6 - Restabelecimento de valor pendente baixado no mercado primário
  • 9 - Anulação de operação de câmbio no mercado primário (usado, por exemplo, na anulação de um evento de liquidação/cancelamento)

Nota: Os códigos seguem o layout de mensagens enviadas pelas instituições ao Banco Central do Brasil.

Enum1234569
Exemplo: 2
event_created_atstring(date-time)^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

O carimbo de data e hora ISO-8601 quando o evento ocorreu.

Exemplo: "2023-03-10T14:00:00Z"
operation_due_datestring or null(date)= 10 characters^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...

A data em que a operação (compra ou venda), após o evento, está programada para ser liquidada, no formato YYYY-MM-DD.

Exemplo: "2023-03-20"
local_operation_tax_amountnumber or null(float)^\d{1,15}\.\d{1,15}$

A taxa de câmbio aplicada à operação após o evento.

Exemplo: 1.4
local_operation_tax_currencystring or null= 3 characters^[A-Z]{3}$

O código de moeda de três letras (ISO-4217) para a taxa de câmbio.

Exemplo: "BRL"
local_operation_value_amountnumber or null(float)^\d{1,17}\.\d{2}$

O valor total da operação em moeda local após o evento.

Exemplo: 950
local_operation_value_currencystring or null= 3 characters^[A-Z]{3}$

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

Exemplo: "BRL"
foreign_operation_value_amountnumber or null(float)^\d{1,17}\.\d{2}$

O valor total da operação em moeda estrangeira após o evento.

Exemplo: 678.57
foreign_operation_value_currencystring or null= 3 characters^[A-Z]{3}$

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

Exemplo: "USD"
operation_outstanding_balance_amountnumber or null(float)^\d{1,17}\.\d{2}$

O saldo pendente a ser liquidado em moeda estrangeira após o evento.

Este campo é obrigatório para eventos criados (event_created_at) a partir de 15 de abril de 2024, em casos de operações de câmbio com liquidação futura.

Exemplo: 678.57
operation_outstanding_balance_currencystring or null= 3 characters^[A-Z]{3}$

A moeda do saldo devedor. Obrigatório se operation_outstanding_balance_amount não for null.

Exemplo: "USD"
tev_amount_amountnumber or null(float)^\d{1,15}\.\d{1,15}$

O "All-in Rate" (Valor Efetivo Total/Total Effective Cost), que representa o custo total da operação após o evento.

Este campo é obrigatório para operações de câmbio à vista que atingem até o limite de $100.000 USD ou equivalente em outras moedas.

Exemplo: 1002
tev_amount_currencystring or null= 3 characters^[A-Z]{3}$

A moeda do VET (sempre BRL). Obrigatório se tev_amount_amount não for null.

Exemplo: "BRL"
local_currency_advance_percentagenumber or null(float)^\d{1}\.\d{1,6}$

A porcentagem do valor em moeda estrangeira que foi concedida ao cliente antecipadamente após o evento.

Este campo é obrigatório em casos de operações de câmbio com liquidação futura.

Exemplo: 0.12
settlement_methodstring or null

O método de entrega para a moeda estrangeira.

Retornamos um dos seguintes valores do enum:

  • CARTA_CREDITO_A_VISTA (Código 10) - Carta de crédito à vista
  • CARTA_CREDITO_A_PRAZO (Código 15) - Carta de crédito a prazo
  • CONTA_DEPOSITO (Código 20) - Conta de depósito
  • CONTA_DEPOSITO_MOEDA_ESTRANGEIRA_PAIS (Código 21) - Conta de depósito em moeda estrangeira no país
  • CONTA_DEPOSITO_EXPORTADOR_MANTIDA_NO_EXTERIOR (Código 22) - Conta de depósito do exportador mantida no exterior
  • CONTA_DEPOSITO_OU_PAGAMENTO_EXPORTADOR_INSTITUICAO_EXTERIOR (Código 23) - Conta de depósito ou pagamento ao exportador em instituição no exterior
  • CONVENIO_PAGAMENTOS_E_CREDITOS_RECIPROCOS (Código 25) - Convênio de pagamentos e créditos recíprocos
  • CHEQUE (Código 30) - Cheque
  • ESPECIE_CHEQUES_VIAGEM (Código 50) - Espécie ou cheques de viagem
  • CARTAO_PREPAGO (Código 55) - Cartão pré-pago
  • TELETRANSMISSAO (Código 65) - Transferência eletrônica
  • TITULOS_VALORES (Código 75) - Títulos/valores mobiliários
  • SIMBOLICA (Código 90) - Simbólica
  • SEM_MOVIMENTACAO_VALORES (Código 91) - Sem movimentação de valores
  • DEMAIS (Código 99) - Outros
  • OUTRO_NAO_MAPEADO_OFB - Outro não mapeado pelo Open Finance Brasil
  • null
Enum"CONTA_DEPOSITO_MOEDA_ESTRANGEIRA_PAIS""CONTA_DEPOSITO_OU_PAGAMENTO_EXPORTADOR_INSTITUICAO_EXTERIOR""ESPECIE_CHEQUES_VIAGEM""CARTAO_PREPAGO""TELETRANSMISSAO""SEM_MOVIMENTACAO_VALORES""DEMAIS""CARTA_CREDITO_A_VISTA""CARTA_CREDITO_A_PRAZO""CONTA_DEPOSITO"
Exemplo: "CARTA_CREDITO_A_PRAZO"
operation_category_codestring or null<= 5 characters^\d{5}$

O código de 5 dígitos do Banco Central que classifica a "natureza" da operação.

Este código deve estar em conformidade com os códigos de natureza referenciados na Resolução 277 ou na Circular 3690, conforme aplicável ao contrato de câmbio.

Exemplo: "90302"
foreign_partie_relationship_codestring or null<= 2 characters^\d{2}$

O código que indica a relação entre o cliente e o pagador/recebedor estrangeiro.

Este código deve estar em conformidade com os códigos de relacionamento referenciados na Resolução 277 ou na Circular 3690, conforme aplicável ao contrato de câmbio.

Nota: Este campo é opcional quando:

  • O campo settlement_method é ESPECIE_CHEQUES_VIAGEM ou CARTAO_PREPAGO.
  • O campo event_type é diferente de 4 (Liquidação de operação de câmbio no mercado primário).

Se a instituição possuir esta informação, é obrigatório enviá-la. Se a informação for atualizada após a contratação, deve ser enviada por meio de eventos.

Exemplo: "50"
foreign_partie_namestring or null<= 80 characters[\w\W\s]*

O nome do pagador ou recebedor estrangeiro.

Nota: Este campo é opcional quando:

  • O campo settlement_method é ESPECIE_CHEQUES_VIAGEM ou CARTAO_PREPAGO.
  • O campo event_type é diferente de 4 (Liquidação de operação de câmbio no mercado primário).

Se a instituição possuir esta informação, é obrigatório enviá-la. Se a informação for atualizada após a contratação, deve ser enviada por meio de eventos.

Exemplo: "Global Tech Imports LLC"
foreign_partie_country_codestring or null= 2 characters^[A-Z]{2}$

O código do país do pagador ou recebedor estrangeiro, conforme o padrão ISO 3166-1.

Nota: Este campo é opcional quando:

  • O campo settlement_method é ESPECIE_CHEQUES_VIAGEM ou CARTAO_PREPAGO.
  • O campo event_type é diferente de 4 (Liquidação de operação de câmbio no mercado primário).

Se a instituição possuir esta informação, é obrigatório enviá-la. Se a informação for atualizada após a contratação, deve ser enviada por meio de eventos.

Exemplo: "US"
{
  "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
  "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
  "exchange_id": "c4bfecf9-4eb6-4920-9f9f-e1f1e60ef321",
  "created_at": "2022-02-09T08:45:50.406032Z",
  "collected_at": "2022-02-09T08:45:50.406032Z",
  "operation_identifier": "92792126019929240",
  "event_sequence_number": "493874649457",
  "event_type": 2,
  "event_created_at": "2023-03-10T14:00:00Z",
  "operation_due_date": "2023-03-20",
  "local_operation_tax_amount": 1.4,
  "local_operation_tax_currency": "BRL",
  "local_operation_value_amount": 950,
  "local_operation_value_currency": "BRL",
  "foreign_operation_value_amount": 678.57,
  "foreign_operation_value_currency": "USD",
  "operation_outstanding_balance_amount": 678.57,
  "operation_outstanding_balance_currency": "USD",
  "tev_amount_amount": 1002,
  "tev_amount_currency": "BRL",
  "local_currency_advance_percentage": 0.12,
  "settlement_method": "CARTA_CREDITO_A_PRAZO",
  "operation_category_code": "90302",
  "foreign_partie_relationship_code": "50",
  "foreign_partie_name": "Global Tech Imports LLC",
  "foreign_partie_country_code": "US"
}

Coming SoonListar exchanges

Requisição

Em Breve

Este endpoint está atualmente em desenvolvimento. Portanto, pequenas alterações ou bugs podem ocorrer. Se você encontrar algum problema, entre em contato com seu representante da Belvo.

▶️ Uso

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

  1. [Obrigatório] Listar exchanges relacionadas a um link.id específico (usando o parâmetro de consulta link).
  2. Obter os detalhes de um exchange.id específico (usando o parâmetro de consulta id).

🔦 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.

📖 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, veja nosso artigo Dicas de Paginação.

Segurança
basicAuth
Consulta
linkstring(uuid)obrigatório

O link.id pelo qual você deseja filtrar.

Exemplo: link=8848bd0c-9c7e-4f53-a732-ec896b11d4c4
idstring(uuid)

Retorne informações apenas para este recurso id.

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

Retorne resultados apenas para esses link.ids.

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

Retorne informações para esses ids de recurso.

Exemplo: id__in=6b3dea0f-be29-49d1-aabe-1a6d588642e6
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.

collected_atstring(date)

Retorne itens que foram recuperados da instituição nesta data (YYYY-MM-DD ou timestamp completo ISO-8601).

Exemplo: collected_at=2022-05-01
collected_at__gtstring(date)

Retorne itens que foram recuperados da instituição após esta data (YYYY-MM-DD ou timestamp completo ISO-8601).

Exemplo: collected_at__gt=2022-05-05
collected_at__gtestring(date)

Retorne itens que foram recuperados da instituição após ou nesta data (YYYY-MM-DD ou timestamp completo ISO-8601).

Exemplo: collected_at__gte=2022-05-04
collected_at__ltstring(date)

Retorne itens que foram recuperados da instituição antes desta data (YYYY-MM-DD ou timestamp completo ISO-8601).

Exemplo: collected_at__lt=2022-04-01
collected_at__ltestring(date)

Retorne itens que foram recuperados da instituição antes ou nesta data (YYYY-MM-DD ou timestamp completo ISO-8601).

Exemplo: collected_at__lte=2022-03-30
collected_at__rangeArray of strings(date)<= 2 items

Retorne itens que foram recuperados da instituição entre duas datas (YYYY-MM-DD ou timestamp completo ISO-8601). O primeiro valor indica o início do intervalo e o segundo valor indica o final do intervalo.

Exemplo: collected_at__range=2022-01-01,2022-12-31
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). O primeiro valor indica o início do intervalo e o segundo valor indica o final do intervalo.

Exemplo: created_at__range=2022-01-01,2022-12-31
curl -i -X GET \
  -u <username>:<password> \
  'https://sandbox.belvo.com/api/br/exchanges/?link=8848bd0c-9c7e-4f53-a732-ec896b11d4c4&id=24ccab1d-3a86-4136-a6eb-e04bf52b356f&link__in=5722d0ba-69d7-42dc-8ff5-33767b83c5d6&id__in=6b3dea0f-be29-49d1-aabe-1a6d588642e6&page_size=100&page=1&omit=string&fields=string&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-01-01%2C2022-12-31&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-01-01%2C2022-12-31'

Respostas

OK - Trocas Recuperadas

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 objects

Um array de objetos de exchange.

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

Coming SoonRecuperar trocas para um link

Requisição

Em Breve

Este endpoint está atualmente em desenvolvimento. Portanto, pequenas alterações ou bugs podem ocorrer. Se você encontrar algum problema, entre em contato com seu representante da Belvo.

Recupere operações de câmbio para um link existente. Por padrão, recuperamos dados de câmbio dos últimos 365 dias.

Nota: Quando você recupera câmbios, nós automaticamente recuperamos o histórico de câmbio para cada operação de câmbio encontrada.

Segurança
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"
date_fromstring(date)

A data de início para a qual você deseja recuperar dados de câmbio, no formato YYYY-MM-DD. Se não for fornecida, recuperamos dados dos últimos 365 dias.

Exemplo: "2022-01-01"
date_tostring(date)

A data de término para a qual você deseja recuperar dados de câmbio, no formato YYYY-MM-DD. Se não for fornecida, recuperamos dados até hoje.

Exemplo: "2022-12-31"
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://sandbox.belvo.com/api/br/exchanges/?omit=string&fields=string' \
  -H 'Content-Type: application/json' \
  -d '{
    "link": "c81a1dea-6dd6-4999-8b9f-541ee8197058",
    "date_from": "2022-01-01",
    "date_to": "2022-12-31",
    "save_data": true
  }'

Respostas

OK - Exchanges Retrieved (quando save_data=false)

Corpoapplication/jsonArray [
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"
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"
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"
operation_identifierstring<= 100 characters^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$obrigatório

O identificador único da rede para a operação de troca.

Exemplo: "92792126019929240"
operation_numberstring or null<= 12 characters^\d{12}$

O número de registro da operação de 12 dígitos do Banco Central do Brasil (Bacen). Isso pode ser null se a operação ainda não tiver sido registrada.

Exemplo: "393874649456"
operation_typestringobrigatório

O tipo de operação de câmbio.

Retornamos um dos seguintes valores do enum:

  • COMPRA - Compra (o cliente está comprando moeda estrangeira)
  • VENDA - Venda (o cliente está vendendo moeda estrangeira)
Enum"COMPRA""VENDA"
Exemplo: "COMPRA"
operation_requested_atstring(date-time)^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?...obrigatório

O carimbo de data e hora ISO-8601 quando a operação de câmbio foi contratada.

Exemplo: "2023-03-07T08:30:00Z"
authorized_institution_identifierinteger(int64)obrigatório

O CNPJ da instituição autorizada a realizar a operação.

Exemplo: 11225860000140
authorized_institution_namestring<= 80 charactersobrigatório

O nome da instituição autorizada.

Exemplo: "AGENCIA CORRETORA"
intermediary_institution_identifierinteger or null(int64)

O CNPJ da instituição intermediária, se uma foi utilizada.

Exemplo: 11225860000140
intermediary_institution_namestring or null<= 80 characters

O nome da instituição intermediária. Deve estar presente se intermediary_institution_identifier estiver disponível.

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

A data de liquidação atualmente agendada para a operação, no formato YYYY-MM-DD.

Nota: Este campo é atualizado se houver alterações na operação de câmbio.

Exemplo: "2018-02-15"
local_operation_tax_amountnumber(float)^\d{1,15}\.\d{1,15}$obrigatório

A taxa de câmbio aplicada à operação.

Exemplo: 1.3
local_operation_tax_currencystring= 3 characters^[A-Z]{3}$obrigatório

O código de moeda de três letras (ISO-4217) para a taxa de câmbio.

Exemplo: "BRL"
local_operation_value_amountnumber(float)^\d{1,17}\.\d{2}$obrigatório

O valor total da operação em moeda local.

Exemplo: 1000.04
local_operation_value_currencystring= 3 characters^[A-Z]{3}$obrigatório

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

Exemplo: "BRL"
foreign_operation_value_amountnumber(float)^\d{1,17}\.\d{2}$obrigatório

O valor total da operação na moeda estrangeira.

Exemplo: 1000.04
foreign_operation_value_currencystring= 3 characters^[A-Z]{3}$obrigatório

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

Exemplo: "USD"
operation_outstanding_balance_amountnumber or null(float)^\d{1,17}\.\d{2}$

O saldo pendente a ser liquidado, na moeda estrangeira. No caso de a operação de câmbio estar programada para ser liquidada dentro de dois dias a partir de operation_requested_at, esse valor pode ser null.

Exemplo: 1000.04
operation_outstanding_balance_currencystring or null= 3 characters^[A-Z]{3}$

A moeda do saldo devedor. Obrigatório se operation_outstanding_balance_amount não for null.

Exemplo: "USD"
tev_amount_amountnumber or null(float)^\d{1,15}\.\d{1,15}$

O "All-in Rate" (Valor Efetivo Total/Custo Efetivo Total), que representa o custo total da operação. Obrigatório quando a operação está programada para ser liquidada dentro de dois dias a partir de operation_requested_at e não excede $100,000 USD.

Exemplo: 1000.000004
tev_amount_currencystring or null= 3 characters^[A-Z]{3}$

A moeda do VET (sempre BRL). Obrigatório se tev_amount_amount não for null.

Exemplo: "BRL"
local_currency_advance_percentagenumber or null(float)^\d{1}\.\d{1,6}$

A porcentagem do valor em moeda estrangeira que foi concedida ao cliente antecipadamente. No caso de a operação de câmbio estar programada para ser liquidada dentro de dois dias a partir de operation_requested_at, esse valor pode ser null.

Exemplo: 0.12
settlement_methodstring or nullobrigatório

O método de entrega para a moeda estrangeira.

Retornamos um dos seguintes valores do enum:

  • CARTA_CREDITO_A_VISTA (Código 10) - Carta de crédito à vista
  • CARTA_CREDITO_A_PRAZO (Código 15) - Carta de crédito a prazo
  • CONTA_DEPOSITO (Código 20) - Conta de depósito
  • CONTA_DEPOSITO_MOEDA_ESTRANGEIRA_PAIS (Código 21) - Conta de depósito em moeda estrangeira no país
  • CONTA_DEPOSITO_EXPORTADOR_MANTIDA_NO_EXTERIOR (Código 22) - Conta de depósito do exportador mantida no exterior
  • CONTA_DEPOSITO_OU_PAGAMENTO_EXPORTADOR_INSTITUICAO_EXTERIOR (Código 23) - Conta de depósito ou pagamento ao exportador em instituição no exterior
  • CONVENIO_PAGAMENTOS_E_CREDITOS_RECIPROCOS (Código 25) - Convênio de pagamentos e créditos recíprocos
  • CHEQUE (Código 30) - Cheque
  • ESPECIE_CHEQUES_VIAGEM (Código 50) - Espécie ou cheques de viagem
  • CARTAO_PREPAGO (Código 55) - Cartão pré-pago
  • TELETRANSMISSAO (Código 65) - Transferência eletrônica
  • TITULOS_VALORES (Código 75) - Títulos/valores mobiliários
  • SIMBOLICA (Código 90) - Simbólica
  • SEM_MOVIMENTACAO_VALORES (Código 91) - Sem movimentação de valores
  • DEMAIS (Código 99) - Outros
  • OUTRO_NAO_MAPEADO_OFB - Outro não mapeado pelo Open Finance Brasil
  • null
Enum"CONTA_DEPOSITO_MOEDA_ESTRANGEIRA_PAIS""CONTA_DEPOSITO_OU_PAGAMENTO_EXPORTADOR_INSTITUICAO_EXTERIOR""ESPECIE_CHEQUES_VIAGEM""CARTAO_PREPAGO""TELETRANSMISSAO""SEM_MOVIMENTACAO_VALORES""DEMAIS""CARTA_CREDITO_A_VISTA""CARTA_CREDITO_A_PRAZO""CONTA_DEPOSITO"
Exemplo: "CARTA_CREDITO_A_PRAZO"
operation_category_codestring<= 5 characters^\d{5}$obrigatório

O código de 5 dígitos do Banco Central que classifica a "natureza" da operação.

Este código deve estar em conformidade com os códigos de natureza referenciados na Resolução 277 ou na Circular 3690, conforme aplicável ao contrato de câmbio.

Exemplo: "90302"
]
Resposta
application/json
[
  {
    "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",
    "operation_identifier": "92792126019929240",
    "operation_number": "393874649456",
    "operation_type": "COMPRA",
    "operation_requested_at": "2023-03-07T08:30:00Z",
    "authorized_institution_identifier": 11225860000140,
    "authorized_institution_name": "AGENCIA CORRETORA",
    "intermediary_institution_identifier": 11225860000140,
    "intermediary_institution_name": "AGENCIA CORRETORA",
    "operation_due_date": "2018-02-15",
    "local_operation_tax_amount": 1.3,
    "local_operation_tax_currency": "BRL",
    "local_operation_value_amount": 1000.04,
    "local_operation_value_currency": "BRL",
    "foreign_operation_value_amount": 1000.04,
    "foreign_operation_value_currency": "USD",
    "operation_outstanding_balance_amount": 1000.04,
    "operation_outstanding_balance_currency": "USD",
    "tev_amount_amount": 1000.000004,
    "tev_amount_currency": "BRL",
    "local_currency_advance_percentage": 0.12,
    "settlement_method": "CARTA_CREDITO_A_PRAZO",
    "operation_category_code": "90302"
  }
]

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.

SchemasOperações

Bills

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

SchemasOperações

Investments Brazil

SchemasOperações

Investment Transactions Brazil

SchemasOperaçõ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)
SchemasOperaçõ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)
SchemasOperações

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.

SchemasOperações

Invoices

SchemasOperações

Tax compliance status

SchemasOperações

Tax returns

Operações

Tax retentions

SchemasOperações

Tax status

SchemasOperações

Financial Statements

SchemasOperações

Invoices Chile

SchemasOperações

Tax Status Chile

SchemasOperações

Debt Reports Chile

SchemasOperaçõ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.

SchemasOperaçõ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.

SchemasOperações

Risk Insights

SchemasOperações

Employment Metrics

SchemasOperaçõ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 cliente é o pagador que vai transferir fundos para sua conta bancária. Você precisa criar um cliente para receber pagamentos de entrada na conta bancária da sua organização.

Versionamento de Recursos

Este endpoint suporta versionamento a nível de recurso. Ao incluir o cabeçalho X-Belvo-API-Resource-Version: Payments-BR.V2, você pode acessar os formatos de requisição e resposta mais recentes (V2). Se o cabeçalho não for fornecido, o formato padrão (V1) será utilizado. Consulte a documentação da API para detalhes sobre as diferenças entre as versões.

Operações

Bank Accounts (Brazil)

Para receber pagamentos de entrada na conta bancária da sua organização, é necessário 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).
Versionamento de Recursos

Este endpoint suporta versionamento a nível de recurso. Ao incluir o cabeçalho X-Belvo-API-Resource-Version: Payments-BR.V2, você pode acessar os formatos de requisição e resposta mais recentes (V2). Se o cabeçalho não for fornecido, o formato padrão (V1) será utilizado. Consulte a documentação da API para detalhes sobre as diferenças entre as versões.

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

Charges (Brazil)

Operações

Payment Intents (Brazil)

Uma intenção de pagamento é um ponto único de acesso para criar pagamentos usando qualquer método de pagamento oferecido pela Belvo.

Uma intenção de pagamento 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.

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