Pular para o conteúdo principal
POST
/
api
/
v2
/
apps
/
{app_id}
/
batch
/
products
/
upsert_by_sku
curl -X POST "https://ecommerce.jelou.ai/api/v2/apps/{app_id}/batch/products/upsert_by_sku" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {
        "sku": "TSHIRT-BLU",
        "name": "Camiseta Básica Azul",
        "description": "Camiseta 100% algodão premium, corte regular",
        "price": 29.99,
        "has_tax": true,
        "tax": 15,
        "status": true,
        "stock_type": "limited",
        "stock": 150,
        "product_url": "https://minha-loja.com/camiseta-basica-azul",
        "discount_type": "percentage",
        "discount": 10,
        "branch": "BRANCH-DOWNTOWN",
        "categories": ["Roupas", "Camisetas"],
        "images": [
          "https://minha-loja.com/images/camiseta-azul-frente.jpg",
          "https://minha-loja.com/images/camiseta-azul-costas.jpg"
        ],
        "variations": [
          {
            "sku": "TSHIRT-BLU-S",
            "price": 29.99,
            "stock_type": "limited",
            "stock": 50,
            "attributes": [
              { "name": "Tamanho", "value": "S" },
              { "name": "Cor", "value": "Azul" }
            ]
          },
          {
            "sku": "TSHIRT-BLU-M",
            "price": 29.99,
            "stock_type": "limited",
            "stock": 60,
            "attributes": [
              { "name": "Tamanho", "value": "M" },
              { "name": "Cor", "value": "Azul" }
            ]
          },
          {
            "sku": "TSHIRT-BLU-L",
            "price": 31.99,
            "stock_type": "limited",
            "stock": 40,
            "attributes": [
              { "name": "Tamanho", "value": "L" },
              { "name": "Cor", "value": "Azul" }
            ],
            "images": [
              "https://minha-loja.com/images/camiseta-azul-L.jpg"
            ]
          }
        ]
      },
      {
        "sku": "PANTS-BLK-M",
        "name": "Calça Preta",
        "price": 49.99,
        "branch": "BRANCH-NORTH",
        "categories": ["Roupas", "Calças"],
        "note_enabled": true,
        "note_label": "Alguma instrução especial?"
      },
      {
        "sku": "PIZZA-FAMILY",
        "name": "Pizza Pepperoni Família",
        "description": "Pizza pepperoni tamanho família com massa artesanal",
        "price": 18.99,
        "stock_type": "unlimited",
        "branch": "BRANCH-NORTH",
        "categories": ["Pizzas", "Promoções"],
        "images": ["https://exemplo.com/pizza-pepperoni.jpg"],
        "modifier_groups": [
          {
            "code": "drinks",
            "name": "Escolha sua Bebida",
            "min_quantity": 1,
            "max_quantity": 1,
            "is_required": true,
            "options": [
              { "code": "coca-1l", "name": "Coca Cola 1L", "price": 0 },
              { "code": "sprite-1l", "name": "Sprite 1L", "price": 0 },
              { "code": "fanta-1l", "name": "Fanta 1L", "price": 0.50 }
            ]
          },
          {
            "code": "extras",
            "name": "Ingredientes Extras",
            "min_quantity": 0,
            "max_quantity": 5,
            "max_per_option": 2,
            "is_required": false,
            "options": [
              { "code": "extra-cheese", "name": "Queijo Extra", "price": 1.50 },
              { "code": "ham", "name": "Presunto", "price": 2.00 },
              { "code": "olives", "name": "Azeitonas", "price": 1.00 }
            ]
          }
        ]
      }
    ]
  }'

{
  "message": "Batch upsert process initiated successfully",
  "count": 3,
  "jobs": 3
}

Documentation Index

Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.
​
app_id
string
obrigatório
O ID da sua loja no Jelou Shop.
​
resources
object[]
obrigatório
Lista de produtos a criar ou atualizar (máx. 500 por requisição).

​
Campos do produto

