Cuando una tienda actualiza su catálogo desde un proveedor o un sistema de gestión, no basta con copiar nombres y precios. También hay que mantener las características que ayudan a describir y encontrar cada producto: color, capacidad, materiales o funciones. Si esas características se gestionan solo a mano, cada nueva carga obliga a repetir trabajo y aumenta el riesgo de crear valores duplicados o de perder asociaciones ya revisadas.
Hemos ampliado la API REST v2 de ShopinCloud para que una integración pueda administrar grupos, valores y conjuntos de atributos, relacionar los conjuntos con categorías y actualizar las características de los productos mediante sus identificadores. El objetivo es que el catálogo conserve una estructura coherente mientras se automatizan tareas repetitivas.
Del atributo aislado a una estructura reutilizable
Un atributo no vive solo. Un grupo puede reunir, por ejemplo, los valores de una característica técnica. Varios grupos forman un conjunto, y ese conjunto puede vincularse a una categoría. Así, los productos de una misma familia comparten una estructura de ficha sin tener que crear un grupo nuevo para cada artículo.
La ampliación permite consultar, crear y editar grupos y valores; crear conjuntos; añadir o retirar grupos de un conjunto; definir su orden dentro de él; y asignar un conjunto a una categoría. Las lecturas devuelven los identificadores reales y las traducciones del idioma solicitado. Esto ayuda a que el sistema externo trabaje con registros concretos, aunque sus nombres visibles cambien con el tiempo.
El orden de los grupos pertenece a cada conjunto. Reordenar un conjunto no altera el orden global del grupo ni el de otros conjuntos que lo reutilizan. Los valores, en cambio, mantienen hoy su orden global dentro del grupo: no existe un orden diferente de valores para cada conjunto.
Actualizar una ficha sin borrar lo que ya tenía
La operación más importante para una sincronización diaria es la asignación de atributos al producto. La API permite leer sus asociaciones actuales por ID, conocer el conjunto aplicable y añadir valores existentes sin sustituir los demás. También permite retirar una sola asociación sin eliminar el valor del catálogo ni quitarlo de otros productos.
Imagina una ficha que ya tiene asociadas las características de color y material. Si el proveedor aporta una nueva función, la integración puede añadir solo ese valor. Los dos anteriores permanecen. Antes de guardarlo, la API comprueba que el valor existe y que su grupo pertenece al conjunto aplicable a ese producto. Si no encaja, rechaza esa asignación en lugar de incorporarla silenciosamente.
Las nuevas rutas usan una versión del estado leído y la identidad del conjunto esperado. Si otro proceso modifica esas asociaciones entre la lectura y la escritura, la integración recibe un conflicto y puede releer la ficha antes de decidir qué hacer. Repetir la asignación de un valor ya presente no crea un segundo vínculo.
Lotes para catálogos que cambian cada día
Trabajar producto a producto no siempre es práctico. La nueva operación masiva admite lotes de hasta 100 fichas y aplica la misma semántica de fusión: los valores enviados se añaden sin borrar los atributos existentes que no figuran en la solicitud.
El resultado se detalla por producto. Si una ficha falla por un ID inexistente, un valor incompatible o una versión obsoleta, las demás pueden guardarse. Esto permite revisar los errores concretos y reintentar solo las fichas pendientes, siempre después de releer su estado. La API distingue lo guardado, lo que ya estaba asociado y lo rechazado.
Guardar datos y verlos en la tienda son dos comprobaciones distintas
Una respuesta de escritura confirma el resultado de persistencia, pero no demuestra por sí sola que todas las páginas públicas ya muestran la información nueva. La ampliación incluye un mecanismo para solicitar la actualización de la vista de atributos de productos concretos y la recarga de la caché del escaparate. La respuesta indica si esa actualización se ha solicitado; la visibilidad final debe comprobarse por separado en la tienda.
Qué revisar antes de conectar tu sistema
- Definir qué sistema es la fuente de verdad para cada grupo, valor y conjunto, y trabajar con IDs canónicos.
- Elegir el idioma de catálogo de forma explícita y comprobar las traducciones disponibles.
- Probar las asignaciones con productos autorizados y verificar que otros atributos y campos de la ficha permanecen intactos.
- Gestionar los conflictos de versión y los resultados parciales de los lotes antes de automatizar los reintentos.
- Comprobar la ficha pública después de la actualización de caché, sin confundir datos guardados con datos ya visibles.
La API devuelve el resultado de cada operación y el estado por producto en los lotes. Un historial consultable de antes y después con identificador propio de auditoría es una capacidad diferente que todavía no forma parte de esta ampliación. Para una integración que necesite ese seguimiento, conviene conservar también sus registros de sincronización.
Si ya organizas tu catálogo mediante integraciones, puedes consultar la documentación de la API v2 . También explicamos cómo gestionar la estructura de categorías mediante API . Si necesitas conectar tus atributos con un proveedor, ERP u otra fuente de datos, cuéntanos cómo se organiza tu catálogo y qué cambios quieres automatizar.
