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,
        "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,
            "attributes": [
              { "name": "Tamanho", "value": "S" },
              { "name": "Cor", "value": "Azul" }
            ]
          },
          {
            "sku": "TSHIRT-BLU-M",
            "price": 29.99,
            "attributes": [
              { "name": "Tamanho", "value": "M" },
              { "name": "Cor", "value": "Azul" }
            ]
          },
          {
            "sku": "TSHIRT-BLU-L",
            "price": 31.99,
            "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"]
      },
      {
        "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
}
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.
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.
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,
        "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,
            "attributes": [
              { "name": "Tamanho", "value": "S" },
              { "name": "Cor", "value": "Azul" }
            ]
          },
          {
            "sku": "TSHIRT-BLU-M",
            "price": 29.99,
            "attributes": [
              { "name": "Tamanho", "value": "M" },
              { "name": "Cor", "value": "Azul" }
            ]
          },
          {
            "sku": "TSHIRT-BLU-L",
            "price": 31.99,
            "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"]
      },
      {
        "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.*.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.

Limites

  • Máximo de 500 produtos por requisição.
  • Todos os produtos são validados antes de serem processados.