Itens

Criação de Item Avulso em Categoria

Este endpoint é utilizado para adicionar um novo item a uma categoria de menu existente na loja.

POST

/menu/{store_id}/items

Payload Criação de Item Avulso em Categoria

{
  "menu_category_id": 930099,
  "sku": "PZMARG001",
  "name": "Pizza Margherita",
  "description": "Molho de tomate fresco, mussarela, manjericão e azeite extra virgem.",
  "order": 1,
  "highlighted": true,
  "status": true,
  "tags": [
    "SPICY"
  ],
  "item_sizes": [
    {
      "size_id": 4519941,
      "sku": "PZMARG001P",
      "value": 39.9,
      "promotional_value": 34.9,
      "status": true,
      "inventory_quantity": 25,
      "is_inventory_active": true
    },
    {
      "size_id": 4519942,
      "sku": "PZMARG001M",
      "value": 49.9,
      "promotional_value": null,
      "status": true,
      "inventory_quantity": 40,
      "is_inventory_active": true
    },
    {
      "size_id": 4519943,
      "sku": "PZMARG001G",
      "value": 65.9,
      "promotional_value": null,
      "status": false,
      "inventory_quantity": 0,
      "is_inventory_active": false
    }
  ],
  "item_week_days": [
    {
      "week_day": 1,
      "status": true
    },
    {
      "week_day": 6,
      "status": true
    }
  ]
}

Detalhamento do Payload

Objeto Principal

O payload utiliza a maioria dos campos do objeto items[] detalhado no Criação de Categoria de Menu, com a adição do campo menu_category_id para especificar a categoria de destino.

Campo	Obrigatório	Descrição
menu_category_id	✅	ID da Categoria na qual o novo item deve ser inserido (Ex: 930100).
sku	❌	SKU ou código interno do item.
name	✅	Nome do item.
description	❌	Descrição detalhada do item para o cliente.
order	❌	Ordem de exibição do item na categoria.
highlighted	❌	Item em destaque (true) para o cliente.
status	✅	Status de exibição/venda do item (true ou false).
image_url	❌	Formatos: png, jpg, jpeg. Tamanhos: Largura [400~1200] x Altura [400~800].
tags	✅	Array de tags adicionais (Ex: ["SPICY"]).
item_sizes	✅	Array de objetos com os tamanhos que este item específico aceita (incluindo preço e estoque).
item_week_days	❌	Disponibilidade do item de acordo com o dia da semana.

Detalhamento dos Sub-objetos

As estruturas internas, como item_sizes[] (preço, estoque) e item_week_days[] (disponibilidade), seguem exatamente o detalhamento fornecido na Criação de Categoria de Menu.

Campos em item_sizes[]

Campo	Obrigatório	Descrição
item_sizes[].size_id	✅	ID do tamanho (Ex: ID do "P" ou "M"). Consulta os ID’s pelo endpoint de Consulta de Menu.
item_sizes[].sku	❌	SKU específico para a combinação Item + Tamanho.
item_sizes[].value	✅	Preço de venda regular.
item_sizes[].status	❌	Status de venda para este tamanho.
item_sizes[].promotional_value	❌	Valor promocional.
item_sizes[].inventory_quantity	❌	Quantidade de estoque do item para este tamanho.
item_sizes[].is_inventory_active	❌	Define se o controle de estoque está ativo (true ou false).

Campos em item_week_days[]

Campo	Obrigatório	Descrição
item_week_days[].week_day	✅	Número do dia da semana: 0 (Segunda-feira) a 6 (Domingo).
item_week_days[].status	✅	Status do item no dia: true (ativo/disponível) ou false (inativo/não disponível).

Atualização de Item

Este endpoint é utilizado para modificar os detalhes de um item existente em uma categoria de menu. Quase todos os campos da estrutura do item podem ser atualizados.

PUT

/menu/{store_id}/items/{uuid}

Payload Atualização de Item

