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.
Samuel Noriega, Fundador y CEO de Shugert · · 8 min de lectura

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ó.
| Dato | Dueño habitual | Pregunta que debe responder el equipo |
|---|---|---|
| SKU y catálogo maestro | ERP | ¿El SKU es único y estable por variante? |
| Contenido comercial | Shopify | ¿Quién edita títulos, imágenes y descripciones? |
| Inventario disponible | ERP o WMS | ¿Cómo se descuentan apartados y stock de seguridad? |
| Pedido en línea | Shopify al originarse | ¿Qué identificador guarda el ERP para rastrearlo? |
| Surtido y guía | WMS 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ón | ERP | ¿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:
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:
- Construye una llave de negocio estable, por ejemplo
tienda + id del pedido + tipo de operación. - Guárdala como referencia externa en el ERP. Casi todos los ERPs tienen un campo para esto.
- Ante un resultado ambiguo, busca primero esa referencia en el ERP. Si existe, registra el éxito; si no, crea.
- 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 error | Ejemplo | Respuesta correcta |
|---|---|---|
| Temporal | ERP fuera de servicio, 503, tiempo de espera | Reintento limitado con espera exponencial y variación aleatoria |
| Límite de API | Shopify devuelve throttling | Esperar según el costo disponible y reintentar |
| Dato inválido | SKU inexistente en el ERP, RFC mal formado | Enviar a revisión humana; reintentar no lo arregla |
| Regla de negocio | Cliente sin crédito, dirección rechazada | Enviar 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:
- Un pedido normal con factura solicitada.
- Un pedido con descuento, envío gratis y dos ubicaciones de surtido.
- Una devolución parcial y una cancelación.
- El mismo webhook entregado dos veces.
- Una caída del ERP durante diez minutos y su recuperación.
- 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.