Financeiro

O financeiro da API tem duas partes: os recebíveis (as parcelas que a empresa tem a receber, uma a uma) e o resumo de vendas, que entrega os totais de um período numa única chamada, com os mesmos números do relatório de Vendas do Festero.

Escopo exigido: finance:read. Sem ele, as rotas respondem scope_missing.

Testar na referência interativa

Listar recebíveis

GET /v1/finance/receivables

Lista os recebíveis da empresa, da alteração mais antiga para a mais recente, com paginação por cursor.

Parâmetro	Tipo	Descrição
status	texto	Filtra pela situação: pending, partiallypaid, paid, overdue ou cancelled. Outro valor responde 400.
dueFrom	data yyyy-MM-dd	Vencimento a partir do qual listar (inclusive).
dueTo	data yyyy-MM-dd	Vencimento até o qual listar (inclusive).
eventId	GUID	Só os recebíveis deste evento.
updatedSince	data e hora ISO 8601	Só os recebíveis alterados a partir deste instante.
limit	inteiro	Tamanho da página, de 1 a 100 (padrão 25).
cursor	texto	O nextCursor da página anterior.

curl "https://platform.festero.com.br/v1/finance/receivables?status=overdue&limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": [
    {
      "id": "0f7c3a95-e1d8-4b26-9a40-5c2e8b6d1f73",
      "status": "overdue",
      "kind": "regular",
      "description": "Parcela 2 de 4 - Casamento Camila e Rafael",
      "amount": { "amount": 10700.00, "currency": "BRL" },
      "receivedAmount": { "amount": 0.00, "currency": "BRL" },
      "dueDate": "2026-10-10",
      "paidDate": null,
      "eventId": "b7e2c4a1-95d3-4f08-a6b2-1c8d3e5f7a90",
      "client": { "id": "9a3e7d52-1b68-4c04-b7f9-e0d2a5c8316b", "name": "Camila Duarte" },
      "category": { "id": "3e6b9d04-a7c2-4f81-b5d3-8a1c0e7f2946", "name": "Eventos" },
      "createdAt": "2026-10-10T20:20:02-03:00",
      "updatedAt": "2026-10-11T03:00:14-03:00"
    }
  ],
  "nextCursor": null
}

Buscar um recebível

GET /v1/finance/receivables/{id}

Devolve um recebível pelo identificador, com os mesmos campos da lista. Responde 404 (not_found) se ele não existe ou é de outra empresa. A resposta traz ETag: veja Paginação e datas.

Parâmetro	Onde	Descrição
id	caminho	Identificador do recebível (GUID).

curl https://platform.festero.com.br/v1/finance/receivables/0f7c3a95-e1d8-4b26-9a40-5c2e8b6d1f73 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Resumo de vendas

GET /v1/finance/sales-summary

Totais de vendas e de recebíveis de um período, pela data do evento. É a rota certa para "quanto vendemos e quanto falta receber em outubro?": uma chamada no lugar de percorrer todos os eventos e recebíveis.

Parâmetro	Tipo	Obrigatório	Descrição
from	data yyyy-MM-dd	sim	Primeira data do período (inclusive). Vale para a data do evento e para o vencimento dos recebíveis.
to	data yyyy-MM-dd	sim	Última data do período (inclusive). Não pode ser anterior a from nem passar de 366 dias depois dele.

curl "https://platform.festero.com.br/v1/finance/sales-summary?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "from": "2026-10-01",
  "to": "2026-10-31",
  "basis": "event_date",
  "soldEvents": {
    "count": 12,
    "total": { "amount": 184500.00, "currency": "BRL" },
    "received": { "amount": 96200.00, "currency": "BRL" },
    "balance": { "amount": 88300.00, "currency": "BRL" }
  },
  "receivables": {
    "count": 31,
    "amount": { "amount": 142300.00, "currency": "BRL" },
    "received": { "amount": 71800.00, "currency": "BRL" },
    "outstanding": { "amount": 70500.00, "currency": "BRL" },
    "overdueCount": 3,
    "overdueAmount": { "amount": 4200.00, "currency": "BRL" }
  }
}

Campos do resumo

Campo	Descrição
from, to	O período pedido.
basis	Base do cálculo. Hoje é sempre event_date: os eventos entram pela data do evento.
soldEvents.count	Quantidade de eventos vendidos no período.
soldEvents.total	Soma do valor dos eventos vendidos.
soldEvents.received	Soma do que já foi recebido desses eventos (recebíveis não cancelados).
soldEvents.balance	Saldo a receber dos eventos vendidos: total menos received.
receivables.count	Recebíveis não cancelados com vencimento no período.
receivables.amount	Soma dos valores cobrados desses recebíveis.
receivables.received	Soma do que já foi recebido deles.
receivables.outstanding	Valor em aberto: amount menos received.
receivables.overdueCount	Quantos desses recebíveis estão vencidos.
receivables.overdueAmount	Valor ainda em aberto dos vencidos (o valor cobrado menos o que já foi recebido).

Campos do recebível

Campo	Tipo	Descrição
id	GUID	Identificador do recebível.
status	texto	pending, partiallypaid, paid, overdue ou cancelled.
kind	texto ou null	Tipo do recebível: regular, additionalitem (item adicional, fora do rateio das parcelas), travelfee (taxa de deslocamento) ou travelfeeadjustment (ajuste da taxa de deslocamento).
description	texto ou null	Descrição. Trechos que parecem telefone, e-mail ou documento aparecem como [oculto].
amount	dinheiro	Valor cobrado do cliente, já com a taxa de cartão repassada, quando houver.
receivedAmount	dinheiro	Valor já recebido.
dueDate	data ou null	Vencimento.
paidDate	data ou null	Data do pagamento. null enquanto não houver pagamento.
eventId	GUID ou null	Evento a que pertence (Eventos).
client	{ id, name } ou null	Cliente do recebível.
category	{ id, name } ou null	Categoria financeira.
createdAt	instante	Criação.
updatedAt	instante ou null	Última alteração.

Campos que pedem atenção

• Mesmos números do relatório de Vendas. soldEvents segue a regra de venda da tela Relatórios, Vendas do Festero: contam os eventos nas situações Agendado (upcoming) e Realizado (completed), pela data do evento. O resultado é conferido contra o relatório do Festero por rotina de consistência.
• soldEvents e receivables são conjuntos diferentes. O primeiro agrupa por data do evento; o segundo por vencimento. Um evento de outubro pode ter parcelas que vencem em novembro, e vice-versa. Por isso soldEvents.received e receivables.received não precisam ser iguais.
• overdueAmount é o que falta, não o valor cheio. Soma amount menos receivedAmount dos recebíveis vencidos.
• O status overdue é aplicado por uma rotina diária do Festero, que marca como vencido o recebível pendente com vencimento anterior a hoje. Ele não muda no minuto em que a data passa.
• Cancelados ficam de fora do resumo. Recebíveis cancelled não entram em nenhum total.
• Pagamento parcial: status igual a partiallypaid e receivedAmount menor que amount.
• Valores sem custo e sem margem. O comprovante de pagamento, a régua de cobrança, contas a pagar, extratos e conciliação não existem na API.
• Limites: o período do resumo vai até 366 dias. Para períodos maiores, faça uma chamada por intervalo e some do seu lado.
• Avisos em tempo real: receivable.paid e receivable.overdue.

Erros possíveis

Código	HTTP	Quando
validation_failed	400	status inválido, data fora do formato yyyy-MM-dd, limit fora de 1 a 100 ou cursor inválido. No resumo: from ou to ausente, to anterior a from ou período acima de 366 dias.
scope_missing	403	A credencial não tem finance:read.
not_found	404	Recebível inexistente ou de outra empresa.

Testar na referência interativa