Documentação
Estoque
Consultar estoque e registrar contagens físicas de insumos e intermediários.
GET /v1/inputs exige inputs:read; GET /v1/intermediaries exige
intermediaries:read. A sessão autenticada do restaurante também é aceita,
sempre vinculada ao restaurante assinado. Chaves tk_ não acessam dados
diretamente: troque a chave por um access token OAuth.
Na V1, as rotas mantêm inputs ou intermediaries, total, count,
remaining, offset e limit. As versões /v2/inputs e /v2/intermediaries
retornam { data, pagination }. O limite é sempre 100.
Use pagination.next.offset na próxima consulta e mantenha os filtros até
pagination.has_more=false. pagination.total informa o total filtrado.
Registros cancelados ficam fora da consulta. A ordem é nome crescente, com ID
como desempate. Veja o formato comum de paginação.
Os campos quantidade, ideal_stock e minimum_stock preservam o texto
armazenado; estoques ideal e mínimo podem ser nulos. total_value e
unitary_price são strings com duas casas decimais. Valores inválidos já
armazenados no legado preservam a string NaN, sem converter para zero. Insumos incluem
is_master e cash_flow_category_subcategory no formato Categoria: Subcategoria
ou uma string vazia quando não há vínculo. Nenhuma rota expõe escrita ou
exclusão; as respostas legadas não incluem o ID do registro.
O offset segue o legado: ausente, inválido ou negativo vira zero, e um prefixo
inteiro é aceito (12abc vira 12). Valores acima de 2147483647 retornam 400.
Não acrescente limit: o tamanho da página é fixo.
A gestão de fichas técnicas usa novos contratos
/v1/inventory e rotas technical-sheet de produtos/complementos.
A V1 mantém os campos e envelopes anteriores; as coleções da V2 usam o formato comum de paginação.
Contagem física e alteração de saldo
Implementação ESTR-1112: confirme a implantação da migration e da external-api antes de usar estas operações em um ambiente. As rotas cadastrais continuam preservando saldo.
| Operação | Rota | Permissão |
|---|---|---|
| Contar insumo | POST /v1/inventory/inputs/:id/counts | inputs:stock:write |
| Contar intermediário | POST /v1/inventory/intermediaries/:id/counts | intermediaries:stock:write |
| Contar insumos em lote | POST /v1/inventory/inputs/counts/bulk | inputs:stock:write |
| Contar intermediários em lote | POST /v1/inventory/intermediaries/counts/bulk | intermediaries:stock:write |
Essas rotas aceitam somente access tokens de integração com permissão explícita. inputs:write e intermediaries:write continuam restritos ao cadastro/custo/composição. Sessões humanas e chaves tk_ enviadas diretamente não autorizam contagens.
- Habilite o novo scope na chave/app. Para OAuth/MCP, reconecte e aprove o consentimento atualizado; para chaves, faça nova troca por access token. Refresh de consentimento antigo não concede novos scopes.
- Consulte
GET /v1/inventory/inputs/:idouGET /v1/inventory/intermediaries/:id, usando o respectivo scope de leitura. Guardestock_versionantes da contagem. As listas cadastrais V1/V2 e ferramentas MCP cadastrais também retornam esse campo; as listas legadas permanecem inalteradas. - Faça a contagem física e envie a quantidade absoluta na unidade do cadastro, com
Idempotency-Keyúnica por operação:
{
"quantidade": "8.500",
"expected_stock_version": "42",
"counted_at": "2026-10-28T14:00:00Z",
"reason": "Contagem física pelo aplicativo"
}quantidade aceita zero e até 12 casas decimais. counted_at exige fuso e apenas registra quando ocorreu a contagem; o saldo e o histórico são alterados no momento da aplicação, sem reconstrução retroativa. A justificativa tem de 1 a 255 caracteres e não pode conter apenas espaços. Idempotency-Key tem de 1 a 200 caracteres ASCII visíveis, sem espaços. Campos extras e IDs repetidos no lote são rejeitados antes da escrita. Lotes usam { "items": [{ "id": 123, ...camposDaContagem }] }, de 1 a 100 IDs distintos, e são aplicados integralmente.
A resposta 201 inclui count_id, history_id, id, restaurant_id, unidade, previous_quantity, quantidade, quantity_delta, unitary_price, total_value, stock_version, counted_at e applied_at. Lotes retornam { "items": [...] } na ordem enviada. Quantidades, valores e versões são strings.
Se uma movimentação ocorrer desde a leitura, a API retorna 409 / inventory_update_conflict: consulte novamente e revise a contagem antes de criar outro pedido. Nunca substitua a versão e reenvie automaticamente. Itens master/multiloja retornam 409 / inventory_managed_record; itens inexistentes ou de outra loja retornam 404.
Para recuperar uma resposta perdida, reenvie o pedido idêntico com a mesma chave. A API retorna o resultado original sem duplicar saldo ou histórico. Outra contagem com a mesma chave retorna 409 / inventory_idempotency_conflict. O espaço de idempotência é compartilhado entre HTTP e MCP para a mesma identidade e restaurante.
No MCP, use register_inventory_input_count, register_inventory_intermediary_count, register_inventory_input_counts ou register_inventory_intermediary_counts. As ferramentas individuais recebem id e os campos acima; as de lote recebem items. Todas recebem idempotency_key e restaurant_id quando necessário. Alteram saldo real e exigem os mesmos scopes. O registro MCP padrão continua somente leitura.
Contar intermediários não produz estoque nem consome ingredientes. Custos unitários, composição e preços de venda são preservados; a valorização do saldo usa o custo vigente. Contagens sem diferença também geram histórico e auditoria.
Baixar coleção Postman de contagens. As variáveis começam vazias; use somente uma loja de teste durante a validação.