# Listar saldos

## ▶️ 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.

Endpoint: GET /api/br/balances/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `link` (string, required)
    O link.id pelo qual você deseja filtrar.
    Example: "8848bd0c-9c7e-4f53-a732-ec896b11d4c4"

  - `account` (string)
    O account.id pelo qual você deseja filtrar.

ℹ️ Recomendamos fortemente adicionar os filtros link.id ou account.id para melhorar seu desempenho.
    Example: "8848bd0c-9c7e-4f53-a732-ec896b11d4c4"

  - `id` (string)
    Retorne informações apenas para este recurso id.
    Example: "24ccab1d-3a86-4136-a6eb-e04bf52b356f"

  - `link__in` (array)
    Retorne resultados apenas para esses link.ids.
    Example: ["5722d0ba-69d7-42dc-8ff5-33767b83c5d6"]

  - `account__in` (array)
    Retorne resultados apenas para esses account.ids.
    Example: ["85b77707-90ef-46fd-9059-5a757f24247a"]

  - `id__in` (array)
    Retorne informações para esses ids de recurso.
    Example: ["6b3dea0f-be29-49d1-aabe-1a6d588642e6"]

  - `page_size` (integer)
    Indica quantos resultados retornar por página. Por padrão, retornamos 100 resultados por página.

ℹ️ O número mínimo de resultados retornados por página é 1 e o máximo é 1000. Se você inserir um valor maior que 1000, nossa API usará o valor máximo por padrão (1000).
    Example: 100

  - `page` (integer)
    Um número de página dentro do conjunto de resultados paginados.
    Example: 1

  - `omit` (string)
    Omitir certos campos de serem retornados na resposta. Para mais informações, consulte nosso artigo Filtrando respostas no DevPortal.

  - `fields` (string)
    Retorne apenas os campos especificados na resposta. Para mais informações, consulte nosso artigo no DevPortal Filtrando respostas.

  - `collected_at` (string)
    Retorne itens que foram recuperados da instituição nesta data (YYYY-MM-DD ou timestamp completo ISO-8601).
    Example: "2022-05-01"

  - `collected_at__gt` (string)
    Retorne itens que foram recuperados da instituição após esta data (YYYY-MM-DD ou timestamp completo ISO-8601).
    Example: "2022-05-05"

  - `collected_at__gte` (string)
    Retorne itens que foram recuperados da instituição após ou nesta data (YYYY-MM-DD ou timestamp completo ISO-8601).
    Example: "2022-05-04"

  - `collected_at__lt` (string)
    Retorne itens que foram recuperados da instituição antes desta data (YYYY-MM-DD ou timestamp completo ISO-8601).
    Example: "2022-04-01"

  - `collected_at__lte` (string)
    Retorne itens que foram recuperados da instituição antes ou nesta data (YYYY-MM-DD ou timestamp completo ISO-8601).
    Example: "2022-03-30"

  - `collected_at__range` (array)
    Retorne itens que foram recuperados da instituição entre duas datas (YYYY-MM-DD ou timestamp completo ISO-8601). O primeiro valor indica o início do intervalo e o segundo valor indica o final do intervalo.
    Example: ["2022-01-01","2022-12-31"]

  - `created_at` (string)
    Retorne itens que foram atualizados pela última vez no banco de dados da Belvo nesta data (no formato YYYY-MM-DD).
    Example: "2022-05-05"

  - `created_at__gt` (string)
    Retorne itens que foram atualizados pela última vez no banco de dados da Belvo após esta data (no formato YYYY-MM-DD).
    Example: "2022-05-05"

  - `created_at__gte` (string)
    Retorne itens que foram atualizados pela última vez no banco de dados da Belvo após ou nesta data (no formato YYYY-MM-DD).
    Example: "2022-05-04"

  - `created_at__lt` (string)
    Retorne itens que foram atualizados pela última vez no banco de dados da Belvo antes desta data (no formato YYYY-MM-DD).
    Example: "2022-04-01"

  - `created_at__lte` (string)
    Retorne itens que foram atualizados pela última vez no banco de dados da Belvo antes ou na data especificada (no formato YYYY-MM-DD).
    Example: "2022-03-30"

  - `created_at__range` (array)
    Retorne contas que foram atualizadas pela última vez no banco de dados do Belvo entre duas datas (no formato YYYY-MM-DD). O primeiro valor indica o início do intervalo e o segundo valor indica o final do intervalo.
    Example: ["2022-01-01","2022-12-31"]

## Response 200 fields (application/json):

  - `count` (integer)
    O número total de resultados na sua conta Belvo.
    Example: 130

  - `next` (string,null)
    A URL para a próxima página de resultados. Cada página consiste em até 100 itens. Se não houver resultados suficientes para uma página adicional, o valor será null.

Em nosso exemplo de documentação, usamos {endpoint} como um valor de espaço reservado. Em produção, esse valor será substituído pelo endpoint real que você está usando atualmente (por exemplo, accounts ou owners).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908&page=2"

  - `previous` (string,null)
    A URL para a página anterior de resultados. Se não houver uma página anterior, o valor será null.

  - `results` (array)
    Um array de objetos balance.

  - `results.id` (string, required)
    O identificador único criado pela Belvo usado para referenciar o saldo atual.
    Example: "0b94bdf9-3719-43a9-81e7-be95d2318595"

  - `results.link` (string, required)
    O identificador único do link ao qual este saldo pertence.
    Example: "0b94bdf9-3719-43a9-81e7-be95d2318595"

  - `results.account_id` (string, required)
    O account.id do Belvo ao qual este saldo pertence.
    Example: "c4bfecf9-4eb6-4920-9f9f-e1f1e60ef321"

  - `results.account_internal_identification` (string, required)
    A identificação interna da instituição para a conta.
    Example: "92792126019929279212650822221989319252576"

  - `results.collected_at` (string, required)
    O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.
    Example: "2024-05-21T08:32:00Z"

  - `results.created_at` (string, required)
    O carimbo de data/hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo.
    Example: "2024-05-21T08:32:00Z"

  - `results.last_updated_at` (string, required)
    O carimbo de data/hora ISO-8601 de quando este saldo foi atualizado pela última vez pela instituição.

