Consultar saldo

Visão Geral

Este endpoint permite recuperar informações detalhadas sobre o saldo financeiro atual da conta, incluindo valores disponíveis para saque, valores em processo de liquidação e valores bloqueados. É essencial para o planejamento financeiro, controle de fluxo de caixa e tomada de decisões sobre transações e saques.

Precauções

ATENÇÃO! Por favor, leia estas informações importantes antes de usar este endpoint.

• Valores Monetários: Todos os valores monetários são retornados em centavos (por exemplo, R$ 100,00 é representado como 10000).
• Atualização: O saldo é atualizado em tempo real conforme as transações são processadas.
• Bloqueios: Valores podem estar temporariamente bloqueados devido a disputas, chargebacks ou outros processos administrativos.
• Saldo zerado: Uma empresa sem movimentações ainda não possui registro de saldo; nesse caso, a API retorna todos os buckets zerados (não retorna 404).

Descrição

O endpoint Consultar Saldo permite recuperar a situação financeira atual da conta, detalhando os valores disponíveis para saque imediato, valores pendentes, bloqueados, reembolsados e a reserva de garantia. É uma ferramenta essencial para o planejamento financeiro e gestão de fluxo de caixa.

Requisição

GET /v1/balance

Escopo necessário: finance:read.

Resposta - 200 OK

Se a requisição for bem-sucedida, o servidor retornará um código de status HTTP 200 OK e os detalhes do saldo atual.

Exemplo de Resposta

Resposta no nível raiz (com merchant, sem _links).

{
  "availableBalance": 150000,
  "pendingBalance": 25000,
  "blockedBalance": 0,
  "refundedBalance": 12000,
  "warrantyBalance": 5000,
  "currency": "BRL",
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  }
}

Atributos da Resposta

Não existem os campos id/bal_, feePlan, debit, createdAt nem _links nesta resposta.

Histórico de Movimentações

GET /v1/balance/history (escopo finance:read) lista as movimentações do saldo (envelope paginado padrão). Cada item:

{
  "id": 1024,
  "fromType": "pending",
  "toType": "available",
  "processedAmount": 50000,
  "oldBalance": { "availableBalance": 100000, "pendingBalance": 75000, "blockedBalance": 0, "refundedBalance": 0 },
  "newBalance": { "availableBalance": 150000, "pendingBalance": 25000, "blockedBalance": 0, "refundedBalance": 0 },
  "handledBy": "receivable.released",
  "type": "receivableReleased",
  "description": "Recebível liberado para saque",
  "createdAt": "2026-04-12T17:56:33.000Z"
}

As taxas aparecem aqui como movimentações próprias: a taxa de chargeback (type: "chargebackFee") e a taxa de análise antifraude (type: "antifraudFee") são debitadas do availableBalance e cada uma tem sua linha no histórico.

Aceita os parâmetros de paginação limit (1–100, padrão 20) e offset.

Respostas de Erro

401 Unauthorized

Ocorre quando a autenticação falha ou o token de acesso é inválido.

{
  "error": {
    "status": "Unauthorized",
    "statusCode": 401,
    "category": "client",
    "message": "Authentication credentials are missing or invalid."
  }
}

Casos de Uso

1. Planejamento Financeiro: Verificar saldo disponível para planejar operações financeiras
2. Controle de Fluxo de Caixa: Monitorar entradas e saídas para gestão de caixa
3. Decisões de Saque: Determinar valores disponíveis para transferência para conta bancária
4. Reconciliação Contábil: Verificar saldos para reconciliação com registros contábeis
5. Auditoria de Movimentações: Use GET /v1/balance/history para auditar como o saldo mudou ao longo do tempo

Melhores Práticas

1. Consulta Regular: Verifique o saldo regularmente para manter-se atualizado
2. Antes de Saques: Sempre consulte o saldo disponível antes de solicitar saques
3. Monitoramento de Pendências: Acompanhe os valores pendentes (pendingBalance) para planejamento financeiro
4. Automação: Considere integrar consultas automáticas de saldo em seus sistemas
5. Tratamento de Saldo Zerado: Trate o caso de uma conta nova, cujos buckets retornam todos 0

Integração com Outros Endpoints

• Use Listar Recebíveis para verificar os valores a receber futuros
• Use Criar Saque para solicitar saques dos valores disponíveis
• Use Listar Saques para acompanhar os saques solicitados