Itens

Criação de Item

Este endpoint é utilizado para criar um novo item de produto no catálogo de uma loja. A loja deve ser do tipo Catálogo (store_type = 2).

Payload item não pesável

{
  "sku": "CRCU350LT",
  "name": "Leite de Coco Integral 1L",
  "type": "2",
  "description": "Leite de coco em garrafa, ideal para culinária e bebidas.",
  "order": 1,
  "highlighted": false,
  "status": true,
  "is_alcoholic": false,
  "tags": [
    "VEGAN",
    "ORGANIC"
  ],
  "size_id": "",
  "size_value": 1,
  "value": 15.79,
  "promotional_value": 13.5,
  "inventory_quantity": 50,
  "is_inventory_active": true,
  "images_url": [
    {
      "url": "https://testefiles.aiqfome.com/itens/295948791222c91040f43/DNY5BUz6ZsjiXzaFbwH7CRkipxz3j5xWBL0J7WSa.jpg",
      "order": 1
    }
  ],
  "max_quantity": 3,
  "ean_code": "789119999779",
  "weightable": false,
  "net_weight": 950,
  "gross_weight": 1100,
  "volume": 1000,
  "height": 20,
  "width": 10,
  "depth": 10,
  "cost_value": 8,
  "similar_sku": "COCO1L",
  "brand": "Coco Mania",
  "color": "Branco",
  "flavor": "Coco Natural",
  "voltage": null,
  "attributes": [
    {
      "name": "Temperatura",
      "value": "Frio"
    }
  ],
  "week_days": []
}

Payload de item pesável

{
  "sku": "MACA-ORG-FUJI",
  "name": "Maçã Fuji Orgânica 600g",
  "type": "2",
  "description": "Maçã Fuji fresca e orgânica, vendida a granel.",
  "order": 1,
  "highlighted": false,
  "status": true,
  "is_alcoholic": false,
  "tags": [
    "ORGANIC"
  ],
  "size_id": 4519639,
  "size_value": 600,
  "value": 12.99,
  "promotional_value": 10.99,
  "inventory_quantity": 50,
  "is_inventory_active": true,
  "images_url": [
    {
      "url": "https://testefiles.aiqfome.com/itens/295948791222c91040f43/DNY5BUz6ZsjiXzaFbwH7CRkipxz3j5xWBL0J7WSa.jpg",
      "order": 1
    }
  ],
  "max_quantity": 3,
  "ean_code": "4012345678905",
  "weightable": true,
  "weightable_value": 600,
  "net_weight": 1000,
  "gross_weight": 1050,
  "volume": 0,
  "height": 0,
  "width": 0,
  "depth": 0,
  "cost_value": 6.5,
  "similar_sku": null,
  "brand": "Fazenda Fresca",
  "color": "Vermelho",
  "flavor": "Doce",
  "voltage": null,
  "attributes": [],
  "week_days": []
}

POST

/catalog/v1/{store_id}/item

Detalhamento do Payload

A documentação utiliza os símbolos ✅ (Obrigatório), ❌ (Não Obrigatório) e ⚠️ (Condicional) para lojas do tipo Catálogo.

