Migración de plataforma

Migrar tu tienda online de una plataforma a otra — por ejemplo, de Magento 2 a Shopify, o de WooCommerce a BigCommerce — implica mucho más que simplemente reinstalar la extensión de Clerk.io.

Es probable que los IDs de tus productos cambien. Deberás cambiar tu método de sincronización. Tus diseños pueden hacer referencia a nombres de atributos específicos de la plataforma. Y tus datos históricos de pedidos deben transferirse para que la IA siga funcionando desde el primer día.

Esta guía te acompaña en cada paso.

Antes de empezar #

Antes de realizar cualquier cambio en Clerk.io, responde a estas dos preguntas:

¿Cambiarán los IDs de tus productos? La mayoría de las migraciones de plataforma asignan nuevos IDs a los productos. Esto es importante porque la IA de Clerk.io vincula productos con pedidos usando el campo id. Si los IDs cambian, los pedidos antiguos harán referencia a IDs que ya no existen en el nuevo catálogo.

¿Puedes hacer coincidir los IDs de producto con el historial de pedidos? Si puedes mapear los IDs antiguos de los productos con los nuevos (o conservarlos completamente), puedes mantener tu Store de Clerk.io existente, independientemente de si el dominio cambia o no. El historial de pedidos del Store se mantiene intacto y la IA conserva sus asociaciones aprendidas.

Si el mapeo de IDs no es viable y no puedes reconciliar los pedidos antiguos con los productos nuevos, crea un nuevo Store en my.clerk.io y comienza desde cero. El dominio en sí no es el factor determinante.

1. Mapea los IDs #

Este es el paso más importante. Si tu nueva plataforma asigna nuevos IDs de producto, debes decidir cómo gestionar la discrepancia entre los pedidos antiguos y los productos nuevos.

Hay dos enfoques:

Opción A — Conservar los IDs antiguos Configura la sincronización de tu nueva plataforma para enviar los mismos valores de id que se usaban en la antigua plataforma. Muchas plataformas permiten incluir un campo de ID heredado o externo en el feed de datos.

Envía el ID de producto de la plataforma antigua como id en tu feed de Clerk.io o en las llamadas a la API CRUD. Así, tu historial de pedidos existente seguirá mapeando correctamente con el nuevo catálogo.

Opción B — Remapear y volver a subir los pedidos Si no puedes conservar los IDs, deberás crear una tabla de mapeo tú mismo — fuera de Clerk.io — que traduzca los IDs de producto antiguos a los nuevos. Una vez que tienes ese mapeo, vuelves a subir los pedidos históricos con los IDs corregidos.

Clerk.io no realiza este mapeo por ti. Tu desarrollador crea un conjunto corregido de datos de pedidos y tú los subes.

Construyendo la tabla de mapeo El enfoque más sencillo es utilizar el SKU del producto como puente. Los SKUs casi siempre se mantienen al migrar de plataforma, incluso cuando los IDs internos de la base de datos cambian.

El proceso es el siguiente:

1. Exporta todos los pedidos de la plataforma antigua, con cada línea del pedido incluyendo el ID de producto antiguo y su SKU.
2. Consulta la base de datos de la nueva plataforma para encontrar cada producto por su SKU y obtener su nuevo ID.
3. Sustituye los IDs antiguos por los nuevos en los datos de los pedidos.

Un ejemplo simple en pseudocódigo:

for order in old_orders:
    for line in order.products:
        new_id = new_platform.find_product_by_sku(line.sku).id
        line.product_id = new_id

El resultado es una lista de pedidos corregidos donde todas las referencias de productos utilizan los IDs de la nueva plataforma.

Subiendo los pedidos corregidos Una vez completado el mapeo, sube los pedidos corregidos a Clerk.io. Hay dos formas de hacerlo:

A través de la API CRUD:

POST https://api.clerk.io/v2/order/add

{
  "key": "your_public_api_key",
  "orders": [
    {
      "id": 5001,
      "products": [901, 902],
      "time": 1622548800,
      "email": "luke@skywalker.com"
    }
  ]
}

O mediante un feed de datos JSON que incluya el array completo de pedidos corregidos. El importador lo procesará en la próxima sincronización. Esta suele ser la opción más simple para grandes volúmenes de pedidos históricos.

En cualquier caso, 901 y 902 son los IDs de producto de la nueva plataforma — no los antiguos.

2. Cambia la Sincronización #

Una vez que tu estrategia de IDs esté definida, actualiza el método de sincronización en Clerk.io para apuntar a la nueva plataforma.

1. Ve a Data > Configuration en my.clerk.io.
2. Cambia el Sync method a la integración de tu nueva plataforma o a la URL del feed.
3. Verifica los indicadores de Import — asegúrate de que Productos, Categorías y Pedidos estén habilitados.
4. Actualiza tu lista de IPs permitidas si la nueva plataforma tiene una IP de servidor diferente.
5. Haz clic en Start New Data Sync y monitorea el registro de sincronización.

