Finanças - 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

• 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

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

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

#Saldo negativo e quitação por Pix

O availableBalance fica negativo quando a conta passa a dever à plataforma — em geral um estorno ou chargeback que chegou depois de o dinheiro já ter sido sacado. Enquanto isso durar:

• nenhum saque é possível — POST /v1/withdrawals responde 422 withdrawalBlockedByDebt, com o valor em aberto em error.params[0].owedAmount (centavos). Sacar menos não resolve;
• a dívida é abatida sozinha pelos próximos recebíveis liberados. Não é preciso fazer nada se a conta continua vendendo.

Para quem não tem entrada e quer quitar agora, existe o Pix de quitação.

#Emitir o Pix de quitação

POST /v1/balance/debt-settlements

Escopo finance:create. Sem corpo. Emite um Pix pelo valor devido naquele instante — ou, se já houver um Pix de quitação pendente e dentro da validade, devolve o mesmo (um duplo clique nunca gera dois QR para pagar).

{
  "object": "debt_settlement",
  "id": "dset_rs83xah4c1977g6w",
  "status": "pending",
  "owedAtIssuance": 48496,
  "amount": 48496,
  "paidAmount": null,
  "refundedAmount": 0,
  "currency": "BRL",
  "pix": { "qrCodeEmv": "00020126…" },
  "expiresAt": "2026-09-17T12:00:00.000Z",
  "paidAt": null,
  "createdAt": "2026-09-16T12:00:00.000Z"
}

• Sem saldo negativo, responde 422 balanceHasNoDebt.
• Um Pix de cada vez. Enquanto houver um Pix de quitação em aberto, o POST devolve o mesmo — e dois pedidos no mesmo instante (o segundo chega enquanto o primeiro ainda espera o banco) respondem 409 debtSettlementInProgress: aguarde alguns segundos e peça de novo. A rota aceita X-Idempotency-Key.
• O pagamento é confirmado consultando o banco, não só pelo aviso dele. Confirmado, o valor pago entra no availableBalance de uma vez, sem taxa e sem retenção, e aparece no histórico como type: "debtSettlement" — "Quitação de saldo negativo (Pix)".
• Pagou a mais, fica com o saldo. A dívida pode diminuir entre a emissão e o pagamento (um recebível liberado no meio). O valor pago é creditado inteiro, e o que passar da dívida fica disponível para saque.
• A validade do Pix é de 24 horas. Vencido, emita outro.
• Se o banco devolver o Pix (MED, contestação ou devolução feita no banco), o crédito sai do availableBalance e a dívida volta — com o saque barrado de novo. A devolução é conferida no banco antes, debitada uma vez por devolução e nunca além do que foi pago, e aparece no histórico como type: "debtSettlementRefund". Uma devolução parcial debita só a parte devolvida e mantém status: "paid", com refundedAmount preenchido.

#Listar as quitações

GET /v1/balance/debt-settlements?limit=20&offset=0

Escopo finance:read. O registro de cada quitação emitida — pendente, paga, vencida ou devolvida —, da mais recente para a mais antiga.

#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