Campo	Obrigatório	Descrição
sku	❌	Código interno da loja para o produto. Se não for enviado, a API gera um SKU aleatório.
name	✅	Nome do produto. Campo dinâmico para exibição no App.
type	✅	Define o tipo de produto. "1" para manufaturado = o campo EAN não será obrigatório. "2" para industrializado = o campo EAN será obrigatório
description	❌	Descrição básica do produto.
order	❌	Ordenação do item no App.
highlighted	❌	Permite destacar o item no APP. false = desativado true = ativado
status	✅	Status do produto. Define se está ativado (true) ou desativado (false) para venda.
is_alcoholic	✅	Flag para definir se o produto é uma bebida alcoólica. (true ou false). Produtos alcoólicos têm restrições de compra por idade.
tags	✅	Permite definir tags adicionais sobre o tipo de produto (VEGETARIAN, VEGA, ORGANIC, GLUTEN_FREE, SUGAR_FREE, LAC_FREE, ALCOHOLIC_DRINK, NATURAL, ZERO, DIET, COLD, HOT).
size_id	❌	ID da unidade de medida cadastrado (Ex: Unidade, Kg, Litro). Se não enviado, o sistema cria uma unidade padrão (Ex: "unidade"). Consulta Unidades da Loja
size_value	✅	Valor da Unidade de Exibição. O valor que deve ser apresentado na descrição do produto junto à unidade de medida. Regra de Varejo: Para itens não pesáveis (industrializados), se o valor for maior que 1, ele representa a quantidade de itens que vêm dentro da embalagem (Ex: size_value = 12 para uma caixa com 12 unidades de leite). Regra de Compra: Este campo é visual, mas define a base da unidade de compra se weightable for false (compra por unidade/embalagem). Se weightable for ativo, a compra é feita por incremento de peso/volume.
value	❌	Preço regular do item, correspondente à unidade utilizada.
promotional_value	❌	Valor promocional do item. Regra: Deve ser sempre menor que o campo value. O sistema sempre prioriza este valor para exibição e cálculos.
inventory_quantity	❌	Número de itens disponíveis para venda. Se enviado como null, o controle de estoque (is_inventory_active) é automaticamente alterado para false.
is_inventory_active	❌	Define se o produto terá controle de estoque no APP. Valor Default: false (desativado). O App só controla o estoque se este campo for true.
images_url	✅	Array de URLs das imagens do produto. É obrigatório enviar pelo menos uma URL.
images_url[].url	✅	Formatos: png, jpg, jpeg. Tamanhos: Largura [400~1200] x Altura [400~800].
images_url[].order	❌	Ordem de exibição da imagem no carrossel do produto no APP.
max_quantity	❌	Quantidade máxima de itens que o cliente pode comprar por pedido. Regra: Se enviado como 0 (zero) ou não enviado, não há limite máximo.
ean_code	⚠️	EAN (código de barras) do produto. Regra Condicional: É Obrigatório se o campo type for igual a "2" (Industrializado). Máximo de 15 caracteres.
weightable	✅	Produto Pesável/Compra Múltipla. Indica se o item é pesável (true) ou se é vendido em unidades inteiras (false). Lógica de Compra: Se false, o cliente compra 1 unidade, independente do valor em size_value. Se true, o cliente compra em incrementos definidos pelo weightable_value.
weightable_value	⚠️	Incremento de Compra. O valor de cada unidade de compra do produto. Regra: A unidade de medida do weightable_value é a mesma definida pelo size_id do item. Este valor dita o incremento mínimo que o cliente pode adicionar ao carrinho para o item pesável (Ex: +250g, +1Kg). Regra Condicional: Obrigatório se o campo weightable for true.
net_weight	❌	Peso líquido do item (em grama).
gross_weight	❌	Peso bruto do item (em grama).
volume	❌	Volume do item (em centímetro cúbico).
height	❌	Altura do item (em centímetro).
width	❌	Largura do item (em centímetro).
depth	❌	Profundidade do item (em centímetro).
cost_value	❌	Preço de custo do item.
similar_sku	❌	Código similar do item (Store Key Unit).
brand	❌	Marca do item.
color	❌	Cor do item.
flavor	❌	Sabor do item.
voltage	❌	Voltagem do produto.
attributes.name	⚠️	Nome do atributo adicional. Regra Condicional: Obrigatório se o objeto attributes for enviado.
attributes.value	⚠️	Valor do atributo adicional.
week_days	⚠️	Array para definir a disponibilidade do item por dia da semana.
week_days[].week_day	⚠️	Dia da semana: 0 (Segunda) a 6 (Domingo).
week_days[].status	⚠️	Status do item no dia: true (ativo) ou false (inativo). Valor Default: true para todos os dias.

Atualização de Item

Este endpoint é utilizado para atualizar as informações de um item existente no catálogo da loja. O payload aceita qualquer campo da estrutura de criação (nome, preço, estoque, etc.), permitindo atualizações parciais.

PUT

/catalog/v1/{store_id}/item

Detalhamento do Payload

O payload segue a mesma estrutura detalhada no Guia de Criação de Item, mas com as seguintes regras cruciais:

