Conector API Genérica

El conector API Genérica entrega registros transformados a cualquier endpoint HTTP o REST. Es un conector solo de destino — recibe registros que ya han sido extraídos, normalizados y transformados por el pipeline y los envía como solicitudes HTTP a un endpoint que tú especificas. Úsalo para integrar con cualquier sistema que acepte datos estructurados vía HTTP pero que no tenga un conector dedicado.

Cuándo usar este conector

• Necesitas enviar datos a una API interna personalizada o microservicio.
• Quieres reenviar registros a una plataforma SaaS de terceros que acepta solicitudes POST tipo webhook.
• Estás enviando datos a un endpoint de ingesta de un almacén de datos o herramienta analítica.
• El sistema destino tiene una API HTTP pero no tiene un conector nativo de EZY Integrations.

Tipos de entidad compatibles

El conector API Genérica acepta cualquier tipo de entidad. Como envía el payload transformado sin interpretar su estructura, es compatible con todos los tipos de entidad que la plataforma admite. El tipo de entidad solo afecta el formato canónico usado durante la etapa Normalize, aguas arriba de este conector.

Tipo de entidad	Nombre descriptivo
item	Artículo / Producto
bp	Socio Comercial
customer	Cliente
bpgroup	Grupo de Socios Comerciales
paymentterms	Términos de Pago
itemgroup	Grupo de Artículos
pricelist	Lista de Precios
warehouse	Almacén
taxgroup	Grupo de Impuestos
uomgroup	Grupo de Unidades de Medida
fiscalperiod	Período Fiscal
salesquotation	Cotización de Venta
salesorder	Orden de Venta
order	Pedido
booking	Reserva
subscription	Suscripción
service	Servicio
plan	Plan
menuitem	Elemento de Menú

Consulta Tipos de Entidad para ver la descripción de cada tipo.

Prerrequisitos

Antes de crear un perfil de conexión para el conector API Genérica:

• Necesitas la URL base del endpoint destino (por ejemplo, https://api.example.com/ingest).
• Necesitas las credenciales de autenticación que requiere el sistema destino (clave de API, token bearer o usuario y contraseña).
• El endpoint debe ser accesible desde el servidor que ejecuta EZY Integrations. Si el destino usa un certificado TLS autofirmado, deberás habilitar la opción Omitir verificación TLS.
• El endpoint destino debe aceptar el método HTTP y el tipo de contenido que configures (POST es el predeterminado; application/json es el tipo de contenido predeterminado).

Campos del perfil de conexión

Endpoint

Campo	Requerido	Descripción	Valor de ejemplo
URL base	Sí	La URL a la que el conector envía las solicitudes. Puedes sobrescribir esto por registro en la configuración de mapeo usando el campo _targetPath (consulta Enrutamiento de payload más abajo).	https://api.example.com/ingest

Autenticación

Campo	Requerido	Descripción	Valor de ejemplo
Tipo de autenticación	Sí	El método de autenticación. Elige uno de: Ninguna, Clave de API, Token bearer o Básica.	apikey
Nombre del encabezado	Si Tipo = Clave de API	El encabezado HTTP que se establece con el valor de la clave de API.	X-Api-Key
Valor del encabezado	Si Tipo = Clave de API	La clave de API que se envía en el encabezado. Se almacena cifrada.	<TU_CLAVE_API>
Token bearer	Si Tipo = Token bearer	El token bearer incluido en el encabezado Authorization: Bearer. Se almacena cifrado.	<TU_TOKEN>
Usuario	Si Tipo = Básica	El nombre de usuario para la autenticación HTTP Básica.	usuario-integraciones
Contraseña	Si Tipo = Básica	La contraseña para la autenticación HTTP Básica. Se almacena cifrada.	<TU_CONTRASEÑA>

Solicitud

Campo	Requerido	Descripción	Valor predeterminado
Tipo de contenido	No	El valor del encabezado Content-Type para el cuerpo de la solicitud.	application/json
Omitir verificación TLS	No	Cuando está habilitado, el conector omite la validación del certificado TLS. Úsalo solo en entornos que no sean de producción donde el destino tiene un certificado autofirmado.	Desactivado

Modos de autenticación

Ninguna

No se agrega encabezado de autenticación. Úsalo para endpoints en una red privada o endpoints que dependen de listas de IP permitidas.

Clave de API

El conector agrega un único encabezado HTTP con el nombre y el valor que especifiques. Los nombres de encabezado comunes son X-Api-Key, Authorization o un nombre específico del sistema proporcionado por la API destino.

Token bearer

El conector agrega Authorization: Bearer <token> a cada solicitud.

Básica

El conector agrega Authorization: Basic <base64(usuario:contraseña)> a cada solicitud, siguiendo el estándar de autenticación HTTP Básica.

Enrutamiento de payload

De forma predeterminada, cada solicitud se envía a la URL base mediante HTTP POST. Puedes sobrescribir tanto la ruta URL como el método HTTP desde tu configuración de mapeo incluyendo campos de control especiales en el payload transformado:

Campo de control	Efecto	Valores permitidos
_targetPath	Se agrega a la URL base para formar la URL final de la solicitud.	Cualquier ruta URL válida, por ejemplo /orders o /items/upsert
_httpMethod	El método HTTP utilizado para la solicitud.	POST, PUT, PATCH

Estos campos se eliminan del payload antes de enviarlo al destino — el endpoint destino nunca los recibe.

Ejemplo: Si la URL base es https://api.example.com y el payload transformado contiene "_targetPath": "/orders" y "_httpMethod": "PUT", el conector envía una solicitud PUT a https://api.example.com/orders.

Manejo de respuestas

• Una respuesta con código de estado HTTP 2xx se trata como éxito.
• Una respuesta con cualquier otro código de estado se trata como fallo. El código de estado y el cuerpo de la respuesta se registran en el historial de la ejecución y el registro se reintenta según la política de reintentos del pipeline.
• Si el cuerpo de la respuesta es JSON válido y contiene un campo id de nivel superior, ese valor se almacena como identificador de entidad destino para la reconciliación futura de crear-vs-actualizar.
• Si la respuesta no es JSON o no contiene un campo id, el conector usa el identificador pasado desde la etapa Transform.

Limitaciones conocidas

• Solo de destino. El conector API Genérica no puede usarse como origen — no tiene extractor. Siempre aparece en el lado de destino de un trabajo.
• Sin reintento tras HTTP 4xx. Los errores de cliente (respuestas 4xx) se registran como fallos y se envían a la Cola de Mensajes Fallidos después de alcanzar el límite de reintentos. Si el destino devuelve un 429 (límite de velocidad), el registro también acabará en la Cola de Mensajes Fallidos; considera ajustar la programación del trabajo para reducir el volumen de solicitudes.
• Sin validación del esquema de respuesta. El conector no valida el cuerpo de la respuesta más allá de buscar el campo id. La corrección del payload es responsabilidad de la configuración de mapeo.
• Omitir TLS es solo para uso fuera de producción. Habilitar Omitir verificación TLS elimina completamente la validación del certificado. No lo uses contra endpoints de producción.
• POST es el método predeterminado. Si el endpoint destino requiere GET o DELETE, esos métodos no están disponibles. Solo se admiten POST, PUT y PATCH.

Relacionado

• Tipos de Entidad — Lista completa de tipos de entidad compatibles.
• Descripción de la Arquitectura — Cómo el conector API Genérica encaja en el pipeline como destino.
• Descripción General de Trabajos — Cómo configurar un trabajo que use este conector como destino.
• Descripción General de Conectores — Compara todos los conectores disponibles.