# Estoque

Estas rotas devolvem o **estoque** da empresa: o que existe, o que entrou e saiu, o que está reservado para eventos, as avarias, as entregas de locação e as listas de compras. Servem para reposição automática, ERP e integração com transportadora.

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

Nada de custo sai por aqui: nem custo unitário, nem valor de reposição, nem custo estimado das listas de compras. Também ficam fora o local de armazenamento, o endereço de entrega, o motorista e as anotações. Quem lançou uma movimentação ou avaria sai só com `id` e `name`, e só se ainda for membro da empresa. Textos livres (motivo, descrição) passam pelo mascaramento de telefone, e-mail e documento.

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

## Itens

### `GET /v1/stock/items`

Lista os itens de estoque. [Paginação por cursor](https://developers.festero.com.br/paginacao.md).

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `isActive` | `true` ou `false` | Só os ativos ou só os desativados. |
| `belowMinimum` | `true` ou `false` | Só os abaixo do mínimo ou só os que não estão. |
| `category` | texto | Só os itens desta categoria (texto exato). |
| `updatedSince`, `limit`, `cursor` | | Como nas demais listas. |

Campos principais: `name`, `sku`, `unit` (em minúsculas), `category`, `currentQuantity`, `minimumQuantity`, `isBelowMinimum`, `isActive`, `tracksAvailability`, `isFixedPerEvent` (patrimônio), `quantityPerGuest`, `expirationDate`, `isExpiringSoon` (vence em até 7 dias) e `preferredSupplier`.

### `GET /v1/stock/items/{id}`

Devolve um item pelo identificador, com os mesmos campos. `404` se não existe ou é de outra empresa. Traz `ETag`.

## Movimentações

### `GET /v1/stock/movements`

Lista as entradas, saídas e ajustes.

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `itemId`, `eventId` | GUID | Só as movimentações deste item ou deste evento. |
| `type` | texto | `entry`, `exit` ou `adjustment`. |
| `from`, `to` | data `yyyy-MM-dd` | Período do lançamento (inclusive). |
| `updatedSince`, `limit`, `cursor` | | Como nas demais listas. |

## Reservas para eventos

### `GET /v1/stock/reservations`

Lista o estoque reservado para eventos: `eventId`, `item`, `reservedQuantity`, `consumedQuantity`, `status` (`reserved`, `consumed` ou `cancelled`) e `reservedForDate`. É o que está **reservado**, não a conta de falta ou sobra por evento: esse cálculo (que expande receitas e pacotes) acontece no aplicativo e não é exposto. Filtros: `eventId`, `status`, `updatedSince`, `limit`, `cursor`.

## Disponibilidade por evento

### `GET /v1/stock/availability`

A disponibilidade de estoque de uma festa, com a mesma conta da tela de estoque (expande receitas e pacotes e desconta o que as outras festas reservam nas mesmas datas): para cada insumo, `needed` (o que a festa precisa), `currentQuantity` (em estoque), `reservedByOtherEvents`, `effectiveAvailable` e `shortage` (o que falta, no pior dia da festa), mais `hasShortage` para a festa toda.

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `eventId` | identificador | A festa. Obrigatório. Festa de outra empresa responde 404. |

O cálculo roda em segundo plano no Festero, para as festas não canceladas dos próximos 180 dias, e a resposta traz `calculatedAt` (quando foi calculado) e `isCalculated`. Uma festa alterada é recalculada em cerca de 1 minuto; sem alteração, o cálculo é refeito a cada 15 minutos (a falta também depende das reservas das outras festas). Festa ainda não calculada (recém-criada, passada ou fora da janela) responde `isCalculated: false`, `calculatedAt` nulo e `items` vazio. Empresa com o controle de locação desligado recebe `items` vazio. Sem custo de estoque.

## Kits

### `GET /v1/stock/kits`

Lista os kits (conjuntos de itens movimentados juntos) com `itemCount`. Filtros: `isActive`, `updatedSince`, `limit`, `cursor`.

### `GET /v1/stock/kits/{id}`

Devolve um kit com os `items` (item, unidade e quantidade). Traz `ETag`.

## Avarias

### `GET /v1/stock/damages`

Lista avarias, perdas e faltas (`type`: `lost`, `broken` ou `missing`) com item, quantidade, evento, data, descrição e quem registrou. Não traz o custo de reposição. Filtros: `itemId`, `eventId`, `from`, `to`, `updatedSince`, `limit`, `cursor`.

## Entregas de locação

### `GET /v1/stock/rental-deliveries`

Lista a entrega e a devolução dos eventos de locação: `deliveryDate`, `deliveryTimeWindow`, `returnDate`, `city`, `state`, `status` (`scheduled`, `intransit` ou `returned`) e `carrierName`. Sem endereço, motorista nem anotações. Filtros: `status`, `from`, `to` (data da entrega), `updatedSince`, `limit`, `cursor`.

## Listas de compras

### `GET /v1/stock/shopping-lists`

Lista as listas de compras geradas a partir dos eventos: `name`, `type`, `status` (`draft`, `inprogress`, `completed` ou `cancelled`), `startDate`, `endDate`, `totalItems` e `eventCount`. Filtros: `status`, `updatedSince`, `limit`, `cursor`.

### `GET /v1/stock/shopping-lists/{id}`

Devolve a lista com os `events` atendidos (`eventId` e `guestCount`) e os `items` a comprar: `name`, `category`, `unit`, `quantityNeeded`, `quantityAdjusted`, `quantityWithBuffer` (necessário mais a folga de segurança), `quantityPurchased`, `isPurchased` e `supplier`. Sem custo estimado nem anotações. Traz `ETag`.