Consultar saldos

GET /api/v1/valepix/balances

Retorna o saldo total e as contas de benefício disponíveis para a integração autorizada.

Autenticação

Envie um API token ativo no header Authorization.

Authorization: Bearer <VALEPIX_API_TOKEN>
Accept: application/json

Path params

Esta rota não possui path params.

Exemplo curl

curl --request GET \
  --url "https://routes.valepix.com.br/api/v1/valepix/balances" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Response

HTTP 200 OK.

{
  "success": "success",
  "data": {
    "wallet_id": "00000000-0000-4000-8000-000000000601",
    "total_balance": 250000,
    "reserved_balance": 50000,
    "available_balance": 200000,
    "tag": "empresa-exemplo",
    "wallet_accounts": [
      {
        "id": "00000000-0000-4000-8000-000000000611",
        "slug": "alimentacao",
        "balance": 150000,
        "currency": "BRL",
        "is_frozen": false,
        "reserved_balance": 30000,
        "available_balance": 120000
      },
      {
        "id": "00000000-0000-4000-8000-000000000612",
        "slug": "livre",
        "balance": 100000,
        "currency": "BRL",
        "is_frozen": false,
        "reserved_balance": 20000,
        "available_balance": 80000
      }
    ]
  }
}

Todos os valores monetários são informados em centavos. reserved_balance representa valores já comprometidos por operações em andamento e available_balance corresponde ao saldo que permanece disponível.

Como usar o resultado

• Use esta rota depois da confirmação do depósito.
• Antes de finalizar uma distribuição, compare o valor necessário com o saldo retornado para as contas envolvidas.

Erros comuns

HTTP	Quando acontece	Ação recomendada
401	Token ausente, inválido, expirado ou revogado	Conferir o header Authorization
403	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
404	Saldos não encontrados	Confirmar a configuração da integração com a ValePix
429	Limite de chamadas excedido	Reduzir a frequência das consultas e aplicar backoff
500, 502, 503, 504	Falha temporária na consulta	Tentar novamente com backoff