# Recuperar o saldo atual de um link

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.

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

## Query parameters:

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

## Request fields (application/json):

  - `link` (string, required)
    O link.id para o qual você deseja recuperar informações.
    Example: "c81a1dea-6dd6-4999-8b9f-541ee8197058"

  - `account_id` (string)
    O account.id do Belvo para o qual você deseja recuperar informações.
    Example: "e2cdb621-f44a-4558-89f6-8ab2a57add7a"

  - `save_data` (boolean)
    Indica se os dados devem ou não ser persistidos no Belvo. Por padrão, isso é definido como true e retornamos uma resposta 201 Created.

Quando definido como false, os dados não serão persistidos e retornamos uma resposta 200 OK.
    Example: true

## Response 200 fields (application/json):

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

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

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

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

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

  - `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"

  - `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"

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

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

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

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

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

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

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

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

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

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

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

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

  - `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

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

  - `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"

  - `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"

  - `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"

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

## Response 201 fields (application/json):

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

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

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

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

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

  - `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"

  - `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"

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

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

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

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

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

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

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

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

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

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

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

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

  - `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

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

  - `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"

  - `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"

  - `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"

  - `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 428 fields (application/json):

  - `code` (string)
    Um código de erro único (token_required) que permite classificar e lidar com o erro programaticamente.
ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 428 token_required.
    Example: "token_required"

  - `message` (string)
    Uma breve descrição do erro. Para erros token_required, a descrição é:

- A instituição requer um token MFA para fazer login.
    Example: "A MFA token is required by the institution to login"

  - `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"

  - `session` (string)
    Um ID único de 32 caracteres da sessão de login (correspondente a um padrão regex de: [a-f0-9]{32}).
    Example: "2675b703b9d4451f8d4861a3eee54449"

  - `expiry` (integer)
    Tempo de duração da sessão em segundos.
    Example: 9600

  - `link` (string)
    Identificador único criado pela Belvo, usado para referenciar o Link atual.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

  - `token_generation_data` (object)
    Detalhes sobre como gerar o token.

  - `token_generation_data.instructions` (string)
    Instruções para geração de token.
    Example: "Use this code to generate the token"

  - `token_generation_data.type` (string)
    Tipo de dados para gerar o token (QR code, desafio numérico).
    Example: "numeric"

  - `token_generation_data.value` (string)
    Valor a ser usado para gerar o token.
    Example: "12345"

  - `token_generation_data.expects_user_input` (boolean)
    Indica se o usuário precisa fornecer entrada para concluir a autenticação. Quando definido como false, seu usuário pode precisar:
- confirmar o login em outro dispositivo
- escanear um código QR
Você ainda precisará fazer uma chamada PATCH para concluir a solicitação.
    Example: true

## 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"