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

<ParamField path="app_id" type="string" required>
  O ID da sua loja no Jelou Shop.
</ParamField>

<ParamField body="resources" type="object[]" required>
  Lista de categorias para criar ou atualizar (máx. 500 por solicitação).

  <Expandable title="Campos de cada categoria">
    <ParamField body="name" type="string" required>
      Nome da categoria (máx. 255 caracteres). Usado como identificador único dentro da loja e filial.
    </ParamField>

    <ParamField body="description" type="string">
      Descrição da categoria.
    </ParamField>

    <ParamField body="image" type="string">
      URL **pública** da imagem da categoria. URLs privadas/internas não são aceitas.
    </ParamField>

    <ParamField body="order" type="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".
    </ParamField>

    <ParamField body="status" type="boolean" default="true">
      Status da categoria (ativa/inativa).
    </ParamField>

    <ParamField body="branch" type="string">
      Código da filial à qual a categoria pertence. A filial deve existir previamente.
    </ParamField>

    <ParamField body="parent_id" type="integer">
      ID da categoria pai (para hierarquia). Deve existir previamente na mesma loja.
    </ParamField>
  </Expandable>
</ParamField>

<Warning>
  A filial deve ser criada antes de atribuí-la a uma categoria. Use o endpoint [Criar filiais](/pt/guias/integracoes/e-commerce/api-sucursales/criar) para registrá-la primeiro.
</Warning>

<RequestExample>
  ```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
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```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."]
    }
  }
  ```
</ResponseExample>

## Comportamento

<AccordionGroup>
  <Accordion title="Processamento assíncrono">
    O endpoint retorna `202 Accepted` imediatamente. As categorias são processadas em segundo plano.
  </Accordion>

  <Accordion title="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>

  <Accordion title="Filial inexistente">
    Se o código da filial não corresponder a nenhuma filial da loja, a categoria é criada sem filial atribuída.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Erros de validação

<Accordion title="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}.                          |
</Accordion>

## 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](/pt/guias/configuracao/chaves-api).
</Note>