Takeat
Versão da documentação
Estoque

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

  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.

RecursoLeituraEscrita
Insumosinputs:readinputs:write
Intermediários e suas fichasintermediaries:readintermediaries:write
Ficha de produtoproducts:readproducts:write
Ficha de complementocomplements:readcomplements: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çãoRotaPermissão
Trocar o centro de custo de um insumoPUT /v1/inventory/inputs/:id/cost-centerinputs:write
Trocar em lotePUT /v1/inventory/inputs/cost-centers/bulkinputs: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çãoMétodo e caminho
Cadastros de insumosPUT /v1/inventory/inputs/bulk
Centros de custo de insumosPUT /v1/inventory/inputs/cost-centers/bulk (corpo { "items": [...] })
Cadastros de intermediáriosPUT /v1/inventory/intermediaries/bulk
Fichas de intermediáriosPUT /v1/inventory/intermediaries/technical-sheets/bulk
Fichas de produtosPUT /v1/products/technical-sheets/bulk
Fichas de complementosPUT /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-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.

StatusSignificado
400Payload inválido, ingrediente repetido, quantidade/rendimento inválido ou ciclo
401/403Credencial, audiência, escopo ou restaurante não autorizado
404Cadastro/ingrediente ausente, cancelado ou pertencente a outra loja
409inventory_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.

On this page