Fichas técnicas

A gestão de fichas técnicas usa contratos novos sob /v1/inventory. As leituras legadas /v1/inputs e /v1/intermediaries continuam com os campos originais; para obter IDs editáveis, use as novas listagens.

Autenticação e ordem de integração

1. Conceda à chave/app somente os escopos necessários. Chaves e instalações existentes não recebem permissões novas automaticamente. Após editar os escopos, troque a chave por outro token ou reconecte o aplicativo OAuth.
2. Use Authorization: Bearer <access_token>. A sessão autenticada do próprio restaurante também é aceita. Uma chave tk_ não chama estas rotas diretamente.
3. Consulte os insumos e intermediários para obter seus IDs. Cadastre primeiro os insumos, depois os intermediários, das dependências para as receitas que as utilizam. IDs de produtos e complementos vêm de seus catálogos existentes.
4. Leia a ficha atual e envie todos os ingredientes desejados no PUT. Envie expected_updated_at com o updated_at lido para detectar alterações concorrentes.

Um parceiro com vários restaurantes envia ?restaurant_id=<id autorizado>. Uma sessão humana fica limitada ao restaurante assinado; não pode trocar de loja.

Cadastros

GET /v1/inventory/inputs e GET /v1/inventory/intermediaries retornam { items, total, count, remaining, offset, limit }. O limite é 100, com ordenação por nome e ID. Cada recurso também tem GET /:id, POST e PUT /:id.

Os cadastros expõem id, restaurant_id, name, unidade, quantidade, unitary_price, total_value, ideal_stock, minimum_stock, is_master, is_multistore, is_multistore_child, created_at e updated_at. yield e recipe ficam nulos para insumos.

Criação exige name e unidade e inicia com saldo zero. Insumos aceitam unitary_price não negativo, com até duas casas, padrão "0.00". Intermediários exigem também a ficha inicial: yield, inputs e intermediaries. Seus custos são calculados; não aceitam unitary_price de entrada.

O PUT cadastral é parcial: aceita nome, unidade, limites mínimo/ideal e expected_updated_at; insumos também aceitam custo. Limites podem ser limpos com null. A unidade é texto livre de até 50 caracteres e somente muda se não houver saldo nem vínculos. Não há rotas de exclusão ou conversão.

Operações em lote

Os POSTs de /v1/inventory/inputs e /v1/inventory/intermediaries aceitam um objeto ou um array de 1 a 100 cadastros. Um objeto retorna um objeto; um array retorna um array na mesma ordem enviada.

Para editar vários cadastros ou fichas na mesma transação, use:

Esses PUTs aceitam um objeto ou um array de 1 a 100 alterações, com id em cada item, e sempre retornam um array na ordem enviada. Os demais campos e escopos são os mesmos da operação individual. IDs repetidos são rejeitados.

[
  { "id": 123, "unitary_price": "12.50", "expected_updated_at": "2026-10-01T12:00:00.000Z" },
  { "id": 456, "minimum_stock": "5.00", "expected_updated_at": "2026-10-01T12:00:00.000Z" }
]

Cada lote é atômico: uma versão desatualizada, ingrediente inválido, ciclo ou cadastro protegido desfaz todas as alterações daquele pedido. A verificação de versão é individual. Os custos dependentes são recalculados uma vez com o estado final do lote. Lotes de fichas ou criação de intermediários admitem até 2000 ingredientes no total, somando inputs e intermediaries de todos os itens. Divida cargas maiores em lotes; lotes diferentes têm transações independentes. Se a conexão cair sem resposta, consulte os cadastros antes de reenviar, especialmente em criações.

Composição completa

• GET|PUT /v1/inventory/intermediaries/:id/technical-sheet
• GET|PUT /v1/products/:id/technical-sheet
• GET|PUT /v1/complements/:id/technical-sheet

Arrays inputs e intermediaries são obrigatórios, com até 1000 ingredientes cada. Cada item recebe { id, quantidade }. Arrays vazios removem os ingredientes editáveis. O insumo mestre do produto aparece em master_input e permanece inalterado; não o inclua em inputs.

Quantidades são strings positivas com ponto, sem separador de milhar ou notação exponencial, com até 12 casas decimais. O rendimento aceita até duas casas. IDs repetidos, ingredientes cancelados, referências de outra loja e ciclos entre intermediários são rejeitados.

Intermediários: quantidades por receita/lote

{
  "yield": "10.00",
  "recipe": "Misturar os ingredientes.",
  "inputs": [{ "id": 123, "quantidade": "2.00" }],
  "intermediaries": [{ "id": 456, "quantidade": "1.00" }],
  "expected_updated_at": "2026-09-29T12:00:00.000Z"
}

Esta receita rende 10 unidades da unidade de medida do intermediário. O insumo 123 usa 2 unidades da sua própria unidade de medida no lote inteiro. O banco armazena 0,2 por unidade produzida; a consulta retorna a quantidade do lote. A precisão interna da divisão é de 12 casas; quantidades que arredondem para zero são rejeitadas. Alterar o rendimento com os mesmos ingredientes altera o consumo por unidade, sem produzir ou consumir estoque.

recipe pode ser texto de até 1000 caracteres ou null. Como o PUT substitui a ficha completa, omitir recipe também limpa o preparo.

Produtos e complementos: quantidades por unidade vendida

{
  "inputs": [{ "id": 123, "quantidade": "0.10" }],
  "intermediaries": [{ "id": 456, "quantidade": "0.25" }]
}

Não envie yield nem recipe neste caso. A resposta identifica quantity_basis: "sale_unit"; intermediários usam "batch". A resposta inclui ingredientes identificados com nome, unidade, quantidade e custo unitário, além de cost para o lote ou unidade vendida.

Custos, proteção e erros

Cada escrita usa uma transação serializável. A substituição reconcilia os vínculos: repetir o mesmo conteúdo não duplica ingredientes. A mudança de custo de um insumo ou da receita recalcula intermediários dependentes em ordem de dependência, com arredondamento monetário de duas casas por intermediário. A valorização do saldo é atualizada, mas sua quantidade e os preços de venda permanecem intactos. Alterações manuais de custo geram histórico com quantidade zero; composição não gera consumo, devolução, produção ou tarefas de compra.

Cadastros mestres e multiloja podem ser consultados, mas sua edição fica bloqueada. As escritas de composição não modificam a configuração de cadastros multiloja; seus custos derivados podem acompanhar alterações de ingredientes locais.

Em 409, consulte o recurso novamente e revise a alteração antes de reenviar. expected_updated_at verifica a data do proprietário; edições legadas que alterem somente vínculos sem atualizar essa data não são detectadas por esse campo. Não há neste conjunto produção, inventário, transferências ou escrita via MCP.