Crear y actualizar categorías

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
      }
    ]
  }'

{
  "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: 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
      }
    ]
  }'

{
  "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."]
  }
}

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

requerido

ID de tu tienda en Jelou Shop.

resources

object[]

requerido

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

Mostrar Campos de cada categoría

name

string

requerido

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

predeterminado:"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

predeterminado:"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.

La sucursal debe estar creada antes de asignarla a una categoría. Usa el endpoint Crear sucursales para registrarla primero.

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
      }
    ]
  }'

{
  "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."]
  }
}

Comportamiento

Procesamiento asíncrono

El endpoint retorna 202 Accepted inmediatamente. Las categorías se procesan en segundo plano.

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.

Sucursal inexistente

Si el código de sucursal no coincide con ninguna sucursal de la tienda, la categoría se crea sin sucursal asignada.

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.

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.

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

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

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.

Reemplaza {app_id} con el ID de tu tienda y TU_CLAVE_API con tu clave API.

Buscar sucursales

Listar categorías

⌘I

Empezando

Agentes IA

Nodos

Variables

Observabilidad en Workflows

Mensajería Outbound

Gestión

Marketplace

Canales

Configuración

Facturación

Crear y actualizar categorías

Comportamiento

Errores de validación

Límites

​Comportamiento

​Errores de validación

​Límites

Comportamiento

Errores de validación

Límites