Cada objeto dentro de resources aceita os seguintes campos:
​
sku
string
obrigatório
Identificador único do produto (máx. 255 caracteres).
​
name
string
obrigatório
Nome do produto (máx. 255 caracteres).
​
price
number
obrigatório
Preço do produto (mín. 0).
​
description
string
Descrição do produto.
​
has_tax
boolean
padrão:"true"
Indica se o preço inclui impostos.
​
tax
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.
​
status
boolean
padrão:"true"
Status do produto (ativo/inativo).
​
stock_type
string
padrão:"unlimited"
Tipo de inventário: limited ou unlimited.
​
stock
number
Quantidade disponível. Aplica-se apenas quando stock_type é limited.
​
product_url
string
URL do produto na sua loja (máx. 2048 caracteres).
​
discount_type
string
Tipo de desconto: value (valor fixo) ou percentage.
​
discount
number
Valor do desconto (mín. 0).
​
categories
string[]
Lista de nomes de categorias. São criadas automaticamente se não existirem.
​
images
string[]
Lista de URLs públicas de imagens do produto.
​
note_enabled
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”).
​
note_label
string
Texto placeholder exibido no campo de nota (máx. 255 caracteres). Se não especificado, um texto genérico padrão é usado.
​
branch
string
Código da filial à qual o produto é atribuído. A filial deve já existir.
A filial deve ser criada antes de ser atribuída a um produto. Use o endpoint Criar filial para registrá-la primeiro.
​
variations
object[]
Lista de variações do produto.
​
modifier_groups
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. 
curl -X POST "https://ecommerce.jelou.ai/api/v2/apps/{app_id}/batch/products/upsert_by_sku" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {
        "sku": "TSHIRT-BLU",
        "name": "Camiseta Básica Azul",
        "description": "Camiseta 100% algodão premium, corte regular",
        "price": 29.99,
        "has_tax": true,
        "tax": 15,
        "status": true,
        "stock_type": "limited",
        "stock": 150,
        "product_url": "https://minha-loja.com/camiseta-basica-azul",
        "discount_type": "percentage",
        "discount": 10,
        "branch": "BRANCH-DOWNTOWN",
        "categories": ["Roupas", "Camisetas"],
        "images": [
          "https://minha-loja.com/images/camiseta-azul-frente.jpg",
          "https://minha-loja.com/images/camiseta-azul-costas.jpg"
        ],
        "variations": [
          {
            "sku": "TSHIRT-BLU-S",
            "price": 29.99,
            "stock_type": "limited",
            "stock": 50,
            "attributes": [
              { "name": "Tamanho", "value": "S" },
              { "name": "Cor", "value": "Azul" }
            ]
          },
          {
            "sku": "TSHIRT-BLU-M",
            "price": 29.99,
            "stock_type": "limited",
            "stock": 60,
            "attributes": [
              { "name": "Tamanho", "value": "M" },
              { "name": "Cor", "value": "Azul" }
            ]
          },
          {
            "sku": "TSHIRT-BLU-L",
            "price": 31.99,
            "stock_type": "limited",
            "stock": 40,
            "attributes": [
              { "name": "Tamanho", "value": "L" },
              { "name": "Cor", "value": "Azul" }
            ],
            "images": [
              "https://minha-loja.com/images/camiseta-azul-L.jpg"
            ]
          }
        ]
      },
      {
        "sku": "PANTS-BLK-M",
        "name": "Calça Preta",
        "price": 49.99,
        "branch": "BRANCH-NORTH",
        "categories": ["Roupas", "Calças"],
        "note_enabled": true,
        "note_label": "Alguma instrução especial?"
      },
      {
        "sku": "PIZZA-FAMILY",
        "name": "Pizza Pepperoni Família",
        "description": "Pizza pepperoni tamanho família com massa artesanal",
        "price": 18.99,
        "stock_type": "unlimited",
        "branch": "BRANCH-NORTH",
        "categories": ["Pizzas", "Promoções"],
        "images": ["https://exemplo.com/pizza-pepperoni.jpg"],
        "modifier_groups": [
          {
            "code": "drinks",
            "name": "Escolha sua Bebida",
            "min_quantity": 1,
            "max_quantity": 1,
            "is_required": true,
            "options": [
              { "code": "coca-1l", "name": "Coca Cola 1L", "price": 0 },
              { "code": "sprite-1l", "name": "Sprite 1L", "price": 0 },
              { "code": "fanta-1l", "name": "Fanta 1L", "price": 0.50 }
            ]
          },
          {
            "code": "extras",
            "name": "Ingredientes Extras",
            "min_quantity": 0,
            "max_quantity": 5,
            "max_per_option": 2,
            "is_required": false,
            "options": [
              { "code": "extra-cheese", "name": "Queijo Extra", "price": 1.50 },
              { "code": "ham", "name": "Presunto", "price": 2.00 },
              { "code": "olives", "name": "Azeitonas", "price": 1.00 }
            ]
          }
        ]
      }
    ]
  }'

{
  "message": "Batch upsert process initiated successfully",
  "count": 3,
  "jobs": 3
}
Substitua {app_id} pelo ID da sua loja e <API_KEY> pelo token fornecido pelo Jelou.

​
Comportamento

O endpoint retorna 202 Accepted imediatamente. Os produtos são processados em segundo plano.
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.
Se uma categoria não existir, ela é criada automaticamente dentro da loja e da filial correspondente.
As imagens são baixadas e processadas em segundo plano após a criação do produto.
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.
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 com 422 e detalha os campos com erros. 
{
  "message": "The resources field is required.",
  "errors": {
    "resources": ["The resources field is required."]
  }
}
CampoMensagem
resourcesPelo menos um produto é obrigatório.
resourcesNão é possível processar mais de 500 produtos de uma vez.
resources.*.skuCada produto deve ter um SKU.
resources.*.nameCada produto deve ter um nome.
resources.*.priceCada produto deve ter um preço. / O preço não pode ser negativo.
resources.*.stock_typeO tipo de estoque deve ser limited ou unlimited.
resources.*.images.*Cada imagem deve ser uma URL válida.
resources.*.variations.*.stock_typeO tipo de estoque da variação deve ser limited ou unlimited.
resources.*.variations.*.stockO estoque da variação deve ser um inteiro. / Não pode ser negativo.
resources.*.modifier_groups.*.codeCada grupo de modificadores deve ter um código.
resources.*.modifier_groups.*.nameCada grupo de modificadores deve ter um nome.
resources.*.modifier_groups.*.optionsCada grupo de modificadores deve ter pelo menos uma opção.
resources.*.modifier_groups.*.options.*.codeCada opção de modificador deve ter um código.
resources.*.modifier_groups.*.options.*.nameCada opção de modificador deve ter um nome.
resources.*.taxA taxa de imposto deve ser um número.
resources.*.taxA taxa de imposto não pode ser negativa.
resources.*.taxA taxa de imposto não pode exceder 100.

​
Limites

  • Máximo de 500 produtos por requisição.
  • 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.