Categorías

Listar las categorías

GET /api/v1/ecommerce/categories

No pide token. Devuelve las categorías que la empresa marcó para mostrarse en la tienda, en el orden que eligió.

Parámetro	Dónde	Obligatorio	Reglas
name	Query	No	Solo las categorías cuyo nombre contenga este texto. Máximo 255 caracteres

curl https://<dominio-de-la-empresa>/api/v1/ecommerce/categories \
  -H "Accept: application/json"

Respuesta

{
  "data": [
    { "id": 22, "name": "Ropa", "slug": "ropa", "products_count": 12 },
    { "id": 23, "name": "Calzado", "slug": "calzado", "products_count": 8 }
  ],
  "success": true,
  "message": "Listado de categorías obtenido de forma correcta."
}

Campo	Qué es
id	Identificador de la categoría. Sirve en el filtro categories de productos
name	Nombre para mostrar
slug	Nombre para la dirección. Es el que se usa en «Ver una categoría» y también sirve en el filtro categories
products_count	Productos asociados a la categoría desde la tienda que están marcados para la tienda virtual y no son servicios. Si la tienda muestra solo productos con stock, solo cuenta los que tienen stock

No es una lista paginada: llegan todas las categorías visibles. Si no hay ninguna, la lista llega vacía.

Las categorías ocultas (por ejemplo destacados o para-ti, que la tienda usa como secciones de la portada) no aparecen aquí, pero sí funcionan en el filtro categories de productos.

Si algo sale mal

HTTP	code	Cuándo	Qué hacer
404	STORE_NOT_FOUND	La tienda no está publicada	La empresa debe publicarla desde el ERP
503	STORE_PAUSED	La tienda está pausada	Reintenta más tarde (Retry-After)
422	VALIDATION_ERROR	name no es un texto o pasa de 255 caracteres	Corrige el parámetro
503	STORE_NOT_CONFIGURED	El ERP no tiene ningún almacén	Avisa a la empresa
429	RATE_LIMITED	Se superó el límite	Espera lo que indica Retry-After
500	INTERNAL_ERROR	Fallo del servidor	Reporta la reference

Ver una categoría

GET /api/v1/ecommerce/categories/{slug}

No pide token. Devuelve la categoría, con sus imágenes de portada y una página de sus productos.

Parámetro	Dónde	Obligatorio	Reglas
slug	Ruta	Sí	El slug de una categoría visible en la tienda. No acepta el id
page	Query	No	Página de productos. Entero, 1 o más. Sin él, la 1
per_page	Query	No	Productos por página. Entero entre 1 y 100. Sin él, 12
type_order	Query	No	Orden de los productos. Los mismos valores que en productos: ALFABETICO, DEFAULTDESC, STOCKASC, STOCKDESC, SKUALFABETICO o ALEATORIO

curl "https://<dominio-de-la-empresa>/api/v1/ecommerce/categories/ropa?per_page=12&page=1&type_order=ALFABETICO" \
  -H "Accept: application/json"

Aquí ALEATORIO sí mezcla los productos. Cada petición mezcla de nuevo, así que al pasar de página un producto puede repetirse o no salir. Sin type_order, los productos salen sin un orden definido.

Qué productos trae

• Solo los que se asociaron a la categoría desde la tienda. Un producto que tiene esta categoría solo como categoría principal en su ficha del ERP no sale aquí, aunque sí sale en POST shop/products con categories: ["ropa"].
• Marcados para la tienda, que no sean servicios y dados de alta en el almacén de la tienda.
• Si la tienda muestra solo productos con stock, solo los que tienen stock mayor que 0.

Respuesta

