# Catálogo

Estas rotas devolvem o **catálogo** que a empresa monta no Festero: os pacotes, os itens que ela vende, as categorias e as tabelas de preço. Servem para um site ou cotador externo mostrar os mesmos pacotes e preços, e para o financeiro cruzar preço e custo de cada item.

**Escopo exigido:** `catalog:read`. Sem ele, as rotas respondem [`scope_missing`](https://developers.festero.com.br/errors.md#scope_missing).

> **Atenção**: O catálogo traz o custo de cada item
>
> Diferente do resto da API, os itens do catálogo saem **com o custo cadastrado** (`cost` e `defaultCost`). É uma exceção deliberada, concedida por quem libera o escopo. Margem e lucro continuam fora de toda a API.

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

## Pacotes

### `GET /v1/catalog/packages`

Lista os pacotes (resumo): nome, descrição, preço base, modo de cobrança, se está publicado na vitrine, cor na agenda e quantidade de itens. [Paginação por cursor](https://developers.festero.com.br/paginacao.md).

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `isPublished` | `true` ou `false` | Só os publicados na vitrine ou só os que não estão. |
| `updatedSince`, `limit`, `cursor` | | Como nas demais listas. |

### `GET /v1/catalog/packages/{id}`

Devolve um pacote completo: o resumo (`package`), os compartimentos (`items`, cada um com as `options` que o cliente pode escolher), os itens fixos (`directItems`) e todas as formas de preço: faixas por número de convidados (`pricingTiers`), preço por convidado (`perGuestPrices`) e preço fixo por tabela (`tablePrices`). Responde `404` se o pacote não existe ou é de outra empresa. A resposta traz `ETag`.

## Itens do catálogo

### `GET /v1/catalog/items`

Lista os itens do catálogo com preço de venda e custo, da alteração mais antiga para a mais recente.

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `categoryId` | GUID | Só os itens desta categoria (veja [categorias](#categorias)). |
| `isPublished` | `true` ou `false` | Só os publicados na vitrine ou só os que não estão. |
| `updatedSince`, `limit`, `cursor` | | Como nas demais listas. |

| Campo | Descrição |
|---|---|
| `name`, `description`, `sku`, `unit` | Identificação e unidade de venda. |
| `category` | Categoria do item (`id`, `name`, `code`). |
| `price` | Preço de venda ao cliente. |
| `cost`, `defaultCost`, `costOrigin` | Custo cadastrado, custo padrão e de onde ele vem. Podem ser `null`. |
| `resourceNature` | Natureza do recurso, como gravado. |
| `isPublished` | Aparece na vitrine pública. |
| `defaultSupplier` | Fornecedor padrão (`id` e `name`). |

## Categorias

### `GET /v1/catalog/categories`

Lista as categorias de itens. Lista curta, devolvida inteira (`nextCursor` nulo). `includeDisabled=true` inclui as desativadas.

### `GET /v1/catalog/package-categories`

Lista as categorias de pacotes, no mesmo formato.

## Tabelas de preço

### `GET /v1/catalog/price-tables`

Lista as tabelas de preço: a vigência por data do evento (`eventDateFrom` e `eventDateTo`), a situação (`open` ou `closed`) e quantos preços cada uma tem (`priceCount`). Lista curta, devolvida inteira.