Una vez finalizada la sincronización, verifica en Data > Health que los recuentos de productos y volúmenes de pedidos sean correctos.

Si tu nueva plataforma lo permite, configura actualizaciones en tiempo real mediante la extensión de la plataforma o la API CRUD para que nuevos productos y pedidos se envíen a Clerk.io en el momento — no solo en la próxima sincronización programada.

3. Actualiza los Diseños #

Los diseños hacen referencia a los atributos de producto usando la sintaxis {{ product.attribute_name }}. Si tu nueva plataforma usa nombres de atributos diferentes, esas referencias dejarán de funcionar o se mostrarán vacías.

Por ejemplo, una configuración de Magento 2 puede sincronizar un atributo personalizado llamado {{ product.manufacturer }}, mientras que Shopify envía la misma información como {{ product.vendor }}. Cualquier diseño que use el nombre antiguo necesitará ser actualizado.

Encontrar los diseños afectados: Utiliza el campo de búsqueda en la página Designs. Busca el nombre de atributo antiguo — la búsqueda rastrea dentro del HTML y CSS de todos los diseños, por lo que puedes localizar cada diseño que lo use.

Actualizando la referencia: Abre cada diseño afectado y reemplaza el nombre del atributo antiguo por el nuevo.

Usando Modifiers en su lugar: Si deseas evitar actualizar muchos diseños, utiliza Modifiers para crear un atributo estable en Clerk.io que haga un mapeo desde el nombre que envía la nueva plataforma.

Por ejemplo, crea un modifier que copie el atributo vendor en un nuevo atributo llamado manufacturer. Así, tus diseños actuales seguirán funcionando sin cambios:

Create new attribute: manufacturer
Value: {vendor}

Este es el enfoque con menos riesgo para configuraciones complejas con muchos diseños.

4. Continuidad de Pedidos #

Clerk.io almacena los pedidos de forma independiente al catálogo de productos. Los pedidos registrados nunca se eliminan al quitar productos de una sincronización o feed — permanecen como registros históricos y continúan influyendo en la IA.

Cuando cambias de plataforma, esto significa:

• Los pedidos registrados con los IDs de producto antiguos permanecen en el Store.
• Los nuevos pedidos registrados con los nuevos IDs de producto empiezan a acumularse.
• Hasta que haya suficientes nuevos pedidos, puede que observes una calidad de personalización reducida en lógicas como Visitor Recommendations y Best Cross-Sell Products.

Para acelerar esto, reimporta tus pedidos históricos con los nuevos IDs de producto (ver Paso 1, Opción B). Así la IA tendrá una visión completa desde el primer día, en lugar de empezar desde cero.

Si tienes un alto volumen de pedidos, prioriza los pedidos más recientes de los últimos 12–24 meses. El comportamiento de compra reciente tiene mayor peso para la IA que los datos antiguos.

5. Verifica el Tracking #

Después de publicar la nueva plataforma, confirma que el tracking de ventas funciona de extremo a extremo.

Verifica lo siguiente:

1. La llamada log/sale se dispara en la página de confirmación de pedido con los IDs de productos nuevos.
2. Los pedidos aparecen en Data > Orders con IDs de productos que coinciden con el nuevo catálogo.
3. Data > Health muestra verde para Sales tracking y Clerk sales.

Si el tracking falla, la atribución de clic-a-compra no funcionará y el reporte de impacto en ingresos estará incompleto. La guía de Sales Tracking explica cómo configurarlo y depurarlo.

Ejemplo paso a paso #

Así se ve una migración de Magento 2 a Shopify de principio a fin.

Antes de la migración (Magento 2):

• Los productos sincronizados con los entity IDs de Magento (por ejemplo, id: 4521)
• Los diseños usan {{ product.manufacturer }} para la marca
• Los pedidos se registran mediante la extensión de Magento

Paso 1 — Mapeo de IDs: Exporta todos los pedidos históricos de Magento con los IDs de producto y SKUs. Consulta Shopify para encontrar cada producto por SKU y obtener el nuevo ID de Shopify. Sustituye los IDs antiguos en los datos de pedidos, luego sube los pedidos corregidos a Clerk.io mediante la API CRUD o un feed JSON.

Paso 2 — Cambia la sincronización: En Data > Configuration, cambia el método de sincronización de la integración de Magento 2 a la integración de Shopify. Ejecuta una sincronización completa.

Paso 3 — Corrige los diseños: Busca en los diseños manufacturer. Cámbialo por {{ product.vendor }} (el campo de Shopify), o añade un Modifier que mapee vendor → manufacturer para mantener los diseños sin cambios.

Paso 4 — Verifica: Realiza un pedido de prueba en la nueva tienda de Shopify. Confirma que aparece en Data > Orders con los IDs de producto correctos de Shopify. Revisa Data > Health para ver los indicadores en verde.

Todo el proceso suele llevar unas horas en migraciones sencillas, y uno o dos días para catálogos grandes donde se requiere remapeo de pedidos históricos.