Aparência
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.
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
Itens
GET /v1/stock/items
Lista os itens de estoque. Paginação por cursor.
| 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.