Skip to main content

Integración de Shopify con ERP: cómo evitar pedidos perdidos y registros duplicados

Una integración Shopify ERP falla en los bordes: webhooks repetidos, tiempos de espera ambiguos y diferencias que nadie concilia. Este es el diseño que usamos para que ningún pedido se pierda ni se registre dos veces.

, Fundador y CEO de Shugert · · 8 min de lectura

Integración Shopify ERP con webhooks, reintentos e idempotencia, cerrada por un proceso de conciliación

Cuando un pedido se confirma en Shopify, el trabajo operativo apenas comienza. El ERP tiene que registrar la venta, el almacén debe surtir, finanzas necesita conciliar el cobro y, en México, alguien tiene que emitir el CFDI cuando el cliente lo pide. Si una conexión falla entre esos pasos, la tienda muestra una compra exitosa mientras el equipo no encuentra el pedido en su sistema administrativo, o peor, lo encuentra dos veces.

La mayoría de las integraciones Shopify ERP funcionan bien el día de la demostración. Fallan en los bordes: un webhook que llega repetido, una petición al ERP que se agota después de que el ERP sí guardó la orden, una cancelación que nunca se propaga. Este artículo describe cómo diseñamos esos bordes.

Respuesta corta

Una integración confiable entre Shopify y un ERP necesita cuatro piezas: un contrato que diga qué sistema manda en cada dato, una recepción de webhooks idempotente, una política de reintentos que distinga errores temporales de errores de datos, y una conciliación programada que compare ambos sistemas aunque la cola se vea sana. El conector, ya sea una app o código propio, es solo una de las cuatro.

1. Define qué sistema manda en cada dato

Antes de elegir una app o escribir código, documenta el origen autorizado de cada campo. Sin ese contrato, dos sistemas terminan escribiendo el mismo dato y gana el último que se ejecutó.

DatoDueño habitualPregunta que debe responder el equipo
SKU y catálogo maestroERP¿El SKU es único y estable por variante?
Contenido comercialShopify¿Quién edita títulos, imágenes y descripciones?
Inventario disponibleERP o WMS¿Cómo se descuentan apartados y stock de seguridad?
Pedido en líneaShopify al originarse¿Qué identificador guarda el ERP para rastrearlo?
Surtido y guíaWMS o 3PL¿Cómo regresa el número de guía a Shopify?
Facturación (CFDI)ERP o app de facturación¿Quién timbra, con qué datos fiscales y cuándo?
Contabilidad y conciliaciónERP¿Cómo se relacionan cobros, devoluciones y ajustes?

En México, la facturación merece su propia fila. El cliente puede pedir factura en el checkout, después desde un portal o por correo, y el RFC, régimen fiscal, uso de CFDI y código postal fiscal tienen que llegar íntegros al sistema que timbra. Muchas marcas resuelven esto con una app de facturación conectada a Shopify y dejan al ERP solo la contabilidad; otras timbran desde CONTPAQi, SAP Business One u Odoo. Las dos opciones funcionan si el contrato dice cuál es la fuente de verdad del dato fiscal y qué pasa cuando el cliente corrige su RFC después de la compra. Revisa el flujo con tu contador antes de automatizarlo.

2. Recibe webhooks como si siempre llegaran repetidos

Shopify documenta que una app puede recibir el mismo webhook más de una vez, por ejemplo después de un tiempo de espera o un reintento. Si tu endpoint no responde con un código 2XX, Shopify reintenta la entrega 8 veces durante las siguientes 4 horas, y tiene un tiempo de espera de 5 segundos para toda la solicitud (documentación de Shopify). Dos consecuencias prácticas: no puedes hacer el trabajo pesado dentro de la petición, y tienes que asumir duplicados.

Las cabeceras que importan:

  • X-Shopify-Hmac-SHA256: firma HMAC-SHA256 del cuerpo crudo, en base64, calculada con el secreto de tu app.
  • X-Shopify-Webhook-Id: identificador de la entrega. Úsalo para descartar entregas repetidas.
  • X-Shopify-Event-Id: compartido por las entregas que provienen de la misma acción del comerciante cuando tienes varias suscripciones al mismo tema. Úsalo para correlacionarlas.

Un receptor robusto separa recibir de procesar:

js
app.post("/webhooks/orders-create", express.raw({ type: "application/json" }), async (req, res) => {
  // 1. Verifica la firma sobre el cuerpo crudo, nunca sobre el JSON ya parseado.
  if (!verifyHmac(req.body, req.get("X-Shopify-Hmac-SHA256"))) return res.sendStatus(401);

  // 2. Registra la entrega de forma atómica; si ya existía, es un duplicado.
  const webhookId = req.get("X-Shopify-Webhook-Id");
  const isNew = await db.insertIfAbsent("webhook_deliveries", { id: webhookId });
  if (!isNew) return res.sendStatus(200);

  // 3. Encola y responde rápido; el ERP no se toca dentro de esta petición.
  await queue.add("sync-order", { orderId: JSON.parse(req.body).admin_graphql_api_id });
  res.sendStatus(200);
});

Este código evita procesar dos veces la misma entrega, pero no resuelve todo. La deduplicación de entregas y la idempotencia de la operación son problemas distintos: dos entregas diferentes pueden referirse al mismo pedido, y un worker puede caerse a mitad del proceso. Por eso el worker también necesita su propia llave.

