Referencia de API
EZY Integrations expone una API REST para tenants que necesitan interactuar con la plataforma de forma programática — por ejemplo, para disparar ejecuciones de trabajos desde un planificador externo, enviar datos vía webhook, o construir paneles personalizados que consuman el historial de ejecuciones. Todas las solicitudes requieren una clave de API válida emitida para tu tenant.
Autenticación
Sección titulada «Autenticación»Cada solicitud a la API debe incluir la clave de API en el encabezado Authorization usando el esquema ApiKey:
Authorization: ApiKey <tu-clave-de-api>Las claves de API están limitadas al scope del tenant. Una clave emitida para un tenant no puede acceder a los datos de otro tenant. Para crear, rotar o revocar claves de API, consulta Claves de API.
Explorador interactivo de la API
Sección titulada «Explorador interactivo de la API»Una referencia de API interactiva integrada está disponible en cada instancia en ejecución de EZY Integrations. Ábrela desde tu navegador mientras la aplicación está en funcionamiento — la ruta exacta se muestra en el área de ayuda o configuración de la aplicación. El explorador te permite probar solicitudes directamente contra la API activa sin escribir código.
Grupos de endpoints
Sección titulada «Grupos de endpoints»La API está organizada en los siguientes grupos. Cada grupo admite operaciones CRUD estándar y está limitado al scope de tu tenant.
| Grupo | Qué gestiona |
|---|---|
| Perfiles de Conexión | Crear, leer, actualizar, eliminar y probar perfiles de conexión para sistemas fuente y destino. |
| Configuraciones de Mapeo | Gestionar los documentos JSON de mapeo que controlan las reglas de extracción, normalización y transformación. |
| Instancias | Crear, leer, actualizar, activar, desactivar y eliminar instancias de trabajo. |
| Programaciones | Crear y gestionar programaciones basadas en cron que disparan ejecuciones de trabajos automáticamente. |
| Registros de Sincronización | Leer el historial de ejecuciones, el estado y los detalles de error por entidad. |
| Cola de Mensajes Fallidos (DLQ) | Listar, inspeccionar, reintentar y descartar mensajes fallidos. |
| Webhooks | Recibir envíos de datos entrantes de sistemas externos (webhooks de Shopify y payloads genéricos). |
| Eventos de Sincronización | Disparar una ejecución de trabajo programáticamente y consultar su estado de finalización. |
Envío de datos entrantes (webhook)
Sección titulada «Envío de datos entrantes (webhook)»Los sistemas externos pueden enviar datos directamente al pipeline de integración sin pasar por una extracción programada. La plataforma valida la solicitud, la enruta a la instancia correcta y procesa el payload a través de las mismas cinco etapas que una ejecución programada.
El conector de Shopify admite entrega nativa de webhooks (actualizaciones de productos, creación de pedidos y eventos similares). Para otros sistemas, un endpoint entrante genérico acepta payloads arbitrarios y los enruta a la instancia de trabajo que elijas.
Consulta Configuración de Tenant para saber cómo configurar el acceso de webhook entrante.
Disparador de sincronización programático
Sección titulada «Disparador de sincronización programático»Puedes disparar una ejecución de trabajo desde una llamada de sistema externo en lugar de esperar a una programación. Después de disparar, la respuesta incluye un ID de correlación que usas para consultar el endpoint de Eventos de Sincronización y conocer el estado de finalización de la ejecución y los recuentos (total de registros, exitosos, fallidos, omitidos).
Esto es útil para pipelines basados en eventos donde un sistema upstream señala que hay nuevos datos disponibles.
Paginación
Sección titulada «Paginación»Los endpoints de listado que pueden devolver muchos registros admiten paginación. Las solicitudes aceptan los parámetros de consulta page y pageSize. Las respuestas incluyen un recuento total para que puedas calcular el número de páginas.
Concurrencia optimista (ETag)
Sección titulada «Concurrencia optimista (ETag)»Las operaciones de actualización y eliminación en recursos de configuración (perfiles de conexión, instancias, configuraciones de mapeo, programaciones) utilizan concurrencia optimista basada en ETag. Cuando obtienes un recurso, la respuesta incluye un encabezado ETag. Debes incluir ese valor en el encabezado If-Match de tu solicitud de actualización o eliminación. Si el recurso fue modificado por otra solicitud entre tu lectura y tu escritura, el servidor devuelve una respuesta 412 Precondition Failed. Obtén el recurso nuevamente para tener la versión más reciente y vuelve a intentar tu actualización.
Páginas relacionadas
Sección titulada «Páginas relacionadas»- Claves de API — Cómo crear y gestionar claves de API.
- Configuración de Tenant — Configuración inicial, incluyendo la configuración de webhook entrante.
- DLQ y Reintento — Cómo usar los endpoints de la DLQ o la interfaz de usuario.