Criar e manter produtos do menu

Este guia cobre a criação de um produto com suas variantes, a associação de categorias de modificadores, e as atualizações que você fará depois — visibilidade, estoque e preço.

O fluxo em resumo

Etapa 1 — categorias e cozinhas

Um produto pertence a uma categoria e a uma cozinha; resolva ambos os ids primeiro:

GET /v1/menu/categories

GET /v1/menu/kitchens

Escopo necessário: menu:read. Uma categoria comporta no máximo 50 produtos — criar um além desse limite é rejeitado com catalog_limit_reached_products_per_category.

Etapa 2 — criar o produto

POST /v1/menu/products

Escopo necessário: menu:write. Os preços são decimais, não em unidades mínimas, como em todos os endpoints de menu. Aceita application/json (sem imagem) ou multipart/form-data (campo product = o mesmo JSON como string, campo image = um arquivo jpeg/jpg/png/webp de até 5 MB).

curl -X POST https://public-api.olaclick.app/v1/menu/products \
  -H "Authorization: Bearer olk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "category_id": "6b2f1a04-1c7e-4a2b-9f11-2d8e0b3c4d55",
    "kitchen_id": "9c4f4203-9e2c-403d-88cc-7c0ce9e0f572",
    "name": "Classic Burger",
    "description": "Beef patty, cheddar, lettuce, tomato",
    "variants": [
      {
        "name": "Regular",
        "price": 8.5,
        "original_price": 10,
        "sku": "BURGER-REG"
      }
    ]
  }'

Campo	Obrigatório	Notas
category_id, kitchen_id	Sim	Precisam pertencer à sua empresa; um kitchen_id desconhecido é rejeitado com 422, um category_id desconhecido com 404.
name	Sim	1–191 caracteres.
description	Não	Até 550 caracteres.
visible	Não	Padrão true.
variants	Sim	1–30 itens. Cada um precisa de name, price, original_price (preço de lista) e sku (no máximo 20 caracteres); price não pode exceder original_price. cost e packaging_price são somente-escrita (aceitos, nunca retornados).
modifier_category_ids	Não	Até 100 UUIDs distintos, na ordem de exibição. Omita para um produto sem modificadores.

A resposta é o produto criado com suas variantes e categorias de modificadores — veja a Referência da API REST para o shape completo.

Etapa 3 — adicionar ou atualizar variantes

Um produto pode ganhar mais variantes (tamanhos, apresentações) depois de criado:

POST /v1/menu/products/{id}/variants

{ "name": "Large", "price": 10.5, "original_price": 12, "sku": "BURGER-LRG" }

Escopo necessário: menu:write. Mesmos campos obrigatórios de uma variante no corpo de criação: name, original_price, price, sku.

Para alterar uma variante existente — incluindo seu price, stock ou stock_threshold — use:

PATCH /v1/menu/products/{id}/variants/{variantId}

{ "stock": 40, "stock_threshold": 5 }

Todos os campos são opcionais, mas ao menos um é obrigatório; price ainda não pode exceder original_price quando ambos estão presentes na requisição.

Etapa 4 — sincronizar categorias de modificadores

Liste o que está disponível, depois substitua a associação do produto em uma única chamada:

GET /v1/menu/modifier-categories

PUT /v1/menu/products/{id}/modifier-categories

{ "modifier_category_ids": ["8e2b4d6f-9a0c-4e1b-85d7-9f2a4c6e8b10"] }

Isso substitui as categorias de modificadores do produto por completo, na ordem informada — não é um diff de adicionar/remover. Todo id precisa ser distinto; um array vazio desassocia todas as categorias de modificadores.

Escopo necessário: menu:write.

Etapa 5 — atualizações (visibilidade, estoque, preço)

• Visibilidade, controle de estoque, mensagem para o cliente: PATCH /v1/menu/products/{id} — name, description, visible, stock_enabled, messages_for_customers. Ao menos um campo é obrigatório; a resposta não inclui variants (chame GET /v1/menu/products/{id} para o produto completo).
• Estoque e preço por variante: PATCH /v1/menu/products/{id}/variants/{variantId}, como acima.

Erros de validação comuns

Status	Código	Quando
422	validation_failed (kitchen_not_found)	kitchen_id não pertence à sua empresa.
404	não encontrado	category_id não existe ou pertence a outra empresa (na criação); o produto (e, nos endpoints de variante, a variante) não existe.
422	catalog_limit_reached_products_per_category	A categoria já tem 50 produtos.
422	catalog_limit_reached_variants_per_product	O produto já tem o número máximo de variantes permitido.
422	validation_failed	O price de uma variante excede seu original_price; um corpo de atualização não tem campos; modifier_category_ids tem duplicatas.
422	modifier_category_not_found	Um item de modifier_category_ids não existe ou pertence a outra empresa.
403	insufficient_scope	A API key não tem menu:read ou menu:write.

Fazendo isso pelo servidor MCP

Ferramenta	O que faz
list_categories / list_kitchens	Resolve category_id / kitchen_id
create_product	Cria um produto com suas variantes (somente JSON, sem imagem)
create_product_variant	Adiciona uma variante a um produto existente
update_product_variant	Atualiza uma variante (preço, estoque, etc.)
list_modifier_categories	Encontra modifier_category_ids válidos
sync_product_modifier_categories	Substitui as categorias de modificadores de um produto
list_products / get_product	Navega o catálogo

Escopos necessários: menu:read, menu:write.

Observação: alterar a própria visibilidade/flag de controle de estoque de um produto (PATCH /v1/menu/products/{id}) é exclusivo do REST — ainda não há uma ferramenta MCP para isso.

Exemplos de prompts:

"Crie um produto chamado Classic Burger na categoria 6b2f1a04-1c7e-4a2b-9f11-2d8e0b3c4d55, cozinha 9c4f4203-9e2c-403d-88cc-7c0ce9e0f572, com uma variante a 8.5"

"Defina o estoque para 40 na variante ... do produto ..."

Veja a página do Servidor MCP para todos os parâmetros de cada ferramenta.