# Documentação da API Belvo # 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 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.| ## Tratamento de Erros Os erros da API Belvo são retornados em formato JSON. Por exemplo, um erro pode ser assim: ```json [ { "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. Version: 1.223.0 ## Servers Ambiente de Testes ``` https://sandbox.belvo.com ``` ## Security ### basicAuth A Belvo utiliza **autenticação básica** usando suas chaves secretas (Você pode encontrar suas chaves secretas da API no seu Painel da Belvo, na seção **Desenvolvedores**). Para autenticar, você precisa usar seu `secretId` da API como `username` e seu `secretPassword` da API como `password`. Essas credenciais precisam ser codificadas em **Base64** e incluídas no cabeçalho `Authorization` das suas requisições HTTP. Por exemplo: ```shell curl -X GET https://sandbox.belvo.com/api/ \ -H "Authorization: Basic $(echo -n 'YOUR_SECRET_ID:YOUR_SECRET_PASSWORD' | base64)" ``` Substitua `YOUR_SECRET_ID` e `YOUR_SECRET_PASSWORD` pelas suas credenciais reais. **Nunca exponha suas credenciais em código do lado do cliente ou em repositórios públicos**. Type: http Scheme: basic ## Download OpenAPI description [Documentação da API Belvo](https://developers.belvo.com/_bundle/@l10n/pt-BR/apis/BelvoOpenApiSpec.yaml) ## 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. ### Listar instituições - [GET /api/institutions/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/institutions/listinstitutions.md): ## ▶️ Uso Com o método List Institutions, você pode: 1. Listar todas as instituições disponíveis no Belvo. ## 📖 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 do 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. ### Obter os detalhes de uma instituição - [GET /api/institutions/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/institutions/detailinstitution.md): Obtenha os detalhes de uma instituição específica. ## 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. ### Listar links - [GET /api/links/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/listlinks.md): ## ▶️ Uso Com o método List Links, você pode: 1. Listar todos os links relacionados à sua conta Belvo (sem usar parâmetros de consulta). 2. Obter os detalhes de um link.id específico (usando o parâmetro de consulta id). ## 📖 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. ### Registrar um novo link - [POST /api/links/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/registerlink.md): ## ▶️ Uso Registre um novo link (uma conexão entre seu usuário e sua instituição) usando a API da Belvo. > 👍 Recomendamos fortemente o uso do nosso Connect Widget para gerenciar a criação de links e atualizações de status de links. Para facilitar, incluímos exemplos personalizados para os links que você pode criar para cada um dos nossos produtos. Basta clicar no tipo de link que você deseja criar na seção Body Params abaixo. ### Solicitação completa de links - [PATCH /api/links/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/patchlinks.md): Usado para retomar uma sessão de registro de Link que foi pausada porque um token MFA foi exigido pela instituição. ### Obter detalhes de um link - [GET /api/links/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/detaillink.md): Obtenha os detalhes de um link específico. ### Modificar a recuperação de dados de um link - [PATCH /api/links/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/modifylinkdataretrieval.md): Modificar as configurações de recuperação de dados para um link específico. Atualmente, você pode: - Alterar o modo de acesso de um link de single para recurrent ou de recurrent para single. - Modificar o período stale_in para o link. - Modificar os recursos históricos que você deseja recuperar para o link (fetch_resources). ## Alterando o access_mode de um link Quando você altera um link de single para recurrent, no dia seguinte é acionada uma atualização histórica dos recursos principais para o link (resultando no recebimento de webhooks de historical_update para o link). Você será cobrado por essas atualizações históricas. ## Modificando stale_in Se você apenas modificar o período stale_in para um link, isso não acionará uma atualização histórica. Para acionar uma atualização histórica para o link, você deve alterar o access_mode. ## Modificando fetch_resources Se você apenas modificar o fetch_resources para um link, isso não acionará uma atualização histórica. Para acionar uma atualização histórica para o link, você deve alterar o access_mode. ### Atualizar as credenciais de um link - [PUT /api/links/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/updatelink.md): Atualize as credenciais de um link específico. Se o link atualizado com sucesso for recorrente, acionamos automaticamente uma atualização do link. Se encontrarmos dados novos, você receberá webhooks de atualização histórica. > 👍 Use nosso Connect Widget > > Recomendamos usar nosso Connect Widget para lidar com a atualização de links invalid ou token_required. ### Excluir um link - [DELETE /api/links/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/destroylink.md): Exclua um link específico e todos os dados associados (por exemplo: transações, contas, faturas, declarações de impostos, empregos, etc.) desse link da sua conta Belvo. Esta ação é irreversível e você não poderá recuperar os dados excluídos. {% admonition type="success" name="Use o cabeçalho X-Belvo-Request-Mode: async" %} Recomendamos fortemente definir o cabeçalho X-Belvo-Request-Mode como async para habilitar a exclusão assíncrona. Dessa forma, você evitará o limite de taxa de 5 exclusões por minuto. Quando configurado, o endpoint responderá com um status 202 Accepted e fornecerá um ID de solicitação para rastrear o processo de exclusão. Assim que o processo for concluído, você receberá uma notificação webhook link_deleted. Se você não definir este cabeçalho, o endpoint responderá com um status 204 No Content, mas você estará sujeito ao limite de taxa de 5 exclusões por minuto. Se exceder esse limite, você receberá um erro 429 Too Many Requests. {% /admonition %} ### Acionar uma atualização histórica para um link - [POST /api/links/{id}/refresh/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/refreshhistoricaldataforlink.md): {% admonition type="warning" name="Limite de Requisições Concorrentes" %} Para evitar requisições duplicadas, este endpoint possui um período de cooldown de 10 minutos por link. Se você tentar atualizar o mesmo link dentro de 10 minutos após uma solicitação anterior, receberá um erro 409 Conflict com a mensagem "The link has already been refreshed. Please wait X minutes before trying again.". {% /admonition %} Use este método para acionar uma atualização histórica para um link específico (único ou recorrente). Utilize o parâmetro fetch_resources para especificar quais recursos você deseja atualizar. Se você não especificar este parâmetro, a atualização histórica será realizada para todos os recursos suportados pela instituição à qual o link está associado. Em uma solicitação bem-sucedida, nossa API responderá com um código de status 202 e um request_id que você poderá usar posteriormente para associar um webhook de historical_update a esta solicitação. {% admonition type="info" name="Não atualiza a definição do link" %} Este endpoint não atualiza a definição do link em si, apenas os dados históricos para os recursos especificados. Se você deseja alterar permanentemente o fetch_resources do link, deve usar o método Modificar a recuperação de dados de um link. {% /admonition %} ## Widget Access Token ### Gerar um token de acesso para o widget - [POST /api/token/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/widget-access-token/generatewidgetaccesstoken.md): Gerar um token de acesso para nosso Widget Hospedado. ## Consents Um consentimento é uma permissão dada pelo usuário final para acessar seus dados financeiros na Rede de Open Finance no Brasil. ### Listar consentimentos - [GET /api/consents/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/consents/listconsents.md): ## ▶️ Uso Com o método Consents, você pode: 1. Listar todos os consentimentos 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. ### Obter os detalhes de um consentimento - [GET /api/consents/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/consents/detailconsent.md): Obtenha os detalhes de um consentimento específico. ## 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 ### Listar proprietários - [GET /api/owners/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/owners/listowners.md): ## ▶️ Uso Com o método List Owners, você pode: 1. Listar proprietários relacionados a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um owners.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todos os proprietários relacionados à sua conta Belvo (sem usar nenhum parâmetro de consulta). ## 📖 Paginação Este método retorna uma resposta paginada (padrão: 100 itens por página). Você pode usar o parâmetro de consulta page_size para aumentar o número de itens retornados até um máximo de 1000 itens. Você pode usar o parâmetro de consulta page para navegar pelos resultados. Para mais detalhes sobre como navegar nas respostas paginadas da Belvo, consulte nosso artigo Dicas de Paginação. ## 🔦 Filtrando Respostas Consulte a lista de consultas abaixo para ver uma lista de campos pelos quais você pode filtrar suas respostas. Para mais informações sobre como usar filtros, consulte nosso artigo Filtrando respostas. ## 🚨 Campos Obsoletos Este recurso pode retornar campos obsoletos. Na documentação de resposta, você pode ver que um campo foi marcado como obsoleto. Isso significa que este campo não é mais mantido pela equipe da Belvo. Você ainda pode receber dados para este campo dependendo da instituição, no entanto, não deve confiar neste campo. ### Recuperar proprietários de um link - [POST /api/owners/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/owners/retrieveowners.md): Recupere informações do proprietário a partir de um link específico. {% admonition type="info" %} Este recurso pode retornar campos obsoletos. Por favor, verifique a documentação da resposta para mais informações. {% /admonition %} ### Concluir uma solicitação do proprietário - [PATCH /api/owners/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/owners/patchowners.md): Usado para retomar uma sessão de recuperação de Proprietário que foi pausada porque um token MFA foi exigido pela instituição. {% admonition type="info" %} Este recurso pode retornar campos obsoletos. Por favor, verifique a documentação da resposta para mais informações. {% /admonition %} ### Obter os detalhes de um proprietário - [GET /api/owners/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/owners/detailowner.md): Obtenha os detalhes de um proprietário específico. {% admonition type="info" %} Este recurso pode retornar campos obsoletos. Por favor, verifique a documentação da resposta para mais informações. {% /admonition %} ### Excluir um proprietário - [DELETE /api/owners/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/owners/destroyowner.md): Excluir um proprietário específico da sua conta Belvo. ## 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. ### Listar contas - [GET /api/accounts/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/accounts/listaccounts.md): ## ▶️ Uso Com o método List Accounts, você pode: 1. Listar contas relacionadas a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um account.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todas as contas relacionadas à sua conta Belvo (sem usar nenhum parâmetro de consulta). ## 🔦 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. ## 🚨 Campos Obsoletos Este recurso pode retornar campos obsoletos. Na documentação de resposta, você pode ver que um campo foi marcado como obsoleto. Isso significa que este campo não é mais mantido pela equipe da Belvo. Você ainda pode receber dados para este campo dependendo da instituição, no entanto, não deve confiar neste campo. ### Recuperar contas para um link - [POST /api/accounts/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/accounts/retrieveaccounts.md): Recupere contas de um link existente. {% admonition type="info" %} Este recurso pode retornar campos obsoletos. Por favor, verifique a documentação da resposta para mais informações. {% /admonition %} ### Concluir uma solicitação de contas - [PATCH /api/accounts/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/accounts/patchaccounts.md): Usado para retomar uma sessão de recuperação de Conta que foi pausada porque um token MFA foi exigido pela instituição. {% admonition type="info" %} Este recurso pode retornar campos obsoletos. Por favor, verifique a documentação da resposta para mais informações. {% /admonition %} ### Obter os detalhes de uma conta - [GET /api/accounts/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/accounts/detailaccount.md): Obtenha os detalhes de uma conta específica. {% admonition type="info" %} Este recurso pode retornar campos obsoletos. Por favor, verifique a documentação da resposta para mais informações. {% /admonition %} ### Excluir uma conta - [DELETE /api/accounts/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/accounts/destroyaccount.md): Excluir uma conta específica da sua conta Belvo. {% admonition type="danger" name="Rate Limited" %} 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. {% /admonition %} {% admonition type="info" %} Ao excluir uma conta, todas as transações associadas e informações do proprietário para essa conta também são removidas. {% /admonition %} ## Balances Um saldo é a quantidade de dinheiro disponível em uma determinada conta bancária (corrente ou poupança) em um determinado momento. ### Listar saldos - [GET /api/br/balances/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/balances/listbalances.md): ## ▶️ Uso Com o método Listar Saldos, você pode: 1. [Obrigatório] Listar saldos relacionados a um link.id específico (usando o parâmetro de consulta link). 2. [Altamente Recomendado] Listar saldos relacionados a um link.id e account.id específicos (usando os parâmetros de consulta link e account). 3. Obter os detalhes de um balance.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. ## 🚨 Campos Obsoletos Este recurso pode retornar campos obsoletos. Na documentação de resposta, você pode ver que um campo foi marcado como obsoleto. Isso significa que este campo não é mais mantido pela equipe da Belvo. Você ainda pode receber dados para este campo dependendo da instituição, no entanto, não deve confiar neste campo. ### Recuperar o saldo atual de um link - [POST /api/br/balances/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/balances/retrievebalances.md): Recupere o saldo atual de todas as contas correntes e de poupança para um link existente. Recomendamos também enviar o account.id para que você receba os saldos de uma conta específica. ### Obter os detalhes de um saldo - [GET /api/br/balances/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/balances/detailbalance.md): Obtenha os detalhes de um saldo específico. ## 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. ### Listar exchanges - [GET /api/br/exchanges/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/exchanges/listexchanges.md): {% admonition type="warning" name="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. {% /admonition %} ## ▶️ 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. ### Recuperar trocas para um link - [POST /api/br/exchanges/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/exchanges/retrieveexchanges.md): {% admonition type="warning" name="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. {% /admonition %} 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. ### Obter os detalhes de uma exchange - [GET /api/br/exchanges/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/exchanges/detailexchange.md): {% admonition type="warning" name="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. {% /admonition %} Obtenha os detalhes de uma exchange específica. > Nota: Quando você exclui uma exchange, todos os registros de histórico associados a ela também são excluídos. ### Excluir uma exchange - [DELETE /api/br/exchanges/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/exchanges/deleteexchange.md): {% admonition type="warning" name="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 Belvo. {% /admonition %} Exclua uma exchange específica da sua conta Belvo. > Nota: Quando você exclui uma exchange, todos os registros de histórico associados a ela também são excluídos. ### Listar o histórico de troca para uma troca específica - [GET /api/br/exchanges/{id}/history/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/exchanges/listexchangehistory.md): {% admonition type="warning" name="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. {% /admonition %} Obtenha o histórico de modificações (trilha de auditoria) para uma operação de câmbio específica. ## 📖 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. ## 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. ### Listar transações - [GET /api/transactions/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/transactions/listtransactions.md): ## ▶️ Uso Com o método List Transactions, você pode: 1. [Obrigatório] Listar transações relacionadas a um link.id específico (usando o parâmetro de consulta link). 2. Filtrar as transações retornadas usando parâmetros de consulta (veja a seção Filtrando respostas abaixo). 3. Obter os detalhes de um transaction.id específico (usando o parâmetro de consulta id junto com o parâmetro de consulta link). ## 📖 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, consulte nosso artigo Filtrando respostas. ### Recuperar transações para um link - [POST /api/transactions/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/transactions/retrievetransactions.md): Recupere transações de uma ou mais contas a partir de um link específico. > 📘 Períodos de Transação e Recuperação > > Ao recuperar transações, é importante entender que os intervalos de dados de transações disponíveis dependem de cada instituição. Se você tentar acessar informações mais antigas do que podemos acessar, retornaremos todos os dados que conseguimos ler dentro desse intervalo de datas. Por exemplo, se você solicitar transações do último ano e só pudermos acessar os últimos seis meses, retornaremos as informações correspondentes a esses seis meses de dados. ### Concluir uma solicitação de transações - [PATCH /api/transactions/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/transactions/patchtransactions.md): Usado para retomar uma sessão de recuperação de Transação que foi pausada porque um token MFA foi exigido pela instituição. ### Obter os detalhes de uma transação - [GET /api/transactions/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/transactions/detailtransaction.md): Obtenha os detalhes de uma transação específica. ### Excluir uma transação - [DELETE /api/transactions/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/transactions/destroytransaction.md): Excluir uma transação específica da sua conta Belvo. > ❗️ Limite de taxa > > 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. ## Bills Uma **bill** refere-se à fatura do cartão de crédito que um usuário recebe para uma determinada conta. ### Listar contas - [GET /api/bills/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/bills/listbills.md): ## ▶️ Uso Com o método List Bills, você pode: 1. [Obrigatório] Listar contas relacionadas a um link.id específico (usando o parâmetro de consulta link). 2. Filtrar as contas retornadas usando parâmetros de consulta (veja a seção Filtrando respostas abaixo). 3. Obter os detalhes de uma conta específica usando o parâmetro de consulta id. ## 📖 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. ### Recuperar faturas para um link - [POST /api/bills/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/bills/retrievebills.md): Recupere faturas de uma ou mais contas para um link específico dentro de um intervalo de datas especificado. ### Obter os detalhes de uma fatura - [GET /api/bills/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/bills/detailbills.md): Obtenha os detalhes de uma conta específica. ### Excluir uma fatura - [DELETE /api/bills/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/bills/destroybills.md): Excluir uma fatura específica da sua conta Belvo. ## Investments Brazil ### Listar investimentos - [GET /api/br/investments/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/investments-brazil/listinvestmentsbrazil.md): ## ▶️ Uso Com o método Listar Investimentos, você pode: 1. [Obrigatório] Listar investimentos relacionados a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um investment.id específico (usando o parâmetro de consulta id). ## 📖 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. ### Recuperar investimentos para um link - [POST /api/br/investments/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/investments-brazil/retrieveinvestmentsbrazil.md): Recuperar investimentos para um link existente. ### Obter os detalhes de um investimento - [GET /api/br/investments/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/investments-brazil/detailinvestmentbrazil.md): Obtenha os detalhes de um investimento específico. ### Excluir um investimento - [DELETE /api/br/investments/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/investments-brazil/destroyinvestmentbrazil.md): Excluir um investimento específico da sua conta Belvo. ## Investment Transactions Brazil ### Listar transações de investimento - [GET /api/br/investment-transactions/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/investment-transactions-brazil/listinvestmenttransactionsbrazil.md): ## ▶️ Uso Com o método Listar Transações de Investimento, você pode: 1. [Obrigatório] Listar transações de investimento relacionadas a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um investment-transaction.id específico (usando o parâmetro de consulta id). ## 📖 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, consulte nosso artigo Filtrando respostas. ### Recuperar investimentos para um link - [POST /api/br/investment-transactions/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/investment-transactions-brazil/retrieveinvestmenttransactionsbrazil.md): Recuperar investimentos para um link existente. ### Obter os detalhes de uma transação de investimento - [GET /api/br/investment-transactions/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/investment-transactions-brazil/detailinvestmenttransactionbrazil.md): Obtenha os detalhes de uma transação de investimento específica. ### Excluir uma transação de investimento - [DELETE /api/br/investment-transactions/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/investment-transactions-brazil/destroyinvestmenttransactionbrazil.md): Excluir uma transação de investimento específica da sua conta Belvo. ## 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) ### Listar empregos - [GET /api/br/employments/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/employments-brazil/listemploymentsbrazil.md): ## ▶️ Uso Com o método List Employments, você pode: 1. [Obrigatório] Listar empregos relacionados a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um employment.id específico (usando o parâmetro de consulta id). ## 📖 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 do Belvo, consulte nosso artigo Dicas de Paginação. ## 🔦 Filtrando Respostas Consulte a lista de consultas abaixo para ver uma lista de campos pelos quais você pode filtrar suas respostas. Para mais informações sobre como usar filtros, consulte nosso artigo Filtrando respostas. ### Recuperar empregos para um link - [POST /api/br/employments/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/employments-brazil/retrieveemploymentsbrazil.md): Recuperar empregos de um link existente. ### Obter os detalhes de um emprego - [GET /api/br/employments/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/employments-brazil/detailemploymentbrazil.md): Obtenha os detalhes de um emprego específico. ### Excluir um emprego - [DELETE /api/br/employments/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/employments-brazil/destroyemploymentbrazil.md): Excluir um emprego específico da sua conta Belvo. ## 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) ### Listar registros de emprego - [GET /api/employment-records/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/employment-records-mexico/listemploymentrecords.md): ## ▶️ Uso Com o método Listar Registros de Emprego, você pode: 1. Listar registros de emprego relacionados a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um employment-record.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todos os registros de emprego 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. ### Recuperar detalhes do registro de emprego - [POST /api/employment-records/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/employment-records-mexico/retrieveemploymentrecorddetails.md): Recuperar detalhes do registro de emprego de um indivíduo. ### Obter os detalhes de um registro de emprego - [GET /api/employment-records/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/employment-records-mexico/detailemploymentrecord.md): Obtenha os detalhes de um registro de emprego específico. ### Excluir um registro de emprego - [DELETE /api/employment-records/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/employment-records-mexico/destroyemploymentrecord.md): Exclua um registro de emprego específico da sua conta Belvo. > ❗️ Limite de taxa > > Este endpoint tem limite de taxa. Você pode excluir apenas 5 itens por minuto. Se exceder esse limite, receberá um código de status 429. ## 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. ## Características Principais - **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) ### Listar empregos atuais - [GET /api/mx/current-employments/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/current-employments-mexico/listcurrentemployments.md): ## ▶️ Uso Com o método List Current Employments, você pode: 1. Listar empregos atuais relacionados a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um current-employment.id específico (usando o parâmetro de consulta id). 3. [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. ### Recuperar empregos atuais - [POST /api/mx/current-employments/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/current-employments-mexico/retrievecurrentemployments.md): Recuperar informações de emprego atuais para um link.id específico. ### Obter detalhes atuais de emprego - [GET /api/mx/current-employments/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/current-employments-mexico/getcurrentemploymentdetails.md): Obtenha os detalhes de um registro específico de emprego atual. ### Excluir emprego atual - [DELETE /api/mx/current-employments/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/current-employments-mexico/deletecurrentemployment.md): Exclua um registro específico de emprego atual da sua conta Belvo. ## Invoices ### Listar faturas - [GET /api/invoices/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/invoices/listinvoices.md): ## ▶️ Uso Com o método Listar Faturas, você pode: 1. Listar faturas relacionadas a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um invoice.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todas as faturas relacionadas à 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. ## 🚨 Campos Obsoletos Este recurso pode retornar campos obsoletos. Na documentação de resposta, você pode ver que um campo foi marcado como obsoleto. Isso significa que este campo não é mais mantido pela equipe da Belvo. Você ainda pode receber dados para este campo dependendo da instituição, no entanto, não deve confiar neste campo. ### Recuperar faturas para um link - [POST /api/invoices/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/invoices/retrieveinvoices.md): Recupere informações de faturas a partir de um link fiscal específico. > 📘 Informação > > Você pode solicitar até um ano (365 dias) de faturas por solicitação. Se precisar de faturas por mais de um ano, basta fazer outra solicitação. > 🚧 Aviso > > Este recurso pode retornar campos obsoletos. Por favor, verifique a documentação da resposta para mais informações. ### Concluir uma solicitação de faturas - [PATCH /api/invoices/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/invoices/patchinvoices.md): Usado para retomar uma sessão de recuperação de Fatura que foi pausada porque um token MFA foi exigido pela instituição. {% admonition type="info" %} Este recurso pode retornar campos obsoletos. Por favor, verifique a documentação da resposta para mais informações. {% /admonition %} ### Obter os detalhes de uma fatura - [GET /api/invoices/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/invoices/detailinvoice.md): Obtenha os detalhes de uma fatura específica. {% admonition type="info" %} Este recurso pode retornar campos obsoletos. Por favor, verifique a documentação da resposta para mais informações. {% /admonition %} ### Excluir uma fatura - [DELETE /api/invoices/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/invoices/destroyinvoice.md): Excluir uma fatura específica da sua conta Belvo. ## Tax compliance status ### Listar status de conformidade fiscal - [GET /api/tax-compliance-status/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-compliance-status/listtaxcompliancestatus.md): ## ▶️ Uso Com o método Listar Status de Conformidade Fiscal, você pode: 1. Listar status de conformidade fiscal relacionados a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um tax-compliance-status.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todos os status de conformidade fiscal 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, consulte nosso artigo Filtrando respostas. ### Recuperar status de conformidade fiscal para um link - [POST /api/tax-compliance-status/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-compliance-status/retrievetaxcompliancestatus.md): Recupere as informações de status de conformidade fiscal para um link fiscal específico. ### Obter os detalhes do status de conformidade fiscal - [GET /api/tax-compliance-status/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-compliance-status/detailtaxcompliancestatus.md): Obtenha os detalhes de um status específico de conformidade fiscal. ### Excluir um status de conformidade fiscal - [DELETE /api/tax-compliance-status/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-compliance-status/destroytaxcompliancestatus.md): Excluir um status de conformidade fiscal específico da sua conta Belvo. ## Tax returns ### Listar declarações de imposto de renda - [GET /api/tax-returns/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-returns/listtaxreturns.md): ## ▶️ Uso Com o método List Tax Returns, você pode: 1. Listar declarações de imposto relacionadas a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um tax-return.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todas as declarações de imposto relacionadas à 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. ## 🔔 Múltiplos Esquemas Como um link pode ter declarações de imposto anuais e mensais, a resposta incluirá uma mistura desses dois tipos de declarações de imposto (e, portanto, diferentes esquemas). ### Recuperar declarações de imposto para um link - [POST /api/tax-returns/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-returns/retrievetaxreturns.md): Recuperar informações da declaração de imposto para um link fiscal específico. ### Obter os detalhes de uma declaração de imposto de renda - [GET /api/tax-returns/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-returns/detailtaxreturn.md): Obtenha os detalhes de uma declaração de imposto específica. ### Excluir uma declaração de imposto - [DELETE /api/tax-returns/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-returns/destroytaxreturn.md): Excluir uma declaração de imposto específica da sua conta Belvo. ## Tax retentions ### Listar retenções de impostos - [GET /api/tax-retentions/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-retentions/listtaxretentions.md): ## ▶️ Uso Com o método List Tax Retentions, você pode: 1. Listar retenções de impostos relacionadas a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um tax-retention.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todas as retenções de impostos relacionadas à 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, consulte nosso artigo Filtrando respostas. ### Recuperar retenções de impostos para um link - [POST /api/tax-retentions/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-retentions/retrievetaxretentions.md): Recupere informações de retenção de impostos de um link específico. O número máximo de retenções de impostos que pode ser retornado para um período é 500. ### Obter os detalhes de uma retenção de imposto - [GET /api/tax-retentions/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-retentions/detailtaxretentions.md): Obtenha os detalhes de uma retenção de imposto específica. ### Excluir uma retenção de imposto - [DELETE /api/tax-retentions/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-retentions/destroytaxretention.md): Exclua uma retenção de imposto específica da sua conta Belvo. ## Tax status ### Listar status fiscais - [GET /api/tax-status/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-status/listtaxstatus.md): ## ▶️ Uso Com o método Listar Status de Impostos, você pode: 1. Listar status de impostos relacionados a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um tax-status.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todos os status de impostos 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. ### Recuperar status de impostos para um link - [POST /api/tax-status/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-status/retrievetaxstatus.md): Recuperar informações sobre o status fiscal para um link fiscal específico. ### Obter os detalhes de um status fiscal - [GET /api/tax-status/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-status/detailtaxstatus.md): Obtenha os detalhes de um status fiscal específico. ### Excluir um status de imposto - [DELETE /api/tax-status/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-status/destroytaxstatus.md): Excluir um status fiscal específico da sua conta Belvo. ## Financial Statements ### Listar Demonstrações Financeiras - [GET /api/financial-statements/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/financial-statements/listfinancialstatements.md): ## ▶️ Uso Com o método Listar Demonstrações Financeiras, você pode: 1. Listar demonstrações financeiras relacionadas a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um financial-statement.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todas as demonstrações financeiras relacionadas à 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, consulte nosso artigo Filtrando respostas. ### Recuperar Demonstrações Financeiras para um link - [POST /api/financial-statements/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/financial-statements/retrievefinancialstatements.md): Recupere as informações das Demonstrações Financeiras para um link fiscal específico. ### Obter detalhes de uma Demonstração Financeira - [GET /api/financial-statements/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/financial-statements/detailfinancialstatement.md): Obtenha os detalhes de um Demonstrativo Financeiro específico. ### Excluir uma Demonstração Financeira - [DELETE /api/financial-statements/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/financial-statements/destroyfinancialstatement.md): Excluir um Demonstrativo Financeiro específico da sua conta Belvo. ## Invoices Chile ### Listar faturas - [GET /api/cl/invoices/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/invoices-chile/listinvoiceschile.md): ## ▶️ Uso Com o método Listar Faturas, você pode: 1. Listar faturas relacionadas a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um invoice.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todas as faturas relacionadas à 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, consulte nosso artigo Filtrando respostas. ### Recuperar faturas para um link - [POST /api/cl/invoices/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/invoices-chile/retrieveinvoiceschile.md): Recuperar informações de faturas de um link fiscal específico do Chile. Você pode solicitar até um ano (365 dias) de faturas por solicitação. Se precisar de faturas por mais de um ano, basta fazer outra solicitação. > 📘 Altamente Recomendado > > Recomendamos fortemente que você use o parâmetro de cabeçalho X-Belvo-Request-Mode da Belvo e implemente um fluxo de trabalho assíncrono. Isso garantirá que você não receba erros de timeout ao recuperar dados de faturas. ### Obter os detalhes de uma fatura - [GET /api/cl/invoices/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/invoices-chile/detailinvoicechile.md): Obtenha os detalhes de uma fatura específica. ### Excluir uma fatura - [DELETE /api/cl/invoices/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/invoices-chile/destroyinvoicechile.md): Excluir uma fatura específica da sua conta Belvo. ## Tax Status Chile ### Listar status fiscais - [GET /api/cl/tax-status/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-status-chile/listtaxstatuschile.md): ## ▶️ Uso Com o método Tax Status, você pode: 1. Listar status fiscais relacionados a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um tax-status.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todos os status fiscais 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, consulte nosso artigo Filtrando respostas. ### Recuperar status de impostos para um link - [POST /api/cl/tax-status/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-status-chile/retrievetaxstatuschile.md): Recuperar informações sobre o status fiscal para um link fiscal específico. ### Obter os detalhes de um status fiscal - [GET /api/cl/tax-status/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-status-chile/detailtaxstatuschile.md): Obtenha os detalhes de um status fiscal específico. ### Excluir um status de imposto - [DELETE /api/cl/tax-status/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/tax-status-chile/destroytaxstatuschile.md): Excluir um status fiscal específico da sua conta Belvo. ## Debt Reports Chile ### Listar relatórios de dívidas - [GET /api/cl/debt-reports/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/debt-reports-chile/listdebtreportchile.md): ## ▶️ Uso Com o método Listar Relatórios de Dívida, você pode: 1. Listar relatórios de dívida relacionados a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um debt-report.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todos os relatórios de dívida 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. ### Recuperar detalhes da dívida para um link - [POST /api/cl/debt-reports/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/debt-reports-chile/retrievedebtreportchile.md): Recuperar informações de relatórios de dívida para um link fiscal específico. ### Obter os detalhes de uma dívida - [GET /api/cl/debt-reports/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/debt-reports-chile/detaildebtreportchile.md): Obtenha os detalhes de uma dívida específica. ### Excluir um relatório de dívida - [DELETE /api/cl/debt-reports/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/debt-reports-chile/destroydebtreportchile.md): Excluir um relatório de dívida específico da sua conta Belvo. ## 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. ### Listar rendimentos - [GET /api/incomes/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/incomes/listincomes.md): ## ▶️ Uso Com o método List Incomes, você pode: 1. Listar rendas relacionadas a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de uma income.id específica (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todas as rendas relacionadas à sua conta Belvo (sem usar nenhum parâmetro de consulta). ## 📖 Paginação Este método retorna uma resposta paginada (padrão: 100 itens por página). Você pode usar o parâmetro de consulta page_size para aumentar o número de itens retornados até um máximo de 1000 itens. Você pode usar o parâmetro de consulta page para navegar pelos resultados. Para mais detalhes sobre como navegar nas respostas paginadas da Belvo, consulte nosso artigo Dicas de Paginação. ## 🔦 Filtrando Respostas Consulte a lista de consultas abaixo para ver uma lista de campos pelos quais você pode filtrar suas respostas. Para mais informações sobre como usar filtros, consulte nosso artigo Filtrando respostas. ### Recuperar rendimentos para um link - [POST /api/incomes/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/incomes/retrieveincome.md): Recupere insights de renda para contas correntes e poupança a partir de um link específico. Você pode receber insights para um período de até 365 dias, dependendo do histórico de transações disponível para cada instituição. ### Obter detalhes de uma renda - [GET /api/incomes/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/incomes/detailincome.md): Obtenha os detalhes de uma renda específica. ### Excluir uma receita - [DELETE /api/incomes/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/incomes/destroyincomes.md): Exclua uma renda específica da sua conta Belvo. ## 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. ### Listar despesas recorrentes - [GET /api/recurring-expenses/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/recurring-expenses/listrecurringexpenses.md): ## ▶️ Uso Com o método Listar Despesas Recorrentes, você pode: 1. Listar despesas recorrentes relacionadas a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um recurring-expense.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todas as despesas recorrentes relacionadas à 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, consulte nosso artigo Filtrando respostas. ### Recuperar despesas recorrentes para um link - [POST /api/recurring-expenses/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/recurring-expenses/retrieverecurringexpenses.md): Recupere insights de despesas recorrentes para contas correntes e de poupança a partir de um link específico. Você pode receber insights para um período de até 365 dias, dependendo do histórico de transações disponível para cada instituição. ### Obter os detalhes de uma despesa recorrente - [GET /api/recurring-expenses/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/recurring-expenses/detailrecurringexpense.md): Obtenha os detalhes de uma despesa recorrente específica. ### Excluir uma despesa recorrente - [DELETE /api/recurring-expenses/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/recurring-expenses/destroyrecurringexpense.md): Excluir uma despesa recorrente específica da sua conta Belvo. ## Risk Insights ### Listar insights de risco - [GET /api/risk-insights/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/risk-insights/listriskinsights.md): ## ▶️ Uso Com o método List Risk Insights, você pode: 1. Listar insights de risco relacionados a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um risk-insight.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todos os insights de risco 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. ### Recuperar insights de risco para um link - [POST /api/risk-insights/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/risk-insights/retrieveriskinsights.md): Solicite as informações de risco para um determinado ID de link. Se você precisar saber a moeda da conta, basta fazer um GET Details no endpoint de contas (usando o ID que você recebe da resposta das contas). ### Obter detalhes de uma análise de risco - [GET /api/risk-insights/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/risk-insights/detailriskinsights.md): Obtenha os detalhes de uma percepção de risco específica. ### Excluir uma análise de risco - [DELETE /api/risk-insights/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/risk-insights/destroyriskinsights.md): Excluir uma análise de risco específica da sua conta Belvo. ## Employment Metrics ### Listar métricas de emprego - [GET /api/employment-metrics/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/employment-metrics/listemploymentmetrics.md): ## ▶️ Uso Com o método Listar Métricas de Emprego, você pode: 1. Listar métricas de emprego relacionadas a um link.id específico (usando o parâmetro de consulta link). 2. Obter os detalhes de um employment-metric.id específico (usando o parâmetro de consulta id). 3. [Não Recomendado] Listar todas as métricas de emprego relacionadas à 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, consulte nosso artigo Filtrando respostas. ### Recuperar métricas de emprego - [POST /api/employment-metrics/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/employment-metrics/retrieveemploymentmetricdetails.md): Recuperar métricas de emprego para um indivíduo. > Nota: Antes de solicitar métricas de emprego, certifique-se de primeiro fazer uma solicitação POST Retrieve employment record details. ### Obter detalhes de uma métrica de emprego - [GET /api/employment-metrics/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/employment-metrics/detailemploymentmetric.md): Obtenha os detalhes de uma métrica de emprego específica. ### Excluir uma métrica de emprego - [DELETE /api/employment-metrics/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/employment-metrics/destroyemploymentmetric.md): Excluir uma métrica de emprego específica da sua conta Belvo. ## 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. ### Liste todas as instituições de pagamento - [GET /payments/br/institutions/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-institutions-(brazil)/listpaymentinstitutionsbrazil.md): Liste todas as instituições de pagamento disponíveis. ## 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. {% admonition type="info" name="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. {% /admonition %} ### Criar um novo cliente - [POST /payments/br/customers/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/customers-(brazil)/createcustomerbrazil.md): Crie um novo cliente para enviar ou solicitar fundos. ### Listar todos os clientes - [GET /payments/br/customers/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/customers-(brazil)/listcustomersbrazil.md): Liste todos os clientes associados à sua conta Belvo. ### Obter detalhes sobre um cliente - [GET /payments/br/customers/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/customers-(brazil)/detailcustomerbrazil.md): Obter os detalhes sobre um cliente específico ## 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). {% admonition type="info" name="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. {% /admonition %} ### Registrar uma nova conta bancária - [POST /payments/br/bank-accounts/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/bank-accounts-(brazil)/registerbankaccountbrazil.md): Registre uma nova conta bancária da qual você pode enviar ou solicitar fundos. ### Listar todas as contas bancárias - [GET /payments/br/bank-accounts/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/bank-accounts-(brazil)/listbankaccountbrazil.md): Liste todas as contas bancárias associadas à sua conta Belvo. ### Ativar ou desativar uma conta bancária - [PATCH /payments/br/bank-accounts/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/bank-accounts-(brazil)/patchbankaccountbrazil.md): Atualiza se uma conta bancária está ativa definindo active como true ou false. Definir active como false desativa a conta bancária identificada no caminho. Contas desativadas são ignoradas para verificações de duplicidade na mesma instituição, agência e número de conta, o que permite registrar uma nova conta bancária com os mesmos dados bancários quando for necessário corrigir informações incorretas do titular (como nome ou CPF/CNPJ) ou erros semelhantes de um registro inicial. ### Obter detalhes sobre uma conta bancária - [GET /payments/br/bank-accounts/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/bank-accounts-(brazil)/detailbankaccountbrazil.md): Obtenha os detalhes sobre uma conta bancária específica. ## 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. {% admonition type="info" name="O que é uma cobrança?" %} Uma **cobrança** representa o pagamento individual (débito) que seu cliente fará. {% /admonition %} {% admonition type="danger" name="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`. {% /admonition %} ### Criar uma nova Autorização de Pagamento - [POST /payments/br/payment-authorizations/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-authorizations-(brazil)/createpaymentauthorizationbrazil.md): {% admonition type="warning" name="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. {% /admonition %} Crie uma Autorização de Pagamento. ### Listar todas as Autorizações de Pagamento - [GET /payments/br/payment-authorizations/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-authorizations-(brazil)/listpaymentauthorizationsbrazil.md): {% admonition type="warning" name="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 Belvo. {% /admonition %} Liste todas as Autorizações de Pagamento associadas à sua conta Belvo. ### Obter detalhes sobre uma Autorização de Pagamento - [GET /payments/br/payment-authorizations/{payment_authorization_id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-authorizations-(brazil)/detailpaymentauthorizationbrazil.md): {% admonition type="warning" name="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. {% /admonition %} Obtenha os detalhes sobre uma Autorização de Pagamento específica. ### Cancelar uma Autorização de Pagamento - [POST /payments/br/payment-authorizations/{payment_authorization_id}/cancel/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-authorizations-(brazil)/cancelpaymentauthorizationbrazil.md): {% admonition type="warning" name="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. {% /admonition %} Cancelar uma Autorização de Pagamento Respondemos com um 204 - No Content e informaremos você via webhook que a Autorização de Pagamento foi cancelada com sucesso. {% admonition type="warning" name="Restrições de Horário para Cancelamento" %} O horário limite para cancelar uma Autorização de Pagamento é até as 22:00:00 (GMT-3) do dia anterior à próxima data de Cobrança. Se você perder o prazo, a Autorização de Pagamento será cancelada, mas a Cobrança ainda será processada. {% /admonition %} ### Listar todas as Cobranças para uma Autorização de Pagamento - [GET /payments/br/payment-authorizations/{payment_authorization_id}/charges/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-authorizations-(brazil)/listpaymentauthorizationchargesbrazil.md): {% admonition type="warning" name="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. {% /admonition %} Liste todas as Cobranças associadas a uma Autorização de Pagamento. ### Obter detalhes sobre uma Cobrança para uma Autorização de Pagamento - [GET /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-authorizations-(brazil)/detailpaymentauthorizationchargebrazil.md): {% admonition type="warning" name="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 Belvo. {% /admonition %} Obtenha os detalhes sobre uma Charge específica associada a uma Payment Authorization. ### Tentar novamente uma Cobrança falhada para uma Autorização de Pagamento - [POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/retry/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-authorizations-(brazil)/retrypaymentauthorizationchargebrazil.md): {% admonition type="warning" name="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. {% /admonition %} Tente novamente uma Cobrança falhada para uma determinada Autorização de Pagamento. {% admonition type="warning" name="Documentação adicional" %} Certifique-se de ler a documentação dedicada a Repetição de Cobranças e Cobranças Vinculadas antes de tentar repetir uma cobrança. {% /admonition %} ### Cancelar uma Cobrança agendada - [POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/cancel/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-authorizations-(brazil)/cancelpaymentauthorizationchargebrazil.md): {% admonition type="warning" name="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. {% /admonition %} Cancele uma Cobrança agendada. Respondemos com um 204 - No Content e informaremos você via webhook que a cobrança foi cancelada com sucesso. {% admonition type="warning" name="Restrição de Tempo para Cancelamento" %} O horário limite para cancelar uma Cobrança agendada é até as 22:00:00 (GMT-3) do dia anterior à data da Cobrança. Se você perder o prazo, receberá um erro de API da Belvo e o pagamento será processado. {% /admonition %} ## Charges (Brazil) Você pode usar o recurso Charges para obter detalhes sobre uma única cobrança ou listar todas as cobranças associadas a uma intenção de pagamento. ### Listar todas as cobranças - [GET /payments/br/charges/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/charges-(brazil)/listallchargesbrazil.md): Liste todas as cobranças relacionadas à sua conta. ### Obter detalhes sobre uma Charge - [GET /payments/br/charges/{charge_id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/charges-(brazil)/detailchargebrazil.md): Obtenha os detalhes sobre uma Charge específica. ## 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. ### Criar uma nova Payment Intent - [POST /payments/br/payment-intents/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-intents-(brazil)/createpaymentintentbrazil.md): Criar uma Intenção de Pagamento. Você pode criar uma Intenção de Pagamento nas seguintes configurações: |Beneficiário|Cliente (Pagador)|Exemplo| |---|---|---| |Chave Pix|Já registrado no Belvo|Chave Pix (Com Cliente Existente)| |Chave Pix|Registrar no Belvo no momento da solicitação da Intenção de Pagamento|Chave Pix (Com Novo Cliente)| |Conta Bancária (Já Registrada)|Já Registrado|Conta Bancária (Com Cliente Existente)| |Conta Bancária (Já Registrada)|Registrar no Belvo no momento da solicitação da Intenção de Pagamento|Conta Bancária (Com Novo Cliente)| |Conta Bancária (Registrar no momento da solicitação da Intenção de Pagamento)|Registrar no Belvo no momento da solicitação da Intenção de Pagamento|Conta Bancária (Com Novo Cliente e Conta Bancária do Beneficiário)| {% admonition type="warning" name="Pagamentos Pix" %} Quando você cria Intenções de Pagamento usando uma Chave Pix, é necessário fazer uma solicitação PATCH Complete a Payment Intent para completar a criação da Intenção de Pagamento. {% /admonition %} ### Listar todas as payment intents - [GET /payments/br/payment-intents/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-intents-(brazil)/listpaymentintentsbrazil.md): Liste todas as intenções de pagamento associadas à sua conta Belvo. ### Concluir uma intenção de pagamento - [PATCH /payments/br/payment-intents/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-intents-(brazil)/patchpaymentintentbrazil.md): Concluir uma nova intenção de pagamento. ### Obter detalhes sobre uma intenção de pagamento - [GET /payments/br/payment-intents/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-intents-(brazil)/detailpaymentintentbrazil.md): Obtenha os detalhes sobre uma intenção de pagamento específica. ### Cancelar uma intenção de pagamento agendada - [POST /payments/br/payment-intents/{id}/cancel/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-intents-(brazil)/cancelpaymentintentbrazil.md): Cancelar uma intenção de pagamento agendada (única). Respondemos com um 204 - No Content e informaremos você via webhook que a intenção de pagamento foi cancelada com sucesso. > Nota: O prazo máximo para cancelar uma intenção de pagamento agendada é até 23:59:00 (GMT-3) do dia anterior à data de pagamento agendada. ### Liste todas as cobranças para uma intenção de pagamento - [GET /payments/br/payment-intents/{payment_intent_id}/charges/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-intents-(brazil)/listchargesbrazil.md): Liste todas as cobranças associadas a uma intenção de pagamento. ### Obter detalhes sobre uma cobrança para uma intenção de pagamento - [GET /payments/br/payment-intents/{payment_intent_id}/charges/{charge_id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-intents-(brazil)/detailchargesbrazil.md): Obtenha os detalhes sobre uma cobrança específica associada a uma intenção de pagamento. ### Cancelar uma cobrança agendada - [POST /payments/br/payment-intents/{payment_intent_id}/charges/{charge_id}/cancel/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-intents-(brazil)/cancelchargebrazil.md): Cancelar uma cobrança agendada. Respondemos com um 204 - No Content e informaremos você via webhook que a cobrança foi cancelada com sucesso. > Nota: O prazo máximo para cancelar uma cobrança agendada é até 23:59:00 (GMT-3) do dia anterior à data de pagamento agendada. ## 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. ### Gerar um token de acesso para o widget de pagamento - [POST /payments/br/token/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/biometric-pix-widget-access-token-(brazil)/generatepaymentwidgetaccesstoken.md): Gerar um token de acesso para o widget de pagamento para o processo de cadastro ou pagamento com Pix Biométrico. ## Enrollments (Brazil) ### Registrar um novo dispositivo de usuário - [POST /payments/br/enrollments/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/enrollments-(brazil)/createenrollmentbrazil.md): ## ▶️ Uso Com o método Enroll a new user device, você pode iniciar o processo de registro de um novo dispositivo para permitir pagamentos com Biometric Pix. > 🚧 Crie um cliente primeiro > > Antes de registrar um dispositivo de usuário, você deve primeiro criar um cliente. ### Listar matrículas - [GET /payments/br/enrollments/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/enrollments-(brazil)/listenrollmentsbrazil.md): ## ▶️ Uso Com o método List Enrollments, você pode: 1. (Recomendado) Listar inscrições relacionadas a um CPF específico (usando o parâmetro de consulta customer__identifier). 2. Listar inscrições relacionadas a um customer.id e institution.id específicos (usando os parâmetros de consulta customer e institution). 3. Listar inscrições de acordo com um status específico (usando o parâmetro de consulta status). 4. [Não Recomendado] Listar todas as inscrições relacionadas à sua conta Belvo (sem usar nenhum parâmetro de consulta). ## 🔦 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 para 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. ### Obter detalhes sobre uma inscrição - [GET /payments/br/enrollments/{enrollment_id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/enrollments-(brazil)/detailenrollmentbrazil.md): Obtenha detalhes sobre um registro específico de dispositivo. ### Concluir inscrição após redirecionamento - [POST /payments/br/enrollments/complete-redirection/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/enrollments-(brazil)/completeenrollmentredirectionbrazil.md): ## ▶️ Uso Use este endpoint para concluir o processo de inscrição após o usuário ser redirecionado de volta da instituição. O corpo da solicitação deve corresponder aos parâmetros recebidos na URL de callback, seja para um callback de sucesso ou de erro. ## 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. ### Listar todas as transações de pagamento - [GET /payments/br/transactions/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-transactions-(brazil)/listpaymenttransactionsbrazil.md): Liste todas as transações de pagamento associadas à sua conta Belvo. ### Obter detalhes sobre uma transação de pagamento - [GET /payments/br/transactions/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/payment-transactions-(brazil)/detailpaymenttransactionsbrazil.md): Obtenha os detalhes sobre uma transação de pagamento específica.