3. Haz idempotente la operación en el ERP

El caso que más pedidos duplica es este: el worker llama al ERP, el ERP guarda la orden, la respuesta se pierde por un tiempo de espera, y el worker reintenta creando una segunda orden. La solución no es reintentar menos, es que reintentar sea seguro:

  1. Construye una llave de negocio estable, por ejemplo tienda + id del pedido + tipo de operación.
  2. Guárdala como referencia externa en el ERP. Casi todos los ERPs tienen un campo para esto.
  3. Ante un resultado ambiguo, busca primero esa referencia en el ERP. Si existe, registra el éxito; si no, crea.
  4. Guarda el identificador que devolvió el ERP, el número de intentos y el resultado. Ese registro es la base de la conciliación.

Si el ERP no permite buscar por referencia externa, ese es un hallazgo de arquitectura que hay que resolver antes del lanzamiento, no un detalle de implementación.

4. Reintenta según el tipo de error

Tipo de errorEjemploRespuesta correcta
TemporalERP fuera de servicio, 503, tiempo de esperaReintento limitado con espera exponencial y variación aleatoria
Límite de APIShopify devuelve throttlingEsperar según el costo disponible y reintentar
Dato inválidoSKU inexistente en el ERP, RFC mal formadoEnviar a revisión humana; reintentar no lo arregla
Regla de negocioCliente sin crédito, dirección rechazadaEnviar al responsable del proceso, con contexto

La GraphQL Admin API de Shopify limita por costo calculado de la consulta con un modelo de cubeta que se vacía a una tasa constante, y el tamaño de la cubeta varía según el plan (límites de API). La respuesta incluye el costo y el estado de la cubeta; úsalos para regular el ritmo en lugar de depender solo del código HTTP.

La cola de errores debe guardar referencia al registro, tipo de falla, intentos y responsable. No guardes datos personales innecesarios en los logs, y define cómo reprocesar un evento una vez corregido el dato.

5. Concilia aunque la cola se vea sana

Una cola vacía no prueba que Shopify y el ERP coincidan. Un webhook puede no haberse suscrito nunca, un usuario puede haber editado un pedido directamente en el ERP, o una cancelación pudo no propagarse. La conciliación es la red de seguridad:

  • Diario: pedidos del día en Shopify contra pedidos con referencia externa en el ERP, comparando conteo, importes, impuestos y estado.
  • Diario: cancelaciones y devoluciones, que son los eventos que más se pierden.
  • Por hora en temporadas altas (Buen Fin, Hot Sale): pedidos sin referencia en el ERP después de cierto tiempo.

Cada diferencia debe dejar rastro: cuándo se detectó, valor esperado, valor encontrado y acción tomada. Y nunca apliques un cambio viejo encima de uno más reciente; compara marcas de tiempo o versiones antes de escribir.

Pruebas antes del lanzamiento

Antes de conectar producción, ejecuta como mínimo:

  1. Un pedido normal con factura solicitada.
  2. Un pedido con descuento, envío gratis y dos ubicaciones de surtido.
  3. Una devolución parcial y una cancelación.
  4. El mismo webhook entregado dos veces.
  5. Una caída del ERP durante diez minutos y su recuperación.
  6. Un tiempo de espera después de que el ERP ya guardó la orden.

La prueba se aprueba cuando el resultado es correcto en ambos sistemas y además el equipo vio la alerta que correspondía. Una integración que se recupera en silencio pero que nadie monitorea solo traslada el problema a fin de mes.

Preguntas frecuentes

¿Conviene usar una app de integración o desarrollar la conexión con el ERP?

Una app es suficiente cuando tu ERP tiene un conector mantenido, tus reglas caben en su configuración y el proveedor te deja ver errores y reprocesar eventos. El desarrollo a medida se justifica cuando hay reglas de inventario, facturación o crédito que la app no modela, o cuando necesitas conciliación y alertas que la app no ofrece.

¿Cómo evito pedidos duplicados en el ERP si Shopify reintenta webhooks?

Deduplica la entrega con X-Shopify-Webhook-Id y además haz idempotente la creación en el ERP con una referencia externa estable por pedido. Ante un resultado ambiguo, consulta esa referencia antes de crear otra orden.

¿Los webhooks son suficientes para mantener Shopify y el ERP sincronizados?

No. Los webhooks comunican cambios rápido, pero se pueden perder suscripciones, fallar durante horas o quedar desplazados por ediciones manuales. Una conciliación programada que compare pedidos, importes y estados es la que garantiza que ambos sistemas coincidan.

¿Dónde se emite el CFDI en una integración Shopify ERP?

Depende del contrato de datos. Puede timbrarse desde una app de facturación conectada a Shopify o desde el ERP. Lo importante es que un solo sistema sea responsable, que los datos fiscales lleguen completos y que exista un proceso para correcciones de RFC después de la compra.

Siguiente paso

Si estás planeando una migración completa y no solo la integración, la guía de migración a Shopify ubica estas decisiones dentro del plan de datos y lanzamiento. Para inventario multi-bodega, revisa sincronización de inventario con ERP, WMS y 3PL, que comparte el mismo contrato de datos pero tiene problemas de concurrencia propios.

Sigue leyendo

Si el trabajo depende de datos de sistemas externos, define las integraciones de Shopify con ERP y otros sistemas junto con las reglas de sincronización y validación.