Catálogo

Qué es

El catálogo es la parte de la API que muestra lo que vende la tienda: productos con sus precios, stock, imágenes y variantes, las categorías, los banners de la portada y los atributos con los que se filtra (talla, color…).

Es de solo lectura y no pide token: lo puede llamar el navegador del visitante o el servidor de la tienda. No crea pedidos ni cambia datos; para comprar, ver el carrito.

Requisitos

• Tienda publicada. Todas las rutas, salvo shop/tables, se cortan si la empresa no ha publicado la tienda:
  • 404 STORE_NOT_FOUND si nunca se publicó.
  • 503 STORE_PAUSED si estuvo publicada y ahora está cerrada. Trae la cabecera Retry-After: 3600 (segundos).
• Almacén de la tienda. El stock se calcula en el almacén que la empresa eligió para la tienda. Si no eligió ninguno, se usa el primero del ERP. Si el ERP no tiene ningún almacén, las rutas con productos responden 503 STORE_NOT_CONFIGURED.

shop/tables responde aunque la tienda no esté publicada, porque es la llamada con la que la tienda sabe su propio estado. En ese caso devuelve los ajustes y el logo, pero el catálogo llega vacío. Ver todo en una llamada.

Vista previa. Con la tienda sin publicar, la empresa puede ver su catálogo añadiendo a cualquier ruta ?geor_preview=<token-de-vista-previa>. Ese token lo genera el ERP en el enlace de vista previa de la tienda; con uno incorrecto, las rutas responden como si la tienda no estuviera publicada.

Límites

Todas las rutas del catálogo están en el cupo general: 300 peticiones por minuto por dirección IP. Si la empresa declara la IP del servidor de su tienda, ese servidor tiene un cupo propio de 3000 por minuto. Ver límites.

Las respuestas cambian poco: guárdalas en caché, sobre todo categorías, banners, atributos y ajustes.

Rutas

Todas cuelgan de /api/v1/ecommerce.

Método	Ruta	Para qué	Documento
POST	shop/products	Listado de productos, con filtros, orden y paginación	Productos
GET	shop/products/{id}	Ficha de un producto, por id o por slug	Ficha del producto
GET	shop/product-ratio/{id}	Productos relacionados	Productos relacionados
GET	categories	Categorías visibles en la tienda	Categorías
GET	categories/{slug}	Una categoría con sus productos	Categorías
GET	banners	Banners activos de la portada	Banners
GET	shop/attributes	Atributos para filtrar (talla, color…), con sus valores	Atributos
GET	shop/tables	Categorías, atributos, banners, textos legales y ajustes juntos	Todo en una llamada

Los ajustes de la tienda están en ajustes y los textos legales en textos legales.

Qué productos aparecen

Un producto sale en el catálogo si:

• Está marcado para mostrarse en la tienda virtual.
• No es un servicio (unidad ZZ).
• En los listados, además, está dado de alta en el almacén de la tienda. La ficha no mira el almacén.
• Si la tienda tiene activado «mostrar solo productos con stock» (ecommerce_show_only_stock), los listados solo traen los que tienen stock mayor que 0. La ficha sí devuelve un producto sin stock.

Errores comunes

Los errores tienen la forma común de la API: success, code, message, errors y, en los fallos del servidor, reference. Ver respuestas y errores.

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. Trae la cabecera Retry-After
503	STORE_NOT_CONFIGURED	El ERP no tiene ningún almacén	Avisa a la empresa
422	VALIDATION_ERROR	Un filtro o parámetro no es válido	Corrige el campo que indica errors
405	METHOD_NOT_ALLOWED	Se usó otro método, por ejemplo GET shop/products	El listado de productos es POST
429	RATE_LIMITED	Se superó el límite	Espera lo que indica Retry-After
500	INTERNAL_ERROR	Fallo del servidor	Reporta la reference