Documentação
Fichas técnicas
Cadastro de insumos e intermediários e composição de receitas pela API externa.
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
- 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.
- Use
Authorization: Bearer <access_token>. A sessão autenticada do próprio restaurante também é aceita. Uma chavetk_não chama estas rotas diretamente. - 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.
- Leia a ficha atual e envie todos os ingredientes desejados no PUT. Envie
expected_updated_atcom oupdated_atlido 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.
| Recurso | Leitura | Escrita |
|---|---|---|
| Insumos | inputs:read | inputs:write |
| Intermediários e suas fichas | intermediaries:read | intermediaries:write |
| Ficha de produto | products:read | products:write |
| Ficha de complemento | complements:read | complements:write |
Cadastros
GET /v1/inventory/inputs e GET /v1/inventory/intermediaries retornam
{ items, total, count, remaining, offset, limit } na V1. As listagens
GET /v2/inventory/inputs e GET /v2/inventory/intermediaries retornam
{ data, pagination }; continue com pagination.next.offset até
pagination.has_more=false. 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, cash_flow_category_subcategory_id,
created_at e updated_at. O centro de custo fica nulo para intermediários.
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", e
cash_flow_category_subcategory_id opcional.
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.
Centro de custo dos insumos
O centro de custo define em qual categoria financeira o insumo entra. Só insumos
com centro de custo do tipo insumos contam no saldo de estoque. Consulte os IDs
em GET /v1/financial/cost-centers
(financial:read).
| Operação | Rota | Permissão |
|---|---|---|
| Trocar o centro de custo de um insumo | PUT /v1/inventory/inputs/:id/cost-center | inputs:write |
| Trocar em lote | PUT /v1/inventory/inputs/cost-centers/bulk | inputs:write |
{ "cash_flow_category_subcategory_id": 44, "expected_updated_at": "2026-11-01T10:00:00.000Z" }null remove o centro de custo. O lote recebe { "items": [{ "id": 123, "cash_flow_category_subcategory_id": 44 }] } com 1 a 100 insumos distintos,
aplicados inteiros ou nada, e responde { "items": [...] }.
Estas rotas mudam somente o centro de custo. Por isso, ao contrário do PUT
cadastral, aceitam insumos master e insumos que a multilojas replicou para a
loja (is_multistore_child: true): cada loja tem os próprios centros de custo.
O cadastro da rede (is_multistore: true) continua com 409 inventory_managed_record, porque a propagação para as lojas é feita pela gestão
da multilojas. Uma edição posterior do insumo pela rede, no painel, pode
substituir o centro de custo da loja.
Um centro de custo que não existe na loja retorna 404 inventory_cost_center_not_found.
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:
| Operação | Método e caminho |
|---|---|
| Cadastros de insumos | PUT /v1/inventory/inputs/bulk |
| Centros de custo de insumos | PUT /v1/inventory/inputs/cost-centers/bulk (corpo { "items": [...] }) |
| Cadastros de intermediários | PUT /v1/inventory/intermediaries/bulk |
| Fichas de intermediários | PUT /v1/inventory/intermediaries/technical-sheets/bulk |
| Fichas de produtos | PUT /v1/products/technical-sheets/bulk |
| Fichas de complementos | PUT /v1/complements/technical-sheets/bulk |
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-sheetGET|PUT /v1/products/:id/technical-sheetGET|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.
| Status | Significado |
|---|---|
| 400 | Payload inválido, ingrediente repetido, quantidade/rendimento inválido ou ciclo |
| 401/403 | Credencial, audiência, escopo ou restaurante não autorizado |
| 404 | Cadastro/ingrediente ausente, cancelado ou pertencente a outra loja |
| 409 | inventory_update_conflict, cadastro gerenciado ou unidade em uso |
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.
Contagens de estoque via integração
inputs:stock:write e intermediaries:stock:write autorizam registrar contagens físicas e alterar saldo real, individualmente ou em lote. Exigem access token de integração, versão atual do saldo e idempotência. Não são concedidos por inputs:write/intermediaries:write nem por sessões humanas. Credenciais existentes precisam de seleção explícita e novo token/consentimento.
Veja contagens de estoque para rotas, ferramentas MCP, payloads e recuperação de conflitos. O cadastro e as fichas técnicas continuam preservando quantidades.