Produtos
Produtos
Crie e atualize produtos com suporte para filiais, variações e modificadores.
POST
Você pode criar ou atualizar produtos em massa pelo SKU. Se um produto com o SKU especificado já existir, ele é atualizado; caso contrário, é criado. Os produtos podem ser atribuídos a uma filial, ter múltiplas variações e grupos de modificadores.
string
obrigatório
O ID da sua loja no Jelou Shop.
object[]
obrigatório
Lista de produtos a criar ou atualizar (máx. 500 por requisição).
Campos do produto
Cada objeto dentro deresources aceita os seguintes campos:
string
obrigatório
Identificador único do produto (máx. 255 caracteres).
string
obrigatório
Nome do produto (máx. 255 caracteres).
number
obrigatório
Preço do produto (mín. 0).
string
Descrição do produto.
boolean
padrão:"true"
Indica se o preço inclui impostos.
number
Taxa de imposto individual do produto (entre
0 e 100). Exemplo: 15 para 15%, 12 para 12%. Aplica-se apenas quando enable_per_product_tax está ativo na configuração da loja. Se não for enviado ou for 0, a taxa global da loja é usada.boolean
padrão:"true"
Status do produto (ativo/inativo).
string
padrão:"unlimited"
Tipo de inventário:
limited ou unlimited.number
Quantidade disponível. Aplica-se apenas quando
stock_type é limited.string
URL do produto na sua loja (máx. 2048 caracteres).
string
Tipo de desconto:
value (valor fixo) ou percentage.number
Valor do desconto (mín. 0).
string[]
Lista de nomes de categorias. São criadas automaticamente se não existirem.
string[]
Lista de URLs públicas de imagens do produto.
boolean
padrão:"false"
Habilita um campo de nota na página de detalhe do produto, permitindo que o cliente adicione um comentário ao adicionar o produto ao carrinho (ex.: “Sem cebola”, “Embrulhar para presente”).
string
Texto placeholder exibido no campo de nota (máx. 255 caracteres). Se não especificado, um texto genérico padrão é usado.
string
Código da filial à qual o produto é atribuído. A filial deve já existir.
object[]
Lista de características (ficha técnica) do produto.
boolean
padrão:"false"
Controla como as variações são sincronizadas. Com
false (padrão), as variações são atualizadas ou criadas por SKU e as existentes que não estiverem no payload são mantidas. Com true, as variações que não estiverem no payload são removidas.object[]
Lista de variações do produto.
object[]
Grupos de modificadores do produto (adicionais). Comum em delivery de comida (ex.: “Escolha sua Bebida”, “Escolha seus Molhos”). Se o campo estiver ausente, os modificadores existentes são preservados. Se for um array vazio
[], todos os modificadores são excluídos. Se tiver dados, os modificadores são completamente substituídos.Os modificadores são armazenados no produto e retornados automaticamente em todos os endpoints que retornam produtos.
Exemplo completo
Este exemplo cria três produtos: uma camiseta com variações de tamanho, uma calça simples e uma pizza com grupos de modificadores.Substitua
{app_id} pelo ID da sua loja e YOUR_API_KEY pela sua chave de API.Comportamento
Processamento assíncrono (padrão)
Processamento assíncrono (padrão)
O endpoint retorna
202 Accepted imediatamente. Os produtos são processados em segundo plano.Processamento síncrono (X-Sync)
Processamento síncrono (X-Sync)
Envie o header
X-Sync: true para processar de forma síncrona e receber o resultado por produto na mesma resposta (200 OK). Nesse modo o máximo é de 50 produtos por requisição.200 OK
Filial inexistente
Filial inexistente
Se o código da filial não corresponder a nenhuma filial da loja, o produto é criado sem atribuição de filial. Nenhum erro é produzido.
Categorias automáticas
Categorias automáticas
Se uma categoria não existir, ela é criada automaticamente dentro da loja e da filial correspondente.
Imagens assíncronas
Imagens assíncronas
As imagens são baixadas e processadas em segundo plano após a criação do produto.
Variações por SKU
Variações por SKU
As variações são identificadas pelo SKU. Se uma variação com esse SKU já existir, ela é atualizada em vez de criar uma nova. Por padrão, as variações existentes que não estiverem no payload são mantidas; envie
replace_variations: true para removê-las.Modificadores
Modificadores
Se
modifier_groups estiver ausente no payload, os modificadores existentes são preservados. Se for um array vazio [], todos os modificadores são excluídos. Se tiver dados, os modificadores são completamente substituídos.Erros de validação
Se os dados não atenderem às regras de validação, a API responde com422 e detalha os campos com erros.
Mensagens de erro comuns
Mensagens de erro comuns
As mensagens da coluna Mensagem são retornadas pela API em inglês (não são localizadas), portanto aparecem aqui exatamente como a API responde.
Limites
- Máximo de 500 produtos por requisição no modo assíncrono (padrão), ou 50 no modo síncrono (
X-Sync: true). - Máximo de 10.000 produtos por janela de 60 segundos por loja (rate limit). Se excedido, a API responde com
429 Too Many Requests. - Todos os produtos são validados antes de serem processados.