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

# Crear y actualizar categorías

> Crea o actualiza categorías en lote. Si una categoría con el mismo nombre ya existe, se actualiza.

Puedes crear o actualizar categorías en lote según su nombre. Si una categoría con el mismo nombre ya existe en la misma tienda y sucursal, se actualiza; si no, se crea.

**app\_id** `string` *required*

ID de tu tienda en Jelou Shop.

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

Lista de categorías a crear o actualizar (máx. 500 por solicitud).

**Campos de cada categoría**

**name** `string` *required*

Nombre de la categoría (máx. 255 caracteres). Se usa como identificador único dentro de la tienda y sucursal.

**description** `string`

Descripción de la categoría.

**image** `string`

URL **pública** de la imagen de la categoría. No se aceptan URLs privadas/internas.

**order** `integer` (default: 0)

Posición de ordenamiento de la categoría (mín. 0, máx. 999999). Cuando es mayor que 0, debe ser único dentro del mismo nivel (app + categoría padre + sucursal). El valor `0` se trata como "sin orden".

**status** `boolean` (default: true)

Estado de la categoría (activa/inactiva).

**branch** `string`

Código de la sucursal a la que pertenece la categoría. La sucursal debe existir previamente.

**parent\_id** `integer`

ID de la categoría padre (para jerarquía). Debe existir previamente en la misma tienda.

> [!WARNING]
>
> La sucursal debe estar creada antes de asignarla a una categoría. Usa el endpoint [Crear sucursales](https://docs.jelou.ai/api/shop/sucursales/crear.md) para registrarla primero.

```bash cURL theme={null}
curl -X POST "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/batch/categories/upsert" \
  -H "x-api-key: TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {
        "name": "Pizzas",
        "description": "Todas nuestras pizzas artesanales",
        "image": "https://ejemplo.com/images/pizzas.jpg",
        "order": 1,
        "status": true,
        "branch": "SUC-CENTRO"
      },
      {
        "name": "Bebidas",
        "description": "Bebidas frías y calientes",
        "order": 2,
        "branch": "SUC-CENTRO"
      },
      {
        "name": "Postres",
        "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."]
  }
}
```

## Comportamiento

> [accordion] Procesamiento asíncrono
>
> El endpoint retorna `202 Accepted` inmediatamente. Las categorías se procesan en segundo plano.

> [accordion] Upsert por nombre
>
> Las categorías se identifican por su `name` dentro de la misma tienda y sucursal. Si ya existe una con ese nombre, se actualiza en lugar de crear una nueva.

> [accordion] Sucursal inexistente
>
> Si el código de sucursal no coincide con ninguna sucursal de la tienda, la categoría se crea sin sucursal asignada.

> [accordion] Imágenes
>
> Si se proporciona una URL de imagen, se descarga y almacena en segundo plano después de la creación de la categoría. La URL debe ser pública; las URLs privadas/internas se rechazan.

> [accordion] Jerarquía (parent\_id)
>
> Usa `parent_id` para anidar categorías. El padre debe existir en la misma tienda antes de procesarse el lote. Para construir una jerarquía nueva, crea primero las categorías padre y luego envía las hijas referenciando su `parent_id`.

> [accordion] Orden único por nivel
>
> Cuando `order` es mayor que 0, debe ser único dentro del mismo nivel (app + categoría padre + sucursal). Si dos categorías del mismo lote comparten `order` en el mismo nivel, o si choca con una categoría existente, la solicitud falla con `422`. El `order` 0 o nulo se considera "sin orden" y no valida unicidad.

## Errores de validación

> [accordion] Mensajes de error comunes
>
> | Campo | Mensaje |
> | - | - |
> | `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}. |

## Límites

* Máximo **500 categorías** por solicitud.
* Límite total de categorías **por tienda** (configurable; por defecto **500**). Si el lote supera el límite restante, la solicitud falla con `422`.
* Todas las categorías se validan antes de procesarse.

> [!NOTE]
>
> Reemplaza `{app_id}` con el ID de tu tienda y `TU_CLAVE_API` con tu [clave API](https://docs.jelou.ai/guides/configuracion/claves-api.md).


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