> 🚧 Aviso
>
> O parâmetro last_updated_at depende de como a instituição processa (ou armazena) os dados. No caso de a instituição armazenar dados de forma síncrona (ou seja, assim que uma transação ocorre, o saldo é atualizado), então o last_updated_at refletirá o saldo em tempo quase real. No caso de a instituição armazenar dados de forma assíncrona (ou seja, ela recupera dados em lote e depois atualiza o saldo), as informações de saldo podem se referir a horas ou dias atrás. Além disso, no caso de a instituição não conseguir fornecer o horário específico (devido a um erro interno), a instituição pode fornecer um horário geral em que atualizou pela última vez as informações da conta e do saldo.
    Example: "2021-05-21T08:30:00Z"

  - `results.currency` (string, required)
    O código de moeda de três letras (ISO-4217).
    Example: "USD"

  - `results.available` (number, required)
    O saldo disponível da conta.
    Example: 1000.02

  - `results.blocked` (number, required)
    O valor que está atualmente bloqueado devido, por exemplo, a transações pendentes.
    Example: 1000.02

  - `results.automatically_invested` (number, required)
    O valor que é automaticamente investido (conforme acordado com a instituição).
    Example: 1000.02

  - `results.reserved_balances` (array, required)
    The account's reserves (for example, caixinhas or cofrinhos): money the account holder has set aside inside the account, with or without yield. Reserves that are investments registered to the account holder are not included here and are returned by the investments endpoints instead.

An empty list ([]) means that the institution reported no reserves for the account, or that they could not be retrieved.

  - `results.reserved_balances.name` (string,null)
    The name the account holder gave to the reserve.
    Example: "Cofrinho"

  - `results.reserved_balances.identification` (string,null)
    The institution's unique identifier for the reserve.
    Example: "d78fc4e5-37ca-4da3-adf2-9b082bf92280"

  - `results.reserved_balances.amounts` (array,null)
    The amounts held in the reserve. Usually a single BRL amount.

  - `results.reserved_balances.amounts.amount` (number,null)
    The amount available in the reserve.
    Example: 1565.51

  - `results.reserved_balances.amounts.currency` (string,null)
    O código de moeda de três letras (ISO-4217).
    Example: "BRL"

  - `results.reserved_balances.amounts.remuneration` (object,null)
    The yield applied to the reserved amount, as reported by the institution. null when the reserve has no yield.

  - `results.reserved_balances.amounts.remuneration.pre_fixed_rate` (number,null)
    The pre-fixed rate applied to the reserve, expressed as a decimal (for example, 0.145 represents 14.5%).

Returned when post_fixed_rate is not.

  - `results.reserved_balances.amounts.remuneration.post_fixed_rate` (number,null)
    The percentage of the indexer applied to the reserve, expressed as a decimal (for example, 1.2 represents 120% of the CDI).

Returned when pre_fixed_rate is not.
    Example: 1.2

  - `results.reserved_balances.amounts.remuneration.rate_type` (string,null)
    The type of remuneration rate. Can be either:
  - LINEAR
  - EXPONENCIAL
    Example: "LINEAR"

  - `results.reserved_balances.amounts.remuneration.rate_periodicity` (string,null)
    The frequency that the remuneration rate is applied. Can be either:
  - DIARIO
  - MENSAL
  - ANUAL
  - SEMESTRAL
    Example: "ANUAL"

  - `results.reserved_balances.amounts.remuneration.calculation_base` (string,null)
    Indicates whether the remuneration is calculated over business days (dias úteis) or calendar days (dias corridos). Can be either:
  - DIAS_UTEIS
  - DIAS_CORRIDOS
    Example: "DIAS_UTEIS"

  - `results.reserved_balances.amounts.remuneration.indexer` (string,null)
    The index used as a reference for the remuneration. Can be either:
  - CDI
  - DI
  - TR
  - IPCA
  - IGP_M
  - IGP_DI
  - INPC
  - BCP
  - TLC
  - SELIC
  - PRE_FIXADO
  - OUTROS
    Example: "CDI"

  - `results.reserved_balances.amounts.remuneration.indexer_additional_info` (string,null)
    Additional information about the indexer. Returned when indexer is OUTROS.

## Response 403 fields (application/json):

  - `code` (string)
    Um código de erro único (access_to_resource_denied) que permite classificar e tratar o erro programaticamente.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    Uma breve descrição do erro.

Para erros access_to_resource_denied, a descrição é:

  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    Um código de erro único (request_timeout) que permite classificar e lidar com o erro programaticamente.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 408 request_timeout.
    Example: "request_timeout"

  - `message` (string)
    Uma breve descrição do erro.

Para erros de request_timeout, a descrição é:

  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    Um código de erro único (unexpected_error) que permite classificar e tratar o erro de forma programática.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 500 unexpected_error.
    Example: "unexpected_error"

  - `message` (string)
    Uma breve descrição do erro.

Para erros unexpected_error, a descrição é:

  - Belvo não consegue processar a solicitação devido a um problema interno do sistema ou a uma resposta não suportada de uma instituição.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"