{
  "data": {
    "id": 22,
    "name": "Ropa",
    "slug": "ropa",
    "description": "Polos, casacas y más",
    "cover_desktop": "https://miempresa.ejemplo.com/storage/ecommerce/ropa-escritorio.png",
    "cover_movil": "https://miempresa.ejemplo.com/storage/ecommerce/ropa-movil.png",
    "products": [
      {
        "id": 45,
        "description": "Polo algodón premium",
        "slug": null,
        "brand": { "id": 1, "marca": "Textiles Andinos" },
        "internal_id": "P-001",
        "barcode": "7750000000011",
        "has_igv": null,
        "price": 49.9,
        "in_offer": true,
        "offer_price": 39.9,
        "prices": [],
        "stock": 60,
        "has_variants": true,
        "files": [
          {
            "id": 1828,
            "description": null,
            "is_cover": true,
            "path": "https://miempresa.ejemplo.com/attach-files/1828/preview",
            "preview": "https://miempresa.ejemplo.com/attach-files/1828/preview/small"
          }
        ],
        "variants": [
          {
            "id": 9,
            "sku": "P-001-S-NEG",
            "price": 49.9,
            "in_offer": true,
            "offer_price": 39.9,
            "stock": 20,
            "prices": [],
            "values": [
              { "id": 17, "attribute": "Talla", "value": "S", "color": null, "is_main": true },
              { "id": 18, "attribute": "Color", "value": "Negro", "color": "#111111", "is_main": false }
            ]
          }
        ],
        "currency": null,
        "unit_type": null,
        "custom_measurement": null,
        "min_order": 0,
        "weight": null
      }
    ],
    "products_count": 12,
    "pagination": { "total": 12, "per_page": 12, "current_page": 1, "last_page": 1 }
  },
  "success": true,
  "message": "Detalle de la categoria obtenido de forma correcta."
}

Campo	Qué es
description	Texto de la categoría, o null
cover_desktop, cover_movil	Imagen de portada para escritorio y para móvil, o null
products	Los productos de la página pedida
products_count	Total de productos de la categoría, contando todas las páginas
pagination.total	Lo mismo que products_count
pagination.per_page, current_page, last_page	Tamaño de página, página actual y última página

La paginación va en pagination, no en links y meta como en el listado de productos. Pedir una página más allá de la última no da error: products llega vacío.

Los productos de una categoría llegan incompletos

Hoy, cada producto de products llega con menos datos que en el listado de productos:

• slug llega null. Para enlazar a la ficha, usa el id.
• currency y unit_type llegan null. La moneda no se puede saber desde aquí.
• has_igv llega null.
• Las variantes no traen files.
• Si el producto no tiene imágenes en la tienda, la imagen de reserva de files apunta a una dirección que no carga.

Si necesitas esos datos, pide los productos con POST shop/products y categories: ["<slug>"], o la ficha de cada uno. Ten en cuenta que ese filtro también incluye los productos que tienen la categoría como principal, así que el total puede no coincidir con products_count.

Si algo sale mal

HTTP	code	Cuándo	Qué hacer
404	STORE_NOT_FOUND	La tienda no está publicada	La empresa debe publicarla desde el ERP
503	STORE_PAUSED	La tienda está pausada	Reintenta más tarde (Retry-After)
404	CATEGORY_NOT_FOUND	No hay una categoría con ese slug, o la empresa la ocultó en la tienda	Revisa el slug en el listado de categorías
422	VALIDATION_ERROR	page, per_page o type_order no son válidos	Corrige el parámetro que indica errors
503	STORE_NOT_CONFIGURED	El ERP no tiene ningún almacén	Avisa a la empresa
429	RATE_LIMITED	Se superó el límite	Espera lo que indica Retry-After
500	INTERNAL_ERROR	Fallo del servidor	Reporta la reference

Los mensajes de validación son: «La página debe ser un número entero.», «La primera página es la 1.», «El número de productos por página debe ser un número entero.», «El número de productos por página debe ser 1 o más.», «El máximo de productos por página es 100.» y, para type_order, «El orden solicitado no existe. Válidos: ALFABETICO, DEFAULTDESC, STOCKASC, STOCKDESC, SKUALFABETICO, ALEATORIO.».