Criar e atualizar categorias

curl -X POST "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/batch/categories/upsert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {
        "name": "Pizzas",
        "description": "Todas as nossas pizzas artesanais",
        "image": "https://exemplo.com/images/pizzas.jpg",
        "order": 1,
        "status": true,
        "branch": "FILIAL-CENTRO"
      },
      {
        "name": "Bebidas",
        "description": "Bebidas quentes e frias",
        "order": 2,
        "branch": "FILIAL-CENTRO"
      },
      {
        "name": "Sobremesas",
        "order": 3
      }
    ]
  }'

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

{
  "message": "Each category must have a name.",
  "errors": {
    "resources.0.name": ["Each category must have a name."]
  }
}

POST

ecommerce

apps

{app_id}

batch

categories

upsert

curl -X POST "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/batch/categories/upsert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {
        "name": "Pizzas",
        "description": "Todas as nossas pizzas artesanais",
        "image": "https://exemplo.com/images/pizzas.jpg",
        "order": 1,
        "status": true,
        "branch": "FILIAL-CENTRO"
      },
      {
        "name": "Bebidas",
        "description": "Bebidas quentes e frias",
        "order": 2,
        "branch": "FILIAL-CENTRO"
      },
      {
        "name": "Sobremesas",
        "order": 3
      }
    ]
  }'

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

{
  "message": "Each category must have a name.",
  "errors": {
    "resources.0.name": ["Each category must have a name."]
  }
}

Você pode criar ou atualizar categorias em lote pelo nome. Se uma categoria com o mesmo nome já existir na mesma loja e filial, ela é atualizada; caso contrário, é criada.

app_id

string

obrigatório

O ID da sua loja no Jelou Shop.

resources

object[]

obrigatório

Lista de categorias para criar ou atualizar (máx. 500 por solicitação).

Mostrar Campos de cada categoria

name

string

obrigatório

Nome da categoria (máx. 255 caracteres). Usado como identificador único dentro da loja e filial.

description

string

Descrição da categoria.

image

string

URL pública da imagem da categoria. URLs privadas/internas não são aceitas.

order

integer

padrão:"0"

Posição de ordenação da categoria (mín. 0, máx. 999999). Quando maior que 0, deve ser único dentro do mesmo nível (app + categoria pai + filial). O valor 0 é tratado como “sem ordem”.

status

boolean

padrão:"true"

Status da categoria (ativa/inativa).

branch

string

Código da filial à qual a categoria pertence. A filial deve existir previamente.

parent_id

integer

ID da categoria pai (para hierarquia). Deve existir previamente na mesma loja.

A filial deve ser criada antes de atribuí-la a uma categoria. Use o endpoint Criar filiais para registrá-la primeiro.

curl -X POST "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/batch/categories/upsert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {
        "name": "Pizzas",
        "description": "Todas as nossas pizzas artesanais",
        "image": "https://exemplo.com/images/pizzas.jpg",
        "order": 1,
        "status": true,
        "branch": "FILIAL-CENTRO"
      },
      {
        "name": "Bebidas",
        "description": "Bebidas quentes e frias",
        "order": 2,
        "branch": "FILIAL-CENTRO"
      },
      {
        "name": "Sobremesas",
        "order": 3
      }
    ]
  }'

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

{
  "message": "Each category must have a name.",
  "errors": {
    "resources.0.name": ["Each category must have a name."]
  }
}

Comportamento

Processamento assíncrono

O endpoint retorna 202 Accepted imediatamente. As categorias são processadas em segundo plano.

Upsert por nome

As categorias são identificadas pelo name dentro da mesma loja e filial. Se já existir uma com esse nome, ela é atualizada em vez de criar uma nova.

Filial inexistente

Se o código da filial não corresponder a nenhuma filial da loja, a categoria é criada sem filial atribuída.

Imagens

Se uma URL de imagem for fornecida, ela é baixada e armazenada em segundo plano após a criação da categoria. A URL deve ser pública; URLs privadas/internas são rejeitadas.

Hierarquia (parent_id)

Use parent_id para aninhar categorias. O pai deve existir na mesma loja antes do processamento do lote. Para construir uma nova hierarquia, crie primeiro as categorias pai e depois envie as filhas referenciando seu parent_id.

Ordem única por nível

Quando order é maior que 0, deve ser único dentro do mesmo nível (app + categoria pai + filial). Se duas categorias do mesmo lote compartilharem order no mesmo nível, ou se colidir com uma categoria existente, a solicitação falha com 422. O order 0 ou nulo é considerado “sem ordem” e não valida unicidade.

Erros de validação

Mensagens de erro comuns

Campo	Mensagem
`resources`	The resources field is required.
`resources`	At least one category is required.
`resources`	Cannot process more than 500 categories at once.
`resources.*.name`	Each category must have a name.
`resources.*.image`	Category image must be a valid URL.
`resources.*.order`	Category order must be an integer. / Category order cannot be negative. / Category order cannot exceed 999999.
`resources.*.order`	Order is duplicated within this batch for the same parent/branch. / Order is already assigned to another category.
`resources.*.status`	Category status must be a boolean.
`resources.*.parent_id`	Parent category id must be an integer. / The parent category does not exist for this app.
`resources`	This app already has categories. Adding new categories would exceed the limit of .

Limites

Máximo 500 categorias por solicitação.
Limite total de categorias por loja (configurável; padrão 500). Se o lote exceder o limite restante, a solicitação falha com 422.
Todas as categorias são validadas antes do processamento.

Substitua {app_id} pelo ID da sua loja e YOUR_API_KEY pela sua chave de API.

Buscar cupons

Listar categorias

⌘I

Primeiros Passos

Agentes de IA

Nós

Variáveis

Observabilidade nos Workflows

Mensagens Outbound

Gestão

Marketplace

Canais

Configuração

Faturamento

Criar e atualizar categorias

Comportamento

Erros de validação

Limites

​Comportamento

​Erros de validação

​Limites

Comportamento

Erros de validação

Limites