Conector Shopify

El conector Shopify vincula tu tienda Shopify con EZY Integrations a través de la API GraphQL de administración de Shopify. Puede leer productos, clientes y pedidos desde Shopify (dirección origen) y escribir productos e inventario de vuelta a Shopify (dirección destino). La paginación basada en cursores mantiene catálogos grandes sincronizados de forma incremental sin volver a descargar datos que no han cambiado.

Cuándo usar este conector

• Publicar el catálogo de artículos de tu ERP en Shopify para que la tienda refleje siempre los precios, descripciones y variantes actuales.
• Extraer pedidos y registros de clientes de Shopify hacia EZY Portal o un archivo plano para reportes o ingreso al ERP.
• Mantener los niveles de inventario de Shopify sincronizados con el stock del almacén en un ERP.
• Extraer datos de productos desde Shopify para procesamiento por otro sistema.

Tipos de entidad compatibles

Tipo de entidad	Dirección	Descripción
item	Origen + Destino	Productos de Shopify, incluidas variantes, metafields, imágenes y niveles de inventario.
itemstock	Destino	Actualización solo de inventario para un producto de Shopify ya existente. No modifica campos del producto, imágenes ni metafields.
customer	Origen	Registros de clientes de Shopify.
order	Origen	Documentos de pedidos de Shopify.

Nota: itemstock requiere que el producto ya exista en Shopify a partir de una sincronización previa del tipo item. Si no se encuentra el mapeo del producto, la ejecución reporta un error para ese registro.

Prerrequisitos

Antes de configurar este conector, completa los siguientes pasos en tu administrador de Shopify.

1. Crear una aplicación personalizada

1. Inicia sesión en el panel de Shopify Partners.
2. Ve a Apps y haz clic en Create app, luego elige Create app manually.
3. Ingresa un nombre descriptivo (por ejemplo, ezy-integration) y haz clic en Create.

2. Configurar los alcances de acceso a la API de administración

En la página de Configuración de la app, habilita como mínimo los siguientes Admin API access scopes:

Alcance	Requerido para
read_products, write_products	Sincronización de productos
read_publications, write_publications	Publicar productos en canales de venta
read_inventory, write_inventory	Sincronización de niveles de inventario
read_locations	Mapeo de almacenes / ubicaciones
read_customers	Extracción de clientes
read_orders	Extracción de pedidos
read_files, write_files	Carga de imágenes de productos

Haz clic en Save después de seleccionar los alcances.

3. Configurar el acceso a datos protegidos de clientes

Si extraes registros de clientes o pedidos, Shopify requiere un paso de aprobación adicional:

1. En la app, ve a API access requests y abre Protected customer data access.
2. Selecciona Store management como motivo de uso de datos.
3. En Protected customer fields, selecciona Name, Email, Phone y Address.
4. Haz clic en Save.

Sin esta aprobación, la API de Shopify rechaza las consultas que acceden a registros de Cliente o Pedido.

4. Configurar el método de distribución e instalar la app

1. En la app, ve a Distribution, selecciona Custom distribution e ingresa el dominio de la tienda destino.
2. Haz clic en Generate link, luego abre ese enlace en un navegador con sesión iniciada en la tienda destino.
3. Revisa los permisos y haz clic en Install app.

5. Obtener las credenciales

Después de la instalación, ve a la página Overview de la app para copiar el Client ID y el Client secret. Los ingresarás en el perfil de conexión.

Opcional: historial completo de pedidos

Por defecto, read_orders devuelve solo los últimos 60 días. Para acceder a todos los pedidos, solicita el alcance Read all orders en API access requests.

Campos del perfil de conexión

Al crear un perfil de conexión de Shopify en EZY Integrations, el formulario está dividido en tres secciones.

Tienda

Campo	Obligatorio	Descripción	Ejemplo
Shop domain	Sí	URL de tu tienda Shopify	https://example.myshopify.com

Autenticación

Elige entre OAuth (recomendado) o Token heredado usando los botones de radio.

Modo OAuth:

Campo	Obligatorio	Descripción	Ejemplo
Client ID	Sí	ID de cliente de la app en el panel de Shopify Partners	<CLIENT_ID>
Client secret	Sí	Secreto de cliente de la app (almacenado encriptado)	<CLIENT_SECRET>

Modo Token heredado:

Campo	Obligatorio	Descripción	Ejemplo
Access token	Sí	Token de acceso de API de administrador de una app privada	<ACCESS_TOKEN>

Hay un botón Test integrado disponible después de completar los campos de autenticación. Úsalo para confirmar la conectividad antes de guardar.

Avanzado

Campo	Obligatorio	Descripción	Ejemplo
API version	No	Versión de la API GraphQL de Shopify. Si se deja en blanco, se usa la última versión compatible.	2026-01
Webhook secret	No	Secreto HMAC para verificar los payloads de webhooks entrantes desde Shopify.	<WEBHOOK_SECRET>

Comportamiento de éxito parcial en escrituras de productos

Cuando EZY Integrations escribe un producto en Shopify, la operación consta de cinco sub-pasos encadenados. Cada sub-paso puede tener éxito o fallar de forma independiente sin bloquear a los demás. Esto se denomina el modelo de éxito parcial.

