API de Categorías y Subcategorías

La API de Categorías y Subcategorías permite gestionar la estructura de categorización de productos en la plataforma Nilo. Estos endpoints son esenciales para organizar los productos en la tienda.

Entendiendo Categorías y Subcategorías

Las categorías y subcategorías en Nilo forman una estructura jerárquica que ayuda a organizar los productos de manera efectiva:

• Categorías: Clasificaciones de nivel superior que agrupan productos relacionados

  • Pueden contener múltiples subcategorías
  • Tienen propiedades como nombre, código interno, peso e imagen
  • Pueden ser habilitadas/deshabilitadas para controlar su visibilidad
  • Se utilizan para la navegación principal y organización de productos

• Subcategorías: Clasificaciones de segundo nivel dentro de las categorías

  • Deben pertenecer a una categoría padre
  • Ayudan a crear agrupaciones de productos más específicas
  • Comparten propiedades similares con las categorías
  • Permiten una organización más granular de productos

Consideraciones Importantes

1. Códigos Únicos: Tanto las categorías como las subcategorías requieren códigos internos únicos
2. Jerarquía: Las subcategorías siempre deben tener una categoría padre válida
3. Peso: Se utiliza para controlar el orden de visualización en los listados (números más bajos aparecen primero)
4. Estado: Ambas pueden ser habilitadas/deshabilitadas independientemente
5. Imágenes: Las categorías pueden tener imágenes asociadas para una mejor representación visual

Operaciones Individuales

Categorías

Obtener todas las categorías

GET/category

Este endpoint permite obtener todas las categorías disponibles en la plataforma.

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
take	number	No	Número de elementos por página (máximo 50, mínimo 1, por defecto 50)
page	string	No	Número de página (por defecto 1)
enabled	boolean	No	Filtrar por estado de habilitación
cursor	string	No	Cursor para paginación. Primer llamado usar 0, luego usar el cursor de la respuesta anterior

Códigos de Respuesta

Código	Descripción
200	Operación exitosa - Categorías recuperadas
404	No encontrado - Categorías no encontradas

Ejemplo de Uso

Javascript

const headers = {
  "x-api-key": "YOUR_API_KEY",
  Authorization: "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category?take=10&page=1&enabled=true",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category"

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

params = {
    'take': 10,
    'page': 1,
    'enabled': True
}

response = requests.get(url, headers=headers, params=params)
print(response.text)

Ejemplo de Respuesta Exitosa

{
  "data": [
    {
      "name": "Category",
      "internalCode": "1235",
      "image": "/qa/category/12442.png",
      "enabled": true,
      "children": [
        {
          "name": "Children Category",
          "internalCode": "1236"
        }
      ]
    }
  ],
  "page": {
    "pageBased": {
      "count": 230
    },
    "cursorBased": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "firstCursor": "0",
      "lastCursor": "49"
    }
  }
}

Obtener una categoría específica

GET/category/{code}

Este endpoint permite obtener los detalles de una categoría específica.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	Código de categoría

Códigos de Respuesta

Código	Descripción
200	Operación exitosa - Categoría recuperada
404	No encontrado - Categoría no encontrada

Ejemplo de Uso

Javascript

const headers = {
  "x-api-key": "YOUR_API_KEY",
  Authorization: "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category/7234",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category/7234"

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)
print(response.text)

Ejemplo de Respuesta Exitosa

{
  "name": "Category",
  "internalCode": "7234",
  "image": "/qa/category/12442.png",
  "enabled": true,
  "parent": {
    "name": "Parent Category",
    "internalCode": "1235"
  },
  "children": [
    {
      "name": "Children Category",
      "internalCode": "1236"
    }
  ]
}

Crear una categoría

POST/category

Este endpoint permite crear una nueva categoría en la plataforma.

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
name	string	Sí	Nombre de la categoría
internalCode	string	Sí	Código interno de la categoría
weight	integer	No	Valor utilizado para posicionar productos en listados (orden de aparición)
image	string	No	URL pública de la imagen de la categoría

Gestión de Imágenes

El campo image espera una URL pública y accesible. Durante el procesamiento, Nilo descargará la imagen, la almacenará en servidores de Nilo y la distribuirá a través de una CDN para carga optimizada. Usa imágenes de alta calidad - la plataforma generará automáticamente versiones optimizadas para diferentes dispositivos.

Ejemplo del Cuerpo de la Solicitud

{
  "name": "Categoría Nueva",
  "internalCode": "9876",
  "weight": 1,
  "image": "/qa/category/9876.png"
}

Códigos de Respuesta

Código	Descripción
200	Operación exitosa - Categoría creada
404	No encontrado - Error al crear categoría

Ejemplo de Uso

Javascript

const headers = {
  "x-api-key": "YOUR_API_KEY",
  Authorization: "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
};

