Skip to main content
GET
cURL

Escopo

O que é este endpoint?

É a versão consultável por API da tela Agenda Financeira do painel: uma entrada por dia em que há dinheiro previsto para liberar, com o total daquele dia separado em pendente, reserva e retido. Sem parâmetros, a resposta traz os próximos 30 dias — a mesma janela que o painel abre ao carregar o calendário.
A operação lê sempre a conta dona do token. Não existe parâmetro de produtor.

O filtro é pela data de liberação, não pela data da venda

releaseDate__gte e releaseDate__lte recortam quando o dinheiro cai, não quando a venda aconteceu. É a pergunta que a agenda responde, e a confusão aqui é silenciosa: a resposta vem correta, só que de outra pergunta. A janela é inclusiva nos dois lados (o dia final entra inteiro) e não pode passar de 365 dias.

Como ler cada dia

  • totalToReceive é pending + pendingReserve: o que efetivamente cai naquele dia.
  • heldByRefund venceria no dia, mas está retido por pedido de reembolso e não entra em totalToReceive. Se o reembolso for negado, o valor volta para uma data futura — não para esta.
  • Dias sem valor não aparecem. A lista é esparsa: para montar um calendário, preencha os buracos com zero em vez de assumir uma entrada por dia.
  • pending já desconta o que foi antecipado. A parcela antecipada virou saque e não libera de novo.
A agenda é previsão, não promessa. Antecipação, reembolso e chargeback mudam o valor de um dia que ainda não chegou, e a apuração é refeita a cada consulta.

Exemplo


Boas práticas

  • Peça a janela que você vai usar. Pedir 365 dias para exibir um mês gasta limite de requisição e traz previsão que ainda vai mudar.
  • Reconsulte antes de decidir. Para conciliação, consulte o dia depois que ele passou: até lá o valor é estimativa.
  • Some com Decimal, não com float. Os valores vêm como string decimal pelo mesmo motivo do Saldo.

Authorizations

Authorization
string
header
required

Token de autenticação do tipo Bearer {access_token}, onde {access_token} é o token obtido no fluxo de autenticação.

Query Parameters

currency
enum<string>

Moeda dos valores. Default BRL.

Available options:
BRL,
USD
releaseDate__gte
string<date>

Início da janela, pela data de liberação (YYYY-MM-DD). Não é a data da venda: para recortar vendas por criação use orders/. Obrigatório junto de releaseDate__lte; omitindo os dois, a resposta traz os próximos 30 dias.

releaseDate__lte
string<date>

Fim da janela, inclusive (o dia inteiro entra). A janela não pode passar de 365 dias.

Response

Uma entrada por dia com valor previsto, em ordem crescente de data. Dia sem previsão não aparece na lista.

date
string<date>
required

Dia da liberação (YYYY-MM-DD). Só aparecem dias com valor previsto.

currency
string
required

Moeda dos valores desta entrada.

pending
string<decimal>
required

Previsto para liberar neste dia, fora reserva. Já desconta o que foi antecipado: a parcela antecipada virou saque e não libera de novo.

Example:

"2.49"

pendingReserve
string<decimal>
required

Reserva de segurança que sai da retenção neste dia.

Example:

"2.49"

heldByRefund
string<decimal>
required

Valor que venceria neste dia mas está retido por pedido de reembolso, e por isso não entra em pending nem em totalToReceive.

Example:

"2.49"

totalToReceive
string<decimal>
required

pending + pendingReserve: o que efetivamente cai no dia.

Example:

"2.49"