Esta página cubre el catálogo de lectura del dominio Productos: el listado principal con filtros, la búsqueda de texto libre, el conteo, la verificación de existencia por SKU, la resolución de un producto padre a partir del SKU de una variante, los catálogos auxiliares de marcas/tipos y la búsqueda avanzada por POST.
No hay un envelope único en Productos
A diferencia de otros dominios de la API, Productos no responde con una forma de envelope consistente en todos sus endpoints. Cada endpoint de esta página documenta su forma de respuesta real — no asumas {data, meta} en ninguno salvo el caso explícito que se marca abajo.
Permiso requerido en todos los endpoints de esta página:products:read.
Único endpoint del dominio con envelope {data, meta}
Sin el parámetro availableAt, GET /products responde un arreglo plano de productos (comportamiento heredado, mostrado arriba). Cuando envías availableAt=<locationId>, la respuesta cambia de forma a un envelope con paginación:
Este es el único endpoint de todo el dominio Productos que usa este envelope. Ningún otro — ni el resto del catálogo, ni collections, ni categories, ni las rutas bulk — lo replica. No construyas tu cliente asumiendo que este contrato es general.
Este endpoint delega directamente en ProductsService.search de la librería. La auditoría confirmó los parámetros de entrada, pero no verificó línea por línea el envelope exacto de salida (arreglo plano vs. objeto envolvente). Los productos que devuelve tienen el shape real de Product (ver modelo de datos); confirma la forma exacta del contenedor contra una respuesta real antes de depender de ella.
Cuenta los productos que cumplen los filtros indicados
200
{ "count": 143 }
Acepta el mismo conjunto de filtros que el listado principal (q, status, category, brands, minPrice, maxPrice, tags, channelId, etc.); no aplica page/limit porque no pagina resultados. Cuando envías un término de búsqueda (term), la respuesta incluye además la estrategia de búsqueda usada:
{ "count": 27, "searchStrategy": "text" }
Tip
El valor exacto de searchStrategy no fue enumerado exhaustivamente en la auditoría — trátalo como informativo, no como un enum cerrado para tu lógica de negocio.
Error 400 sin código, y shape de respuesta no verificado
Si omites locationId, este endpoint responde 400 con {"error": "Missing required query parameter: locationId"} — sin un campo code, a diferencia de la convención del resto del dominio. El shape exacto de la respuesta exitosa (resultado de getProductsByLocation) tampoco fue verificado línea por línea en la auditoría; confírmalo contra una respuesta real.
Vista minimizada de productos con inventario en una ubicación (payload reducido, pensado para listas grandes)
La respuesta confirmada envuelve en {products, total} — con payload minimizado (~500 bytes por producto, contra ~3 KB del producto completo). La auditoría no enumeró el listado completo y definitivo de campos que trae cada item; el ejemplo de arriba es ilustrativo con campos que sí existen en el modelo real, no una copia exacta verificada del código.
Errores comunes de /products/inventory-view:400 bad-request/missing-param, 400 bad-request/invalid-param, 500 inventory-view/error.
Varios endpoints de Productos (este listado y GET /products/{id}) aceptan extend como una lista separada por comas de campos adicionales a incluir en la respuesta, de un conjunto cerrado:
variants, options, description, bindings, metadata, inventory, dimensions, seo, all
all incluye todos los campos extendidos disponibles. Los detalles de qué hace extend=inventory/extend=all específicamente (adjuntar inventario por variante y ubicación) se documentan en Consultar un producto, donde el parámetro tiene su efecto más completo.