const data = {
  name: "Categoría Nueva",
  internalCode: "9876",
  weight: 1,
  image: "/qa/category/9876.png",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category", {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category"

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

data = {
    "name": "Categoría Nueva",
    "internalCode": "9876",
    "weight": 1,
    "image": "/qa/category/9876.png"
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Actualizar una categoría

PUT/category/{code}

Este endpoint permite actualizar una categoría existente.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	Código de categoría

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
name	string	Sí	Nombre de la categoría
weight	integer	No	Valor utilizado para posicionar productos en listados (orden de aparición)
image	string	No	URL pública de la imagen de la categoría

Gestión de Imágenes

El campo image espera una URL pública y accesible. Durante el procesamiento, Nilo descargará la imagen, la almacenará en servidores de Nilo y la distribuirá a través de una CDN para carga optimizada.

Ejemplo del Cuerpo de la Solicitud

{
  "name": "Categoría Actualizada",
  "weight": 2,
  "image": "/qa/category/updated.png"
}

Códigos de Respuesta

Código	Descripción
200	Operación exitosa - Categoría actualizada
404	No encontrado - Categoría no encontrada

Ejemplo de Uso

Javascript

const headers = {
  "x-api-key": "YOUR_API_KEY",
  Authorization: "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
};

const data = {
  name: "Categoría Actualizada",
  weight: 2,
  image: "/qa/category/updated.png",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category/7234",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category/7234"

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

data = {
    "name": "Categoría Actualizada",
    "weight": 2,
    "image": "/qa/category/updated.png"
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Upsert de categoría

PUT/category

Este endpoint permite crear o actualizar una categoría existente (upsert).

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
name	string	Sí	Nombre de la categoría
internalCode	string	Sí	Código interno de la categoría
enabled	boolean	Sí	Estado de habilitación de la categoría
weight	integer	No	Valor utilizado para posicionar productos en listados (orden de aparición)
image	string	No	URL pública de la imagen de la categoría

Gestión de Imágenes

El campo image espera una URL pública y accesible. Durante el procesamiento, Nilo descargará la imagen, la almacenará en servidores de Nilo y la distribuirá a través de una CDN para carga optimizada.

Ejemplo del Cuerpo de la Solicitud

{
  "name": "Categoría Upsert",
  "internalCode": "5678",
  "enabled": true,
  "weight": 3,
  "image": "/qa/category/upsert.png"
}

Códigos de Respuesta

Código	Descripción
200	Operación exitosa - Categoría actualizada
404	No encontrado - Categoría no encontrada

Ejemplo de Uso

Javascript

const headers = {
  "x-api-key": "YOUR_API_KEY",
  Authorization: "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
};

const data = {
  name: "Categoría Upsert",
  internalCode: "5678",
  enabled: true,
  weight: 3,
  image: "/qa/category/upsert.png",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category", {
  method: "PUT",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category"

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

data = {
    "name": "Categoría Upsert",
    "internalCode": "5678",
    "enabled": true,
    "weight": 3,
    "image": "/qa/category/upsert.png"
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Cambiar estado de categoría

PUT/category/{code}/status

Este endpoint permite habilitar o deshabilitar una categoría.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	Código de categoría

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
enabled	boolean	Sí	Estado de habilitación (true/false)

Ejemplo del Cuerpo de la Solicitud

{
  "enabled": true
}

Códigos de Respuesta

Código	Descripción
200	Operación exitosa - Estado actualizado
404	No encontrado - Categoría no encontrada

Ejemplo de Uso

Javascript

const headers = {
  "x-api-key": "YOUR_API_KEY",
  Authorization: "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
};

const data = {
  enabled: true,
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category/7234/status",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category/7234/status"

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

data = {
    "enabled": true
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Subcategorías

Crear una subcategoría

POST/subcategory

Este endpoint permite crear una nueva subcategoría en la plataforma.

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
name	string	Sí	Nombre de la subcategoría
internalCode	string	Sí	Código interno de la subcategoría
parentCategoryInternalCode	string	Sí	Código interno de la categoría padre
weight	integer	No	Valor utilizado para posicionar productos en listados (orden de aparición)

Ejemplo del Cuerpo de la Solicitud

{
  "name": "Subcategoría Nueva",
  "internalCode": "4321",
  "parentCategoryInternalCode": "7234",
  "weight": 1
}

Códigos de Respuesta

Código	Descripción
200	Operación exitosa - Subcategoría creada
404	No encontrado - Error al crear subcategoría

Ejemplo de Uso

Javascript

const headers = {
  "x-api-key": "YOUR_API_KEY",
  Authorization: "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
};

const data = {
  name: "Subcategoría Nueva",
  internalCode: "4321",
  parentCategoryInternalCode: "7234",
  weight: 1,
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/subcategory",
  {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/subcategory"

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

data = {
    "name": "Subcategoría Nueva",
    "internalCode": "4321",
    "parentCategoryInternalCode": "7234",
    "weight": 1
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Actualizar una subcategoría

PUT/subcategory/{code}

Este endpoint permite actualizar una subcategoría existente.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	Código de subcategoría

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
name	string	Sí	Nombre de la subcategoría
parentCategoryInternalCode	string	Sí	Código interno de la categoría padre
weight	integer	No	Valor utilizado para posicionar productos en listados (orden de aparición)

Ejemplo del Cuerpo de la Solicitud

{
  "name": "Subcategoría Actualizada",
  "parentCategoryInternalCode": "7234",
  "weight": 2
}

Códigos de Respuesta

Código	Descripción
200	Operación exitosa - Subcategoría actualizada
404	No encontrado - Subcategoría no encontrada

Ejemplo de Uso

Javascript

const headers = {
  "x-api-key": "YOUR_API_KEY",
  Authorization: "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
};

const data = {
  name: "Subcategoría Actualizada",
  parentCategoryInternalCode: "7234",
  weight: 2,
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/subcategory/4321",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/subcategory/4321"

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

data = {
    "name": "Subcategoría Actualizada",
    "parentCategoryInternalCode": "7234",
    "weight": 2
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Upsert de subcategoría

PUT/subcategory

Este endpoint permite crear o actualizar una subcategoría existente (upsert).

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
name	string	Sí	Nombre de la subcategoría
internalCode	string	Sí	Código interno de la subcategoría
parentCategoryInternalCode	string	Sí	Código interno de la categoría padre
enabled	boolean	Sí	Estado de habilitación de la subcategoría
weight	integer	No	Valor utilizado para posicionar productos en listados (orden de aparición)

Ejemplo del Cuerpo de la Solicitud

{
  "name": "Subcategoría Upsert",
  "internalCode": "8765",
  "parentCategoryInternalCode": "7234",
  "enabled": true,
  "weight": 3
}

Códigos de Respuesta

Código	Descripción
200	Operación exitosa - Subcategoría actualizada
404	No encontrado - Subcategoría no encontrada

Ejemplo de Uso

Javascript

const headers = {
  "x-api-key": "YOUR_API_KEY",
  Authorization: "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
};

const data = {
  name: "Subcategoría Upsert",
  internalCode: "8765",
  parentCategoryInternalCode: "7234",
  enabled: true,
  weight: 3,
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/subcategory",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/subcategory"

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

data = {
    "name": "Subcategoría Upsert",
    "internalCode": "8765",
    "parentCategoryInternalCode": "7234",
    "enabled": true,
    "weight": 3
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Cambiar estado de subcategoría

PUT/subcategory/{code}/status

Este endpoint permite habilitar o deshabilitar una subcategoría.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	Código de subcategoría

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
enabled	boolean	Sí	Estado de habilitación (true/false)

Ejemplo del Cuerpo de la Solicitud

{
  "enabled": true
}

Códigos de Respuesta

Código	Descripción
200	Operación exitosa - Estado actualizado
404	No encontrado - Subcategoría no encontrada

Ejemplo de Uso

Javascript

const headers = {
  "x-api-key": "YOUR_API_KEY",
  Authorization: "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
};

const data = {
  enabled: true,
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/subcategory/4321/status",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/subcategory/4321/status"

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

data = {
    "enabled": true
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Tipos de Respuesta

Respuesta Exitosa

{
  "code": 200,
  "message": "Operación exitosa"
}

Respuesta de Error

{
  "code": 400,
  "message": "Parámetros de solicitud inválidos"
}

Mejores Prácticas

1. Nombres Consistentes: Utilizar nombres claros y descriptivos para categorías y subcategorías
2. Estructura de Códigos: Crear una estructura lógica para los códigos internos que los haga fácilmente identificables
3. Gestión de Pesos: Planificar cuidadosamente los valores de peso para mantener el orden deseado
4. Control de Estado: Usar cambios de estado en lugar de eliminar categorías
5. Referencias Padre: Siempre verificar que la categoría padre exista antes de crear subcategorías
6. Gestión de Imágenes: Usar imágenes de alta calidad con URLs públicas - Nilo las optimizará para diferentes dispositivos

Casos de Uso Comunes

1. Configuración Inicial

   • Crear categorías principales para el catálogo de productos
   • Configurar subcategorías dentro de cada categoría principal
   • Configurar pesos para el orden de visualización adecuado

2. Mantenimiento del Catálogo

   • Actualizar nombres o imágenes de categorías
   • Habilitar/deshabilitar categorías según la temporada
   • Ajustar pesos para cambiar el orden de visualización

Seguridad

Todos los endpoints de la API requieren dos tipos de autenticación:

1. API Key en el encabezado: x-api-key
2. Token de autorización en el encabezado: Authorization

Permisos Requeridos

Para los endpoints de categorías y subcategorías, se requieren los siguientes permisos:

• Para operaciones de lectura: supplier/category.read
• Para operaciones de escritura: supplier/category.write