Descripción General de la Arquitectura

EZY Integrations conecta sistemas fuente (como un ERP o una tienda de comercio electrónico) con sistemas destino (como EZY Portal o un archivo plano) enrutando los datos a través de un formato neutro compartido llamado entidad canónica. Este diseño permite agregar un nuevo conector fuente o destino sin reescribir cada mapeo existente: todos los conectores hablan el mismo lenguaje intermedio.

Cada integración se configura como un trabajo que vincula un perfil de conexión fuente con un perfil de conexión destino usando una o más configuraciones de mapeo. Cuando un trabajo se ejecuta, los datos transitan por cinco etapas del pipeline: ingestión, normalización, transformación, ejecución y finalización.

Flujo de datos

flowchart LR
    A[Sistema Fuente] -->|Extractor lee datos| B[Registros Crudos]
    B -->|Normalizador convierte| C[Entidad Canónica]
    C -->|Transformador da forma| D[Payload Destino]
    D -->|Conector escribe| E[Sistema Destino]
    E -. writeback opcional .-> A

La entidad canónica es el punto de pivote de este diseño. Es un formato de registro neutro que todos los conectores entienden. El conector fuente extrae datos crudos y los convierte en una entidad canónica; el conector destino lee esa entidad canónica y produce el payload que el sistema destino espera. Ningún sistema fuente se comunica directamente con ningún sistema destino.

Las cinco etapas del pipeline

Cada registro pasa por cinco etapas en orden. Si una etapa falla, el registro se reintenta automáticamente. Tras agotar todos los reintentos, el registro pasa a la Cola de Mensajes Fallidos para revisión manual.

Etapa	Qué ocurre
Ingestión	El trabajo lee registros del sistema fuente usando las credenciales del perfil de conexión y las reglas de extracción de la configuración de mapeo.
Normalización	Los datos crudos del sistema fuente se convierten en una entidad canónica. Esta etapa aplica conversiones de tipo y validaciones de campos requeridos.
Transformación	La entidad canónica se da forma al payload exacto que el sistema destino espera, aplicando mapeos de campos, transformadores de valores y campos estáticos de la configuración de mapeo.
Ejecución	El payload transformado se envía al sistema destino. El conector gestiona la reconciliación entre creación y actualización.
Finalización	Se registra el resultado de la ejecución. Los cursores de sincronización se actualizan para que la próxima ejecución solo recupere registros nuevos o modificados.

Consulta Etapas del Pipeline para un desglose completo de cada etapa y qué hacer cuando una etapa falla.

Sincronización incremental y cursores

La mayoría de los conectores fuente admiten sincronización incremental: en lugar de releer cada registro en cada ejecución, el sistema rastrea un cursor — generalmente una marca de tiempo de última modificación — y solo recupera los registros que cambiaron desde la ejecución anterior. El valor del cursor se guarda al final de cada etapa de finalización exitosa y se lee al inicio de la siguiente etapa de ingestión.

La columna del cursor se configura en el bloque de extracción de tu configuración de mapeo. Consulta Configuración de Mapeo para más detalles.

Componentes clave

Componente	Qué es
Perfil de conexión	Credenciales guardadas para un sistema (fuente o destino).
Configuración de mapeo	Documento JSON que controla las reglas de extracción, normalización y transformación para un tipo de entidad.
Trabajo (instancia)	Vincula un perfil fuente con un perfil destino y contiene una o más configuraciones de mapeo.
Ejecución	Una corrida de un trabajo — produce un resultado de éxito, éxito parcial o fallo.
Tipo de entidad	El tipo de registro que se mueve: artículo, socio de negocio, pedido, etc.
Entidad canónica	El formato intermedio neutro que comparten todos los conectores.
Cola de Mensajes Fallidos	Almacena registros que fallaron todos los reintentos automáticos, listos para reintento manual.

Relacionado

• Etapas del Pipeline — Desglose detallado de cada etapa, comportamiento ante fallos y lógica de reintentos.
• Tipos de Entidad — Lista completa de tipos de entidad admitidos y qué conectores los gestionan.
• Configuración de Mapeo — Cómo crear el documento JSON que controla la extracción, normalización y transformación.