Campo	Obrigatório	Descrição
UUID (Identificador do Item)	✅	O ID único do item que está sendo atualizado. Este campo deve ser incluído no payload da requisição para identificar o recurso.
ean_code	❌	Não pode ser atualizado. Se o ean_code já foi definido durante a criação do item, este campo é imutável e sua alteração será ignorada ou resultará em erro.
size_id	❌	Não pode ser atualizado. O ID da unidade de medida (Ex: Unidade, Kg) é definido no momento da criação e não pode ser alterado posteriormente.
Qualquer Outro Campo	❌	Nenhum outro campo de atributo (como name, status, value, etc.) é obrigatório.
Atualização Parcial	Regra de Negócio	Você pode enviar apenas o(s) campo(s) que deseja atualizar (exemplo: somente status: false), e o restante dos dados do item permanecerá inalterado.
Campos Condicionais	Regra de Validação	Regras condicionais (Ex: a obrigatoriedade de um campo em certa condição) continuam válidas mesmo na atualização.

Atualização Rápida de Inventário

Este endpoint é utilizado para atualizar rapidamente a quantidade em estoque e o status de controle de inventário de um item específico no Catálogo.

PUT

/catalog/v1/{store_id}/item/{uuid}/inventory

Payload Atualização Rápida de Inventário

{
  "inventory_quantity": 19,
  "is_inventory_active": false
}

Detalhamento do Payload

A atualização é realizada no corpo da requisição (payload) e é focada exclusivamente nos campos de inventário.

Campo	Obrigatório	Descrição
uuid (na URL)	✅	O ID único do item de catálogo que está sendo atualizado.
inventory_quantity	✅	Nova quantidade de estoque disponível para o item (número inteiro).
is_inventory_active	✅	Define se o controle de estoque deve estar ativo (true) ou inativo (false) para o item.

Atualização de Status do Item

Este endpoint é utilizado para atualizar o status do item e definir sua disponibilidade por dia da semana no Catálogo.

PUT

/catalog/v1/{store_id}/item/{uuid}/status

Payload Atualização de Status do Item

{
  "status": true,
  "week_days": [
    {
      "week_day": 1,
      "status": false
    }
  ]
}

Detalhamento do Payload

A atualização é realizada no corpo da requisição (payload).

Campo	Obrigatório	Descrição
uuid (na URL)	✅	O ID único do item de catálogo que está sendo atualizado.
status	✅	Status de venda global do item na loja (true para ativo/disponível, false para inativo).
week_days	❌	Array de objetos que define a disponibilidade específica por dia da semana.

Detalhamento da Disponibilidade Semanal (week_days[])

Este objeto permite restringir a venda do item em dias específicos.

Campo	Obrigatório	Descrição
week_day	✅	Número do dia da semana: 0 (Segunda-feira) a 6 (Domingo).
status	✅	Status de venda para o dia específico (true para disponível, false para indisponível).

Atualização de Valor e Oferta

Este endpoint é utilizado para atualizar o preço de venda regular (value) e, opcionalmente, definir ou remover o preço promocional (promotional_value) de um item específico no Catálogo.

PUT

/catalog/v1/{store_id}/item/{uuid}/value

Payload Atualização de Valor e Oferta

{
  "value": 55.5,
  "promotional_value": 39.4
}

Detalhamento do Payload

A atualização é realizada no corpo da requisição (payload).

Campo	Obrigatório	Descrição
uuid (na URL)	✅	O ID único do item de catálogo que está sendo atualizado.
value	✅	O novo preço de venda regular do item (Ex: 55.50).
promotional_value	❌	O preço de venda promocional do item (Ex: 39.40). Use null para remover a oferta.

Deleção de Item

Este endpoint é utilizado para remover permanentemente um item do catálogo da loja.

DELETE

/catalog/v1/{store_id}/item/{uuid}

Detalhamento do Payload

A deleção é realizada utilizando apenas os parâmetros de path da URL:

Parâmetro	Obrigatório	Descrição
store_id	✅	O ID único da loja onde o item será deletado.
uuid	✅	O UUID (ID único) do item que deve ser removido.