Takeat
Versão da documentação
Estoque

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çãoRotaPermissão
Contar insumoPOST /v1/inventory/inputs/:id/countsinputs:stock:write
Contar intermediárioPOST /v1/inventory/intermediaries/:id/countsintermediaries:stock:write
Contar insumos em lotePOST /v1/inventory/inputs/counts/bulkinputs:stock:write
Contar intermediários em lotePOST /v1/inventory/intermediaries/counts/bulkintermediaries: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.

  1. 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.
  2. Consulte GET /v1/inventory/inputs/:id ou GET /v1/inventory/intermediaries/:id, usando o respectivo scope de leitura. Guarde stock_version antes da contagem. As listas cadastrais V1/V2 e ferramentas MCP cadastrais também retornam esse campo; as listas legadas permanecem inalteradas.
  3. 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.

On this page