{
  "sku": "TESTE UPDATE",
  "name": "Pizza Margherita UPDATE",
  "description": "Molho de tomate fresco, mussarela, manjericão e azeite extra virgem. UPDATE",
  "order": 1,
  "highlighted": true,
  "excluded": null,
  "status": true,
  "image_url": "https://testefiles.aiqfome.com/itens/295948791222c91040f43/water_bottle.jpg",
  "tags": [
    "SPICY"
  ],
  "item_sizes": [
    {
      "id": 4519950,
      "sku": "PZMARG001P",
      "value": 89.9,
      "promotional_value": 77.9,
      "status": true,
      "inventory_quantity": 30,
      "is_inventory_active": true
    },
    {
      "id": 4519951,
      "sku": "PZMARG001M",
      "value": 104.9,
      "promotional_value": 100,
      "status": false,
      "inventory_quantity": 40,
      "is_inventory_active": true
    },
    {
      "id": 4519952,
      "sku": "PZMARG001G",
      "value": 210.9,
      "promotional_value": 188,
      "status": true,
      "inventory_quantity": 0,
      "is_inventory_active": false
    }
  ],
  "item_week_days": [
    {
      "week_day": 1,
      "status": true
    },
    {
      "week_day": 6,
      "status": true
    }
  ]
}

Detalhamento do Payload

Objeto Principal

A atualização é realizada no corpo da requisição (payload). É possível enviar apenas os campos que se deseja alterar (atualização parcial).

Campo	Obrigatório	Descrição
uuid (na URL)	✅	O ID único do item que está sendo atualizado.
sku	❌	SKU (código interno) do item.
name	❌	Nome do item.
description	❌	Descrição detalhada do item.
order	❌	Ordem de exibição do item na categoria.
highlighted	❌	Item em destaque (true) para o cliente.
excluded	❌	Campo para exclusão. (Geralmente utilizado internamente ou com valor null).
status	❌	Status de exibição/venda do item (true ou false).
image_url	❌	URL da imagem principal do item.
tags	✅	Tags adicionais (Ex: ["SPICY"]).
item_sizes	❌	Array de objetos com os tamanhos que este item aceita. Regra: Se enviado, sobrescreve completamente a lista de tamanhos do item.
item_week_days	❌	Disponibilidade do item por dia da semana. Se enviado, sobrescreve a configuração anterior.

Detalhamento dos Tamanhos (item_sizes[])

Ao enviar o item_sizes, certifique-se de incluir o ID do tamanho que você está atualizando (se o tamanho já existia no item) para evitar duplicação ou criação de novos registros.

Campo	Obrigatório	Descrição
item_sizes[].id	✅ Condicional	ID do Registro do Tamanho (Se estiver atualizando um tamanho existente).
item_sizes[].size_name	❌	Nome do tamanho (Ex: "P", "M").
item_sizes[].sku	❌	SKU específico para a combinação Item + Tamanho.
item_sizes[].value	❌	Preço de venda regular.
item_sizes[].promotional_value	❌	Valor promocional.
item_sizes[].inventory_quantity	❌	Quantidade de estoque do item para este tamanho.
item_sizes[].is_inventory_active	❌	Define se o controle de estoque está ativo (true ou false).

Consulta de Detalhes do Item

Este endpoint é utilizado para consultar os detalhes completos de um item específico do cardápio, incluindo preços por tamanho, status de estoque e grupos de modificadores exclusivos.

GET

/menu/{store_id}/items/{uuid}

Payload Consulta de Detalhes do Item

