Consultar Saldo

Visão Geral

O endpoint GET /accounts/balances retorna o saldo da conta autenticada no formato compatível com a especificação do Banco Central.

Endpoint

GET /accounts/balances

Autenticação

Authorization

string

required

Token Bearer obtido via /oauth/token.

Request

curl -X GET https://api.avista.global/accounts/balances \
  -H "Authorization: Bearer <token>"

Response

200 OK
401 Unauthorized

{
  "data": [
    {
      "eventDate": "2025-01-15T10:30:00.000Z",
      "balanceAmount": {
        "available": 48734.90,
        "blocked": 1500.00,
        "overdraft": 0
      }
    }
  ]
}

{
  "statusCode": 401,
  "message": "Token não fornecido ou inválido",
  "error": "Unauthorized"
}

Campos da Resposta

data

array

Lista de saldos. Atualmente retorna apenas um item.

Show Item

eventDate

string

Data e hora da consulta (ISO 8601).

balanceAmount

object

Valores do saldo.

Show Propriedades

available

number

Saldo disponível para uso imediato. Já desconta valores bloqueados.

blocked

number

Saldo bloqueado. Valores reservados para operações pendentes (ex: PIX Out em processamento).

overdraft

number

Limite de crédito (cheque especial). Atualmente sempre 0.

Tipos de Saldo

Tipo	Descrição
available	Saldo que pode ser usado imediatamente para transferências
blocked	Valores reservados para operações em processamento
overdraft	Limite de crédito adicional (não implementado)

Cálculo do Saldo Total

saldoTotal = available + blocked

O saldo available já desconta os valores blocked.

Comparação com API Padrão

API Padrão (`GET /balance`)	API BACEN (`GET /accounts/balances`)
`grossBalance`	`available + blocked`
`blockedBalance`	`blocked`
`netBalance`	`available`
`consultedAt`	`eventDate`

Exemplo de Equivalência

// API Padrão
{
  "grossBalance": 50234.90,
  "blockedBalance": 1500.00,
  "netBalance": 48734.90,
  "consultedAt": "2025-01-15T10:30:00.000Z"
}

// API BACEN (equivalente)
{
  "data": [{
    "eventDate": "2025-01-15T10:30:00.000Z",
    "balanceAmount": {
      "available": 48734.90,   // = netBalance
      "blocked": 1500.00,       // = blockedBalance
      "overdraft": 0
    }
  }]
}

Fluxo de Saldo em Operações

PIX Out (Transferência)

PIX In (Recebimento)

Boas Práticas

Consulte antes de transferir

Sempre verifique o saldo disponível antes de iniciar uma transferência para evitar erros de saldo insuficiente.

async function transferir(valor: number) {
  const balance = await getBalance();
  const disponivel = balance.data[0].balanceAmount.available;

  if (valor > disponivel) {
    throw new Error(`Saldo insuficiente. Disponível: ${disponivel}`);
  }

  return await createTransfer(valor);
}

Considere valores bloqueados

O saldo blocked representa operações em andamento. Em caso de falha, esse valor retorna para available.

Cache com TTL curto

Se precisar cachear o saldo, use TTL curto (ex: 5-10 segundos) para manter valores atualizados.

Erros Comuns

Código	Erro	Solução
401	Token não fornecido	Inclua header `Authorization: Bearer <token>`
401	Token inválido	Verifique se o token está correto
401	Token expirado	Obtenha novo token via `/oauth/token`

Introdução

Endpoints

Webhooks V2

Visão Geral

Endpoint

Autenticação

Request

Response

Campos da Resposta

Tipos de Saldo

Cálculo do Saldo Total

Comparação com API Padrão

Exemplo de Equivalência

Fluxo de Saldo em Operações

PIX Out (Transferência)

PIX In (Recebimento)

Boas Práticas

Erros Comuns

Próximos Passos

Criar Cobrança

Transferir PIX

Introdução

Endpoints

Webhooks V2

​Visão Geral

​Endpoint

​Autenticação

​Request

​Response

​Campos da Resposta

​Tipos de Saldo

​Cálculo do Saldo Total

​Comparação com API Padrão

​Exemplo de Equivalência

​Fluxo de Saldo em Operações

​PIX Out (Transferência)

​PIX In (Recebimento)

​Boas Práticas

​Erros Comuns

​Próximos Passos

Criar Cobrança

Transferir PIX

Visão Geral

Endpoint

Autenticação

Request

Response

Campos da Resposta

Tipos de Saldo

Cálculo do Saldo Total

Comparação com API Padrão

Exemplo de Equivalência

Fluxo de Saldo em Operações

PIX Out (Transferência)

PIX In (Recebimento)

Boas Práticas

Erros Comuns

Próximos Passos