Orçamentos

Os orçamentos são as propostas que a empresa envia aos clientes. A lista traz o resumo de cada um (cliente, data do evento, valores e situação). A busca por identificador traz o orçamento completo, com as opções (quando há várias propostas) e as linhas (itens).

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

Testar na referência interativa

Listar orçamentos

GET /v1/quotes

Lista os orçamentos da empresa, da alteração mais antiga para a mais recente, com paginação por cursor. A lista não traz opções nem itens; para isso, busque o orçamento por id.

Parâmetro	Tipo	Descrição
status	texto	Filtra pela situação: draft, sent, approved, rejected, expired 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 orçamentos 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/quotes?status=approved&limit=25" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": [
    {
      "id": "e4f6a9b2-3c71-4d85-9b0e-7a1c5d8f2634",
      "title": "Orçamento Casamento Camila e Rafael",
      "status": "approved",
      "client": { "id": "9a3e7d52-1b68-4c04-b7f9-e0d2a5c8316b", "name": "Camila Duarte" },
      "eventId": "b7e2c4a1-95d3-4f08-a6b2-1c8d3e5f7a90",
      "eventDate": "2027-03-20",
      "eventTime": "18:00",
      "guestCount": 150,
      "eventType": { "id": "5d1a8c33-7e42-49b6-8f10-c2a9b4d6e871", "name": "Casamento" },
      "packageName": "Pacote Ouro",
      "isRental": false,
      "city": "Salvador",
      "state": "BA",
      "subtotal": { "amount": 44300.00, "currency": "BRL" },
      "discount": { "amount": 1500.00, "currency": "BRL" },
      "travelFee": null,
      "total": { "amount": 42800.00, "currency": "BRL" },
      "validUntil": "2026-11-15",
      "sentAt": "2026-10-08T11:02:44-03:00",
      "approvedAt": "2026-10-10T20:15:31-03:00",
      "createdAt": "2026-10-07T15:30:12-03:00",
      "updatedAt": "2026-10-10T20:15:31-03:00"
    }
  ],
  "nextCursor": null
}

Buscar um orçamento

GET /v1/quotes/{id}

Devolve o orçamento completo: os campos do resumo, mais options e items. 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 orçamento (GUID).

curl https://platform.festero.com.br/v1/quotes/e4f6a9b2-3c71-4d85-9b0e-7a1c5d8f2634 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "id": "e4f6a9b2-3c71-4d85-9b0e-7a1c5d8f2634",
  "title": "Orçamento Casamento Camila e Rafael",
  "status": "approved",
  "client": { "id": "9a3e7d52-1b68-4c04-b7f9-e0d2a5c8316b", "name": "Camila Duarte" },
  "eventId": "b7e2c4a1-95d3-4f08-a6b2-1c8d3e5f7a90",
  "eventDate": "2027-03-20",
  "eventTime": "18:00",
  "guestCount": 150,
  "eventType": { "id": "5d1a8c33-7e42-49b6-8f10-c2a9b4d6e871", "name": "Casamento" },
  "packageName": "Pacote Ouro",
  "isRental": false,
  "city": "Salvador",
  "state": "BA",
  "subtotal": { "amount": 44300.00, "currency": "BRL" },
  "discount": { "amount": 1500.00, "currency": "BRL" },
  "travelFee": null,
  "total": { "amount": 42800.00, "currency": "BRL" },
  "validUntil": "2026-11-15",
  "sentAt": "2026-10-08T11:02:44-03:00",
  "approvedAt": "2026-10-10T20:15:31-03:00",
  "createdAt": "2026-10-07T15:30:12-03:00",
  "updatedAt": "2026-10-10T20:15:31-03:00",
  "options": [],
  "items": [
    {
      "id": "1c5e8a30-9b27-4f64-a3d1-6e0b2c7f4a85",
      "name": "Buffet completo",
      "category": "Buffet",
      "quantity": 1,
      "unit": "perguest",
      "unitPrice": { "amount": 250.00, "currency": "BRL" },
      "total": { "amount": 37500.00, "currency": "BRL" },
      "isIncluded": true,
      "isFromPackage": true,
      "optionId": null
    },
    {
      "id": "7a2d9f46-0c18-4b53-8e6a-d4b1f3a95c07",
      "name": "Decoração",
      "category": "Decoração",
      "quantity": 1,
      "unit": "noquantity",
      "unitPrice": { "amount": 4800.00, "currency": "BRL" },
      "total": { "amount": 4800.00, "currency": "BRL" },
      "isIncluded": true,
      "isFromPackage": false,
      "optionId": null
    },
    {
      "id": "d3b8e1c7-5f49-4a02-9c64-a0e7b2d1f836",
      "name": "Som e iluminação",
      "category": "Equipamentos",
      "quantity": 1,
      "unit": "noquantity",
      "unitPrice": { "amount": 2000.00, "currency": "BRL" },
      "total": { "amount": 2000.00, "currency": "BRL" },
      "isIncluded": true,
      "isFromPackage": false,
      "optionId": null
    }
  ]
}