{
  "data": {
    "uuid": "de8aedd7-5f75-34f2-9e9c-640248829f57",
    "sku": "PZ0002",
    "name": "Pizza Vegetariana",
    "description": "Mussarela, vegetais frescos e azeite.",
    "order": 3,
    "highlighted": false,
    "excluded": false,
    "status": "AVAILABLE",
    "blocked_until_tomorrow": false,
    "comments": "|0|",
    "tags": [
      {
        "id": 0,
        "name": "SPICY"
      }
    ],
    "item_sizes": [
      {
        "item_size_id": 37727031,
        "size_id": 4519950,
        "name": "P",
        "sku": "PZ0002P",
        "status": "AVAILABLE",
        "flavors_amount": 1,
        "additional_max_limit": 5,
        "value": "40.00",
        "promotional_value": null,
        "inventory_quantity": null,
        "is_inventory_active": false,
        "daily_sale": null
      },
      {
        "item_size_id": 37727032,
        "size_id": 4519951,
        "name": "M",
        "sku": "PZ0002M",
        "status": "AVAILABLE",
        "flavors_amount": 2,
        "additional_max_limit": 8,
        "value": "50.00",
        "promotional_value": null,
        "inventory_quantity": null,
        "is_inventory_active": false,
        "daily_sale": null
      },
      {
        "item_size_id": 37727033,
        "size_id": 4519952,
        "name": "G",
        "sku": "PZ0002G",
        "status": "AVAILABLE",
        "flavors_amount": 2,
        "additional_max_limit": 10,
        "value": "60.00",
        "promotional_value": null,
        "inventory_quantity": null,
        "is_inventory_active": false,
        "daily_sale": null
      },
      {
        "item_size_id": 37727038,
        "size_id": 4519953,
        "name": "GG",
        "sku": "6936dd6a1c90c",
        "status": "BLOCKED",
        "flavors_amount": 2,
        "additional_max_limit": 2,
        "value": null,
        "promotional_value": null,
        "inventory_quantity": null,
        "is_inventory_active": false,
        "daily_sale": null
      },
      {
        "item_size_id": 37727041,
        "size_id": 4519954,
        "name": "GG",
        "sku": "6936df785845e",
        "status": "BLOCKED",
        "flavors_amount": 2,
        "additional_max_limit": 2,
        "value": null,
        "promotional_value": null,
        "inventory_quantity": null,
        "is_inventory_active": false,
        "daily_sale": null
      }
    ],
    "item_week_days": [],
    "mandatory_groups": [],
    "daily_sale": null,
    "menu_category_id": 930103
  }
}

Resposta de Sucesso (Status Code 200)

O retorno é um objeto na chave data contendo todos os detalhes do item solicitado.

Campo Principal	Descrição
uuid	ID único do item.
sku	SKU ou código interno do item.
name	Nome do item (Ex: "Pizza do Chef").
description	Descrição detalhada do item.
order	Ordem de exibição do item na categoria.
highlighted	Indica se o item está em destaque (true ou false).
status	Status de exibição/disponibilidade do item. Valores: "AVAILABLE" ou "BLOCKED".
blocked_until_tomorrow	Indica se o item está bloqueado para alteração até o dia seguinte (true ou false).
tags	Array de tags associadas ao item (Ex: SPICY).
menu_category_id	ID da categoria à qual este item pertence.
daily_sale	Objeto contendo as regras de promoção diária exclusivas deste item (pode ser null).
mandatory_groups	Array contendo os grupos de modificadores que são obrigatórios apenas para este item.
item_sizes	Array detalhado dos tamanhos que o item aceita (preços, estoque, etc.).

Detalhamento dos Tamanhos (item_sizes[])

Esta é a seção crítica, pois contém a precificação, modulação e controle de estoque por tamanho.

Campo	Descrição
item_size_id	ID único do registro de preço/tamanho deste item.
size_id	ID do tamanho base definido na categoria (Ex: ID do 'P', 'M' ou 'G').
name	Nome do tamanho (Ex: "P", "M").
sku	SKU específico para a combinação Item + Tamanho.
status	Status de venda para este tamanho. Valor: "AVAILABLE" ou "BLOCKED".
flavors_amount	Quantidade de sabores permitida para este tamanho.
additional_max_limit	Limite máximo de adicionais opcionais permitidos.
value	Preço de venda regular do item para este tamanho (em string de Real, Ex: "35.00").
promotional_value	Valor promocional (em string de Real, Ex: "30.00").
inventory_quantity	Quantidade de estoque do item para este tamanho (pode ser null).
is_inventory_active	Indica se o controle de estoque está ativo (true ou false).
daily_sale	Promoção diária aplicada apenas a este tamanho (pode ser null).

Detalhamento dos Mandatórios (mandatory_groups[])

