# Eventos

Os eventos são as festas, casamentos e locações da empresa. A API entrega o **núcleo estável** de cada evento: identidade, data, horário, situação, tipo, cliente e valor total, mais convidados previstos e cidade. É o suficiente para agenda, relatórios e conciliação com outros sistemas.

**Escopo exigido:** `events: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 eventos

### `GET /v1/events`

Lista os eventos 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: `draft`, `upcoming`, `confirmed`, `inprogress`, `completed` ou `cancelled`. Outro valor responde `400`. |
| `eventDateFrom` | data `yyyy-MM-dd` | Data do evento a partir da qual listar (inclusive). |
| `eventDateTo` | data `yyyy-MM-dd` | Data do evento até a qual listar (inclusive). |
| `updatedSince` | data e hora ISO 8601 | Só os eventos 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/events?status=upcoming&eventDateFrom=2027-03-01&eventDateTo=2027-03-31&limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{
  "data": [
    {
      "id": "b7e2c4a1-95d3-4f08-a6b2-1c8d3e5f7a90",
      "title": "Casamento Camila e Rafael",
      "status": "upcoming",
      "kind": "conventional",
      "eventType": { "id": "5d1a8c33-7e42-49b6-8f10-c2a9b4d6e871", "name": "Casamento" },
      "client": { "id": "9a3e7d52-1b68-4c04-b7f9-e0d2a5c8316b", "name": "Camila Duarte" },
      "eventDate": "2027-03-20",
      "eventTime": "18:00",
      "durationHours": 5,
      "guestCount": 150,
      "city": "Salvador",
      "state": "BA",
      "isRental": false,
      "quoteId": "e4f6a9b2-3c71-4d85-9b0e-7a1c5d8f2634",
      "totalAmount": { "amount": 42800.00, "currency": "BRL" },
      "discount": { "amount": 1500.00, "currency": "BRL" },
      "travelFee": null,
      "contractedAt": "2026-10-10T20:15:31-03:00",
      "createdAt": "2026-10-08T10:12:40-03:00",
      "updatedAt": "2026-10-10T20:15:31-03:00"
    }
  ],
  "nextCursor": null
}
```

## Buscar um evento

### `GET /v1/events/{id}`

Devolve um evento 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, foi excluído 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 evento (GUID). |

```bash
curl https://platform.festero.com.br/v1/events/b7e2c4a1-95d3-4f08-a6b2-1c8d3e5f7a90 \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Campos do evento

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | GUID | Identificador do evento. |
| `title` | texto | Título (o nome de exibição, quando houver). Trechos que parecem telefone, e-mail ou documento aparecem como `[oculto]`. |
| `status` | texto | `draft`, `upcoming`, `confirmed`, `inprogress`, `completed` ou `cancelled`. |
| `kind` | texto ou `null` | Natureza do evento: `conventional`, `rental` ou `show`. |
| `eventType` | `{ id, name }` ou `null` | Tipo de evento cadastrado pela empresa. |
| `client` | `{ id, name }` ou `null` | Cliente do evento. |
| `eventDate` | data ou `null` | Data do evento. |
| `eventTime` | texto ou `null` | Horário do evento, como cadastrado no Festero. |
| `durationHours` | número ou `null` | Duração, em horas. |
| `guestCount` | inteiro ou `null` | Convidados previstos. |
| `city`, `state` | texto ou `null` | Cidade e estado do evento. |
| `isRental` | booleano | Indica que o evento é uma locação. |
| `quoteId` | GUID ou `null` | Orçamento vinculado ([Orçamentos](https://developers.festero.com.br/api/orcamentos.md)). |
| `totalAmount` | dinheiro ou `null` | Valor total do evento. |
| `discount` | dinheiro ou `null` | Desconto aplicado. |
| `travelFee` | dinheiro ou `null` | Taxa de deslocamento. |
| `contractedAt` | instante ou `null` | Quando o evento foi contratado. |
| `createdAt` | instante | Criação. |
| `updatedAt` | instante ou `null` | Última alteração. |

## Campos que pedem atenção

- **Só o núcleo.** A API não entrega endereço completo, valores de custo, lista de convidados, respostas de formulários nem textos livres.
- **`totalAmount` é o valor do evento, não o que já foi pago.** Para o que foi recebido, consulte os [recebíveis](https://developers.festero.com.br/api/financeiro.md) do evento com `eventId`, ou o resumo de vendas.
- **Quais eventos são "vendidos".** No resumo de vendas, contam como vendidos os eventos nas situações `upcoming` (Agendado) e `completed` (Realizado). Use a mesma régua nos seus relatórios para bater com o Festero.
- **`eventDate` é uma data, `contractedAt` é um instante.** A data não tem fuso nem hora; veja [Paginação e datas](https://developers.festero.com.br/paginacao.md#datas-e-horarios).
- **Evento excluído some.** Um evento excluído no Festero deixa de aparecer nas listas e responde `404` por `id`. Para saber da exclusão na hora, assine o webhook [`event.cancelled`](https://developers.festero.com.br/webhooks/eventos.md#event-cancelled).
- **Mudanças em tempo real:** [`event.created`](https://developers.festero.com.br/webhooks/eventos.md#event-created), [`event.status_changed`](https://developers.festero.com.br/webhooks/eventos.md#event-status-changed) e [`event.cancelled`](https://developers.festero.com.br/webhooks/eventos.md#event-cancelled).

## 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. |
| [`scope_missing`](https://developers.festero.com.br/errors.md#scope_missing) | 403 | A credencial não tem `events:read`. |
| [`not_found`](https://developers.festero.com.br/errors.md#not_found) | 404 | Evento inexistente, excluído ou de outra empresa. |

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