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.

Testar na referência interativa

Listar eventos

GET /v1/events

Lista os eventos 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: 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.

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"

{
  "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) se ele não existe, foi excluído ou é de outra empresa. A resposta traz ETag: veja Paginação e datas.

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

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).
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 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.
• 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.
• Mudanças em tempo real: event.created, event.status_changed e event.cancelled.

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.
scope_missing	403	A credencial não tem events:read.
not_found	404	Evento inexistente, excluído ou de outra empresa.

Testar na referência interativa