Informações financeiras

Use o saldo para conferir quanto a conta tem no momento da consulta e qual parcela está disponível. Os valores podem mudar com novos recebimentos, saques, estornos, retenções e liberações.

As estatísticas de cobranças apresentam os totais por período. Elas ajudam a acompanhar os recebimentos. A previsão apresenta uma estimativa do que ainda pode ser recebido no período. Nenhuma delas substitui a consulta de saldo.

Consultar o saldo atual

Use Consultar saldo, com GET /v1/balances. A resposta apresenta os valores em centavos de real.

A consulta não reserva dinheiro. Um saque ou estorno continua sujeito às suas próprias condições, limites e à nova conferência do saldo no momento da solicitação.

Entender os valores

Se a conta tiver R$ 100,00 no total e R$ 30,00 bloqueados, a resposta será:

{
  "total_amount_cents": 10000,
  "blocked_amount_cents": 3000,
  "available_amount_cents": 7000
}

O bloqueio preserva o valor total e reduz o disponível. Sua liberação torna o valor disponível novamente; ela não representa um novo recebimento. O total mantém um eventual valor negativo, enquanto o disponível fica em zero quando não há valor livre para uso.

Saldo e extrato

O saldo mostra os valores atuais. O Extrato apresenta os lançamentos financeiros registrados, com seus tipos e vínculos. A soma de uma página ou de lançamentos filtrados não substitui a consulta de saldo.

A resposta de saldo não informa quanto havia na conta após um lançamento antigo. Para conferir uma movimentação, use Recuperar um lançamento.

Estatísticas de cobranças

Use Consultar estatísticas de cobranças, com GET /v1/charges/statistics, para acompanhar quantidades, valores e taxa de pagamento em um ERP, relatório ou painel próprio. A consulta reúne os totais da empresa e do ambiente da chave, sem exigir que você percorra todas as páginas de cobranças.

Os grupos issued, issued_paid e received informam count, para a quantidade, e amount_cents, para o valor em centavos de real. Os valores são brutos, sem descontar tarifas ou devoluções. Uma cobrança devolvida permanece nesses totais pelo valor original enquanto estiver em um dos estados considerados. Cobranças em estado de contestação não entram em issued_paid nem em received. A consulta não informa o saldo disponível da conta.

Por exemplo, uma cobrança criada ontem e paga hoje entra em received na consulta de hoje. Ela não entra em issued nem em issued_paid de hoje, pois foi criada fora desse período.

Para conferir cobranças individuais, use Listar cobranças. Para saber quanto dinheiro está disponível na conta, use Consultar saldo.

Período e atualização das estatísticas

Se a resposta informar INVALID_FIELDS com period e INVALID_VALUE em error.details, escolha um dos períodos aceitos. Envie period uma única vez. Datas personalizadas em start_at ou end_at não são filtros: um parâmetro desconhecido recebe UNKNOWN_QUERY_PARAMETER.

O parâmetro period aceita today, last_7_days, last_15_days e last_30_days. Quando omitido, a consulta considera hoje. Os períodos usam dias de calendário no horário de São Paulo e incluem o dia atual. last_7_days, por exemplo, começa à meia-noite de seis dias atrás e termina à meia-noite de amanhã.

start_at e end_at são campos da resposta, não filtros. Eles informam o início incluído e o fim excluído do período, em segundos Unix UTC. Use esses limites para identificar o intervalo do relatório. A consulta aceita somente os períodos listados em period, sem datas personalizadas de início e fim.

Os totais podem levar alguns segundos para refletir uma criação, pagamento, devolução ou remoção. updated_at informa a última atualização dos dados consultados, ou null quando essa informação não estiver disponível. Consultas repetidas não antecipam essa atualização.

Recebimentos previstos

Use Consultar recebimentos previstos, com GET /v1/balances/forecast, para acompanhar a mesma estimativa financeira apresentada no Resumo do Dashboard.

receivable_amount_cents apresenta os pagamentos confirmados que o cálculo ainda mantém como recebimentos previstos dentro do período escolhido. A consulta não soma cobranças abertas nem procura vencimentos futuros. O período se refere à data prevista de recebimento, não à data de criação da cobrança.

projected_balance_cents soma essa estimativa ao saldo total atual da conta. Por exemplo, um saldo total de R$ 100,00 com R$ 25,00 previstos resulta em R$ 125,00 projetados. O valor pode incluir saldo bloqueado e não confirma liquidação bancária, prazo garantido ou disponibilidade para saque. Consulte Consultar saldo para saber os valores atuais total, bloqueado e disponível.

O parâmetro period aceita today, last_7_days, last_15_days e last_30_days; o padrão é today. Os períodos incluem hoje e usam o calendário de São Paulo. last_7_days, por exemplo, começa à meia-noite de seis dias atrás e termina à meia-noite de amanhã. Essa consulta não projeta os próximos sete, quinze ou trinta dias.

start_at informa o início incluído e end_at, o fim excluído do período. forecast_date identifica o dia de referência da estimativa, à meia-noite de hoje em São Paulo. Esses campos usam segundos Unix UTC.

Os valores podem levar alguns segundos para acompanhar mudanças nos pagamentos. updated_at informa a atualização dos dados da previsão, ou null quando ela não estiver disponível. Uma estimativa igual a zero não comprova que todos os pagamentos foram liquidados. No Sandbox, os valores são simulados e não representam recebimentos reais.

Saques em processamento

Use Consultar saques em processamento para acompanhar o total das retiradas que ainda aguardam conclusão. A consulta exige uma chave de API de Produção e considera os saques com situação PENDING ou PROCESSING.

processing_count informa a quantidade de saques, e processing_amount_cents soma o valor solicitado, incluindo a tarifa, em centavos de real. Quando não houver saques nessas situações, os dois campos retornam zero.

Esse total representa dinheiro comprometido com as solicitações. Não o some ao saldo disponível nem o trate como crédito confirmado na conta de destino. Para conferir cada pedido e seu resultado, use Listar saques. A consulta do resumo não solicita outra retirada nem altera o andamento dos saques.

Empresa e ambiente

As consultas exigem uma chave de API e usam a empresa e o ambiente vinculados a ela. A chave Sandbox consulta o saldo de simulação, separado do saldo de Produção. O console aceita somente chaves Sandbox.

Você não precisa informar uma empresa ou conta no corpo da requisição. Trate os erros pelo status HTTP e por error.code, conforme Códigos HTTP das respostas.