> ## Documentation Index > Fetch the complete documentation index at: https://docs.cakto.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Agenda de Recebimentos > Veja quanto libera em cada dia. É a mesma apuração da tela Agenda Financeira do painel. #### Escopo ```bash theme={null} read payments ``` ## 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. > [!NOTE] > > 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. | Você quer saber | Use | | - | - | | quanto cai em outubro | esta operação, com a janela de outubro | | o que vendi em outubro | [Listar Pedidos](/api-reference/orders/list.md) | | quando cai **um** pedido | `releaseDate` em [Obter Pedido](/api-reference/orders/retrieve.md) | 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. > [!WARNING] > > 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 ```python Python theme={null} import requests from decimal import Decimal response = requests.get( "https://api.cakto.com.br/public_api/balance/schedule/", params={"releaseDate__gte": "2026-10-01", "releaseDate__lte": "2026-10-31"}, headers={"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn..."}, timeout=30, ) response.raise_for_status() agenda = response.json() total = sum(Decimal(dia["totalToReceive"]) for dia in agenda) print(f"Previsto para outubro: R$ {total}") for dia in agenda[:5]: print(f"{dia['date']}: R$ {dia['totalToReceive']}") ``` ```javascript Node.js theme={null} const params = new URLSearchParams({ releaseDate__gte: "2026-10-01", releaseDate__lte: "2026-10-31", }); const response = await fetch( `https://api.cakto.com.br/public_api/balance/schedule/?${params}`, { headers: { Authorization: "Bearer eyJhbGciOiJIUzI1NiIsIn..." } }, ); if (!response.ok) throw new Error(`Cakto API error ${response.status}`); const agenda = await response.json(); agenda.forEach((dia) => console.log(`${dia.date}: R$ ${dia.totalToReceive}`)); ``` *** ## 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](/api-reference/balance/retrieve.md). ## OpenAPI ````yaml GET /public_api/balance/schedule/ openapi: 3.0.3 info: title: Cakto API version: 1.0.0 description: Documentação da API pública do Cakto. servers: - url: https://api.cakto.com.br description: Cakto API security: [] paths: /public_api/balance/schedule/: get: tags: - balance description: >- Agenda de liberação dos recebimentos da conta autenticada. Uma entrada por dia em que há dinheiro previsto para liberar, na mesma apuração da tela "Agenda Financeira" do painel. O recorte é pela **data de liberação** (`releaseDate`), não pela data da venda — para listar vendas por data de criação use `orders/`. É previsão: antecipação, reembolso e chargeback mudam o valor de um dia que ainda não chegou. Como no saldo, a operação responde sempre a conta dona do token. operationId: balance_schedule_list parameters: - in: query name: currency schema: type: string enum: - BRL - USD description: Moeda dos valores. Default `BRL`. - in: query name: releaseDate__gte schema: type: string format: date description: >- 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. - in: query name: releaseDate__lte schema: type: string format: date description: >- Fim da janela, inclusive (o dia inteiro entra). A janela não pode passar de 365 dias. responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/BalanceScheduleEntry' examples: Sucesso: value: - - date: '2026-09-18' currency: BRL pending: '740.00' pendingReserve: '0.00' heldByRefund: '0.00' totalToReceive: '740.00' - date: '2026-09-22' currency: BRL pending: '1310.50' pendingReserve: '120.00' heldByRefund: '89.90' totalToReceive: '1430.50' description: >- Uma entrada por dia com valor previsto, em ordem crescente de data. Dia sem previsão não aparece na lista. '400': content: application/json: schema: type: object properties: detail: type: string examples: JanelaIncompleta: value: detail: >- Informe `releaseDate__gte` e `releaseDate__lte` juntos, ou nenhum dos dois para receber os próximos 30 dias. JanelaMuitoLonga: value: detail: A janela não pode passar de 365 dias. description: Corpo da resposta status 400 '401': description: Request não autenticado devido à ausência ou invalidez do token. content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedError' examples: Token ausente ou inválido: $ref: '#/components/examples/UnauthenticatedErrorExample' '403': content: application/json: schema: type: object properties: detail: type: string examples: EscopoInsuficiente: value: detail: Você não tem permissão para executar esta ação. description: Chave de API sem o escopo `payments`. '409': content: application/json: schema: type: object properties: detail: type: string examples: ContaSemRecebimento: value: detail: >- Conta ainda não habilitada para recebimento. Conclua o cadastro no painel da Cakto para que o saldo exista. description: >- A conta ainda não tem cadastro de recebimento concluído, então não há saldo a responder. Não vale repetir a chamada até que o cadastro seja concluído no painel — e este 409 nunca significa "sem saldo": saldo zero responde 200. security: - OAuth Token: [] components: schemas: BalanceScheduleEntry: type: object properties: date: type: string format: date description: >- Dia da liberação (`YYYY-MM-DD`). Só aparecem dias com valor previsto. currency: type: string description: Moeda dos valores desta entrada. pending: type: string format: decimal example: '2.49' description: >- Previsto para liberar neste dia, fora reserva. Já desconta o que foi antecipado: a parcela antecipada virou saque e não libera de novo. pendingReserve: type: string format: decimal example: '2.49' description: Reserva de segurança que sai da retenção neste dia. heldByRefund: type: string format: decimal example: '2.49' description: >- Valor que venceria neste dia mas está retido por pedido de reembolso, e por isso **não** entra em `pending` nem em `totalToReceive`. totalToReceive: type: string format: decimal example: '2.49' description: '`pending` + `pendingReserve`: o que efetivamente cai no dia.' required: - currency - date - heldByRefund - pending - pendingReserve - totalToReceive UnauthenticatedError: type: object properties: detail: type: string examples: UnauthenticatedErrorExample: summary: Token ausente ou inválido description: Token ausente ou inválido value: detail: As credenciais de autenticação não foram fornecidas. securitySchemes: OAuth Token: type: http scheme: bearer in: header name: Authorization description: >- Token de autenticação do tipo `Bearer {access_token}`, onde `{access_token}` é o token obtido no fluxo de [autenticação](/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.