Campos do orçamento

Campo	Tipo	Descrição
id	GUID	Identificador do orçamento.
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, sent, approved, rejected, expired ou cancelled.
client	{ id, name } ou null	Cliente do orçamento.
eventId	GUID ou null	Evento vinculado, quando o orçamento virou evento (Eventos).
eventDate, eventTime	data e texto	Data e horário do evento.
guestCount	inteiro ou null	Número de convidados.
eventType	{ id, name } ou null	Tipo de evento cadastrado pela empresa.
packageName	texto ou null	Nome do pacote do orçamento.
isRental	booleano	Indica que o orçamento é de uma locação.
city, state	texto ou null	Cidade e estado do evento.
subtotal	dinheiro	Soma dos itens, antes do desconto.
discount	dinheiro	Desconto do orçamento.
travelFee	dinheiro ou null	Taxa de deslocamento, quando houver.
total	dinheiro	Valor total do orçamento.
validUntil	data ou null	Data até a qual o orçamento vale.
sentAt	instante ou null	Envio ao cliente.
approvedAt	instante ou null	Aprovação.
createdAt	instante	Criação.
updatedAt	instante ou null	Última alteração.
options	lista	Só na busca por id. Opções do orçamento.
items	lista	Só na busca por id. Linhas (itens) do orçamento.

Opções (options)

Um orçamento pode ter várias propostas (opções). Num orçamento comum, options vem vazia.

Campo	Tipo	Descrição
id	GUID	Identificador da opção.
label	texto ou null	Nome da opção.
isDefault	booleano	Opção padrão: enquanto o cliente não escolhe, o total do orçamento segue ela.
isChosen	booleano	Opção que o cliente (ou a empresa, em nome dele) escolheu. No máximo uma por orçamento.
discount	dinheiro	Desconto desta opção. Com opções, cada uma desconta o seu valor.

Itens (items)

Campo	Tipo	Descrição
id	GUID	Identificador da linha.
name	texto	Nome do item.
category	texto ou null	Categoria do item.
quantity	número	Quantidade.
unit	texto ou null	Unidade de venda, em minúsculas.
unitPrice	dinheiro	Preço unitário efetivo ao cliente.
total	dinheiro	Total da linha.
isIncluded	booleano	false indica item adicional, cobrado à parte e fora do rateio das parcelas.
isFromPackage	booleano	A linha representa um pacote do catálogo.
optionId	GUID ou null	Opção a que a linha pertence. null vale para todas as opções.

Campos que pedem atenção

• total é o valor oficial. Use-o em vez de somar as linhas: o desconto pode vir do orçamento ou, quando há opções, da opção de referência (a escolhida, ou a padrão enquanto o cliente não escolheu).
• Como items[].total é calculado. Segue a mesma regra da tela do Festero: com unit igual a perguest, o total é unitPrice × quantity × guestCount; com noquantity ou unlimited, vale o preço cheio, sem quantidade; nos demais casos, unitPrice × quantity.
• Valores são preço ao cliente. Custos, composição vendida e margem não existem na API.
• Sem anotações. As anotações internas e livres do orçamento, o endereço completo e os códigos de acesso ao portal do cliente não saem pela API.
• A lista é resumida. options e items só vêm na busca por id. Para ler vários orçamentos completos, liste e depois busque um a um, respeitando os limites de uso.
• Aprovação em tempo real: os avisos quote.sent, quote.accepted e quote.rejected chegam assim que o cliente responde.

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 quotes:read.
not_found	404	Orçamento inexistente ou de outra empresa.

Testar na referência interativa