graph TD
    A[Crear / actualizar producto] --> B[Sincronización de variantes]
    B --> C[Sincronización de metafields]
    C --> D[Sincronización de imágenes y asociación con variantes]
    D --> E[Sincronización de inventario]
    A -- verificación de hash inteligente --> SKIP[Sub-paso omitido\ncontenido sin cambios]

Cómo funciona cada sub-paso:

1. Crear / actualizar producto — El registro principal del producto (título, descripción, handle, proveedor, estado, etiquetas) se escribe primero. Si este paso falla, el registro completo se marca como fallido y no se ejecutan sub-pasos.
2. Sincronización de variantes — Las variantes del producto (SKUs, precios, códigos de barra, peso, opciones) se crean o actualizan. Los conflictos de SKU en variantes individuales se registran como advertencias; las demás variantes del mismo producto se completan igual.
3. Sincronización de metafields — Los metafields personalizados se escriben después del producto. Este sub-paso solo se ejecuta cuando el contenido de los metafields ha cambiado desde la última ejecución (sincronización inteligente basada en hash).
4. Sincronización de imágenes — Las imágenes del producto se cargan o reemplazan. Una verificación de hash de contenido independiente determina qué imágenes son nuevas, actualizadas o sin cambios. Después de la carga, las imágenes se asocian con la variante correspondiente por el nombre de la opción de color.
5. Sincronización de inventario — Los niveles de stock se configuran por ubicación en Shopify. Este sub-paso solo se ejecuta cuando los valores de inventario han cambiado desde la última ejecución.

Qué verás en el historial de ejecuciones cuando falla un sub-paso

Resultado	Lo que verás
Todos los sub-pasos tienen éxito	El registro de ejecución muestra Éxito; el resumen del conector lista los conteos de variantes sincronizadas, imágenes agregadas/actualizadas/eliminadas, metafields escritos e inventario sincronizado.
Uno o más sub-pasos fallan	El registro de ejecución sigue mostrando Éxito (la escritura principal del producto fue exitosa), pero la columna Advertencias lista cada sub-paso fallido con su mensaje de error.
La escritura principal del producto falla	El registro de ejecución muestra Fallido con el código de error y el mensaje de Shopify.

Como un sub-paso fallido se trata como advertencia y no como fallo, el hash de contenido de ese sub-paso no se promueve. En la siguiente ejecución, EZY Integrations reintentará ese sub-paso aunque los datos de origen no hayan cambiado.

Cómo remediar una advertencia de sub-paso

1. Abre el Historial de Ejecuciones y haz clic en la ejecución afectada para ver el detalle completo.
2. Lee el mensaje de advertencia para identificar qué sub-paso falló (por ejemplo, “Metafield sync failed” o “Image upload failed”).
3. Corrige cualquier problema de datos en origen si el error apunta a un problema de datos (por ejemplo, una URL de imagen que devolvió un 404).
4. Ejecuta un reintento manual desde la página de Sync Trigger, o espera la próxima ejecución programada — el sub-paso fallido reintentará automáticamente.

Si la carga de imagen se completa pero Shopify no terminó de procesar el medio antes de que se ejecute el paso de asociación de imágenes a variantes, EZY Integrations espera hasta aproximadamente 15 segundos para que los medios alcancen el estado listo. Si se agota el tiempo de espera, el paso de asociación se omite y se registra como advertencia para que el siguiente ciclo lo reintente.

Limitaciones y particularidades conocidas

• Sincronización inteligente (omisión por hash): Si los datos de un producto no han cambiado desde la última ejecución exitosa, el conector omite la escritura por completo. Esto reduce el consumo de cuota de la API de Shopify y acelera las sincronizaciones de catálogos grandes.
• Reconciliación en la primera ejecución: Al escribir un producto por primera vez, el conector verifica si ya existe un producto con el mismo handle o SKU en Shopify. Si lo encuentra, convierte la creación en una actualización para evitar duplicados.
• Límite diario de variantes en Shopify: Shopify aplica un límite diario a las llamadas de productVariantsBulkCreate. Para productos con múltiples variantes, el conector usa la mutación productSet, que no está sujeta a este límite diario.
• Se requieren IDs de ubicación para inventario: La sincronización de inventario escribe los niveles de stock por ubicación de Shopify. El ID de ubicación debe estar incluido en la configuración de mapeo; de lo contrario, el sub-paso de inventario se omite o falla.
• Alcance de todos los pedidos: Sin el alcance opcional Read all orders, los pedidos extraídos se limitan a los últimos 60 días.
• Datos protegidos de clientes: La extracción de nombres, correos electrónicos, teléfonos o direcciones de clientes requiere la aprobación de Acceso a Datos Protegidos de Clientes de Shopify (ver Prerrequisitos).
• Versión de API: Si la versión de API configurada no coincide con la superficie de la API de Shopify (por ejemplo, nombres de campos renombrados entre versiones), aparecerán errores de GraphQL en el historial de ejecuciones.

Relacionado

• Etapas del Pipeline — Cómo los registros se mueven a través de las etapas Ingest, Normalize, Transform, Execute y Finalize.
• Tipos de Entidad — Lista completa de tipos de entidad y los conectores que los soportan.
• Configuración de Mapeo — Cómo configurar el mapeo de campos para un origen o destino Shopify.
• Historial de Ejecuciones — Cómo leer resultados de ejecuciones e interpretar advertencias.
• DLQ y Reintento — Cómo reintentar mensajes fallidos.
• Todos los Conectores — Compara Shopify con otros conectores disponibles.