Estes grupos de modificadores são obrigatórios somente para este item (não herdados da categoria).

Campo	Descrição
mandatory_groups[].id	ID único do grupo obrigatório.
mandatory_groups[].name	Nome do grupo (Ex: "Tipo de Base").
mandatory_groups[].min_limit	Mínimo de opções que o cliente deve selecionar.
mandatory_groups[].max_limit	Máximo de opções que o cliente pode selecionar.
mandatory_groups[].mandatory_items	Array dos itens/opções que pertencem a este grupo. Inclui id, sku, name, value e status.

Consulta de Itens por Categoria

Este endpoint é utilizado para listar todos os itens pertencentes a uma categoria específica do cardápio.

GET

/menu/{store_id}/items

Payload Consulta de Itens por Categoria

{
  "data": [
    {
      "uuid": "9a6ed996-462e-3b89-b5ca-97274eeb57d4",
      "sku": "TESTE UPDATE",
      "name": "Pizza Margherita UPDATE",
      "description": "Molho de tomate fresco, mussarela, manjericão e azeite extra virgem. UPDATE",
      "order": 1,
      "status": "BLOCKED",
      "blocked_until_tomorrow": false,
      "tags": [
        {
          "id": 0,
          "name": "SPICY"
        }
      ],
      "menu_category_id": 930103
    },
    {
      "uuid": "39536367-4042-329b-8e57-c4c4ccc8f9a4",
      "sku": "PZ0001",
      "name": "Pizza do Chef (Em Oferta)",
      "description": "Calabresa, bacon, cebola e toque de pimenta.",
      "order": 2,
      "status": "AVAILABLE",
      "blocked_until_tomorrow": false,
      "tags": [
        {
          "id": 0,
          "name": "SPICY"
        }
      ],
      "menu_category_id": 930103
    },
    {
      "uuid": "de8aedd7-5f75-34f2-9e9c-640248829f57",
      "sku": "PZ0002",
      "name": "Pizza Vegetariana",
      "description": "Mussarela, vegetais frescos e azeite.",
      "order": 3,
      "status": "AVAILABLE",
      "blocked_until_tomorrow": false,
      "tags": [
        {
          "id": 0,
          "name": "SPICY"
        }
      ],
      "menu_category_id": 930103
    }
  ],
  "links": {
    "first": "http://purple-box.aiqfome.com/alfredo/menu/53852/categories/930103/items?page=1",
    "last": null,
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "path": "http://purple-box.aiqfome.com/alfredo/menu/53852/categories/930103/items",
    "per_page": 15,
    "to": 3
  }
}

Resposta de Sucesso (Status Code 200)

O retorno é um objeto que segue o padrão de paginação (implícito no contexto total da API), contendo um array na chave data com a lista dos itens.

Detalhamento dos Campos do Item (data[])

Campo	Descrição
uuid	ID único do item.
sku	SKU ou código interno do item.
name	Nome do item (Ex: "Pizza Margherita").
description	Descrição detalhada do item.
order	Ordem de exibição do item na categoria.
status	Status de exibição/disponibilidade do item. Valores: "AVAILABLE" ou "BLOCKED".
blocked_until_tomorrow	Indica se o item está bloqueado para alteração até o dia seguinte (true ou false).
menu_category_id	ID da categoria à qual este item pertence.
tags	Array de tags associadas ao item.
tags[].id	ID da tag.
tags[].name	Nome da tag (Ex: "SPICY").

Lembrete de Ação

Para obter detalhes completos do item (incluindo preço por tamanho, estoque e mandatórios), utilize o endpoint

GET

/menu/{store_id}/items/{uuid}

Exclusão de Item

Este endpoint é utilizado para remover permanentemente um item do cardápio da loja.

DELETE

/menu/{store_id}/items/{uuid}

Detalhamento do Payload

A exclusão é realizada diretamente através da URL, não sendo necessário um corpo (payload).

Parâmetro	Tipo	Obrigatório	Descrição
store_id (na URL)	Integer	✅	O ID da loja.
uuid (na URL)	String	✅	O ID único do item de cardápio a ser excluído.