> ## 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.

# Criar e atualizar categorias

> Crie ou atualize categorias em lote. Se uma categoria com o mesmo nome já existir, ela é atualizada.

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` *required*

O ID da sua loja no Jelou Shop.

**resources** `object[]` *required*

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

**Campos de cada categoria**

**name** `string` *required*

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` (default: 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` (default: 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.

> [!WARNING]
>
> A filial deve ser criada antes de atribuí-la a uma categoria. Use o endpoint [Criar filiais](https://docs.jelou.ai/pt/api/shop/filiais/criar.md) para registrá-la primeiro.

```bash cURL theme={null}
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
      }
    ]
  }'
```

```json 202 Accepted theme={null}
{
  "message": "Batch upsert process initiated successfully",
  "count": 3,
  "jobs": 1
}
```

```json 422 Validation Error theme={null}
{
  "message": "Each category must have a name.",
  "errors": {
    "resources.0.name": ["Each category must have a name."]
  }
}
```

## Comportamento

> [accordion] Processamento assíncrono
>
> O endpoint retorna `202 Accepted` imediatamente. As categorias são processadas em segundo plano.

> [accordion] 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.

> [accordion] Filial inexistente
>
> Se o código da filial não corresponder a nenhuma filial da loja, a categoria é criada sem filial atribuída.

> [accordion] 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.

> [accordion] 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`.

> [accordion] 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

> [accordion] 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 {n} is duplicated within this batch for the same parent/branch. / Order {n} 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 {n} categories. Adding {m} new categories would exceed the limit of {limit}. |

## 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.

> [!NOTE]
>
> Substitua `{app_id}` pelo ID da sua loja e `YOUR_API_KEY` pela sua [chave de API](https://docs.jelou.ai/pt/guias/configuracao/chaves-api.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.