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

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

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

```bash
curl "https://platform.festero.com.br/v1/quotes?status=approved&limit=25" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{
  "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`](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 orçamento (GUID). |

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

```json
{
  "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](https://developers.festero.com.br/api/eventos.md)). |
| `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](https://developers.festero.com.br/limites.md).
- **Aprovação em tempo real:** os avisos [`quote.sent`](https://developers.festero.com.br/webhooks/eventos.md#quote-sent), [`quote.accepted`](https://developers.festero.com.br/webhooks/eventos.md#quote-accepted) e [`quote.rejected`](https://developers.festero.com.br/webhooks/eventos.md#quote-rejected) chegam assim que o cliente responde.

## 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 `quotes:read`. |
| [`not_found`](https://developers.festero.com.br/errors.md#not_found) | 404 | Orçamento inexistente ou de outra empresa. |

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