# 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`](https://developers.festero.com.br/errors.md#scope_missing).

[Testar na referência interativa](https://developers.festero.com.br/referencia/)

## 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](https://developers.festero.com.br/paginacao.md).

| 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. |

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

```json
{
  "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`](https://developers.festero.com.br/errors.md#not_found)) se ele não existe ou é de outra empresa. A resposta traz `ETag`: veja [Paginação e datas](https://developers.festero.com.br/paginacao.md#recurso-individual-etag).

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

```bash
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. |

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

```json
{
  "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](https://developers.festero.com.br/api/eventos.md)). |
| `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`](https://developers.festero.com.br/webhooks/eventos.md#receivable-paid) e [`receivable.overdue`](https://developers.festero.com.br/webhooks/eventos.md#receivable-overdue).

## Erros possíveis

| Código | HTTP | Quando |
|---|---|---|
| [`validation_failed`](https://developers.festero.com.br/errors.md#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`](https://developers.festero.com.br/errors.md#scope_missing) | 403 | A credencial não tem `finance:read`. |
| [`not_found`](https://developers.festero.com.br/errors.md#not_found) | 404 | Recebível inexistente ou de outra empresa. |

[Testar na referência interativa](https://developers.festero.com.br/referencia/)