Configuración de API proxy en Jitterbit API Manager

Introducción

Esta página describe cómo crear y configurar una API proxy desde la página APIs de Jitterbit API Manager. Una API proxy es uno de los tres tipos de API configurados a través de API Manager. Para los otros dos tipos, API personalizada y servicio OData, consulta Configuración de API personalizada y Configuración del servicio OData.

Alternativamente, crea API proxy usando el Asistente de IA de APIM.

Requisitos previos

A diferencia de una API personalizada o un servicio OData, que exponen una operación de Harmony para su consumo, una API proxy se utiliza con una API existente. Las API proxificadas no se enrutan a través de agentes de Jitterbit. La puerta de enlace que procesa la API debe poder acceder a la API que se está proxificando:

• Puerta de enlace de API en la nube: Si usas la puerta de enlace de API en la nube (alojada por Jitterbit), la API existente debe ser accesible públicamente, incluso si está protegida. La API que intentas proxificar no puede estar detrás de un firewall. Para incluir en la lista blanca las direcciones IP de la puerta de enlace de API en la nube a fin de permitir que la puerta de enlace acceda a la API que se está proxificando, consulta Información de lista blanca y navega a https://services.jitterbit para tu región.

• Puerta de enlace de API privada: Si usas una puerta de enlace de API privada (alojada en una red privada), la puerta de enlace de API privada debe poder acceder a la API existente.

Aunque cada API proxy permite asignar múltiples servicios a una URL única, la URL proxy base consume el derecho.

Crear una nueva API proxy

Para crear una nueva API proxy, haz clic en New y selecciona una de las siguientes opciones:

• Build with AI: Abre el Asistente de APIM para crear una API usando indicaciones en lenguaje natural. Para más información, consulta Usar el Asistente de IA.

  Nota

  Para usar el Asistente de IA de APIM, tu licencia de Harmony debe incluir la opción Asistente de IA de APIM. Contacta a tu Gerente de éxito del cliente (CSM) para agregar esta opción a tu licencia.

• Proxy API: Abre la pantalla de configuración de la API proxy para crear manualmente una nueva API proxy. Esta opción está habilitada solo si existe una URL de API correspondiente disponible.

Configurar una API proxy

Cuando configuras una API proxy manualmente, la pantalla de configuración incluye múltiples pestañas. La pantalla de configuración incluye tres pestañas requeridas y tres pestañas opcionales:

• Pestaña Perfil (requerida)
• Pestaña Configuración (opcional)
• Pestaña API existente (requerida)
• Pestaña Servicios (requerida)
• Pestaña Perfiles de seguridad (opcional)
• Pestaña Encabezados de solicitud (opcional)

Pestaña Perfil

Usa la pestaña Perfil para ingresar información básica que identifique la API.

Configura los siguientes ajustes:

• API Name: Ingresa un nombre para la API proxy que usar con fines de identificación interna. Se permiten los siguientes caracteres especiales: ( ) - _.

• Service Root: El nombre público de la API para usar como parte de la URL del servicio de la API. De forma predeterminada, este campo se completa con el Proxy Name convertido a camel case. Este campo no permite espacios ni ciertos caracteres especiales. No se recomienda usar caracteres especiales distintos de un guion bajo (_). Se permiten los siguientes caracteres especiales: . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -.

• Descripción: Ingresa una descripción opcional para la API.

• Entorno: Usa el menú para seleccionar el entorno donde residirá la API. Puedes escribir cualquier parte del nombre del entorno en el menú para filtrar la lista de entornos. Los resultados del menú se filtran en tiempo real con cada pulsación de tecla.

  Nota

  Después de crear la API, no es posible cambiar el entorno. Para mover una API entre entornos, puedes clonar la API o exportar e importar la API en otro entorno.

• Número de versión: Ingresa una versión opcional para usar como parte de la URL del servicio de la API. Este campo permite un máximo de 48 caracteres y no permite espacios ni ciertos caracteres especiales. No se recomienda usar caracteres especiales que no sean un punto (.) o un guión (-). Las convenciones de nomenclatura comunes incluyen versiones incrementales como v1.0, v1.1, v1.2, o usar una fecha de publicación de la API como 2025-08-28.

Después de completar la pestaña Profile, haz clic en Next para ir a la pestaña Settings, o haz clic en Save as draft para guardar tu progreso.

Pestaña Settings

La pestaña Settings es opcional y contiene opciones de configuración avanzada para la API.

Configura los siguientes ajustes según sea necesario:

• Timeout: Ingresa el número de segundos antes de que la API agote el tiempo de espera. El valor predeterminado es 30 segundos. El valor máximo permitido es 180 segundos.

  Nota

  Este ajuste es independiente del ajuste de tiempo de espera de la operación en Studio o Design Studio. Los ajustes de tiempo de espera de la operación no se utilizan a menos que el ajuste EnableAPITimeout en el archivo de configuración del agente privado esté habilitado.

• SSL only: Este toggle está habilitado de forma predeterminada y requiere HTTPS para la API. Cuando está habilitado, los datos se cifran mediante SSL y una solicitud HTTP devuelve un error. Cuando está deshabilitado, se admiten solicitudes HTTP y HTTPS.

  Advertencia

  Cuando está deshabilitado, los datos que pasan a través de solicitudes y respuestas de API no se cifran y pueden ser interceptados y visualizados por otros. Esto podría exponer información sensible.

• CORS: Habilita este toggle para admitir CORS (Intercambio de Recursos entre Orígenes). CORS es un mecanismo que permite que aplicaciones web que se ejecutan en un navegador web en un dominio accedan a recursos de un servidor en un dominio diferente.

  Advertencia

  Habilitar CORS hace que las operaciones que usan el método OPTIONS se ejecuten sin autenticación.

• Verbose logging: Habilita este toggle para agregar datos de solicitud y respuesta sin procesar —incluyendo encabezados, parámetros y cuerpos— al registro de llamadas cuando se realiza una solicitud de API. Estos datos aparecen en la página API Logs y en la página Runtime de la Consola de administración para ejecuciones exitosas e infructuosas. El registro detallado no genera entradas de registro de operaciones de Studio para ejecuciones exitosas. Para registrar ejecuciones de operaciones exitosas en Studio, usa Enable debug mode until en su lugar.

  Advertencia

  El registro detallado puede incluir datos sensibles como credenciales de autenticación o información de identificación personal. Los valores para encabezados enmascarados se ocultan, pero los parámetros y cuerpos se registran en su totalidad. Usa este ajuste con cuidado.

• Enable debug mode until: Habilita este toggle para activar el registro detallado para solucionar problemas, luego haz clic en el icono del calendario para seleccionar una fecha hasta dos semanas desde hoy cuando el modo de depuración se desactiva automáticamente. Cuando está habilitado, los datos de solicitud y respuesta (conservados durante 30 días) aparecen en la página API Logs, la página Runtime de la Consola de administración y los registros de operaciones de Studio para ejecuciones exitosas e infructuosas. El registro de depuración a nivel de actividad también está habilitado, capturando datos de entrada y salida de componentes en la pestaña Debug Logging. Este ajuste anula Verbose logging: cuando el modo de depuración está habilitado, los datos de solicitud y respuesta se incluyen en los registros independientemente de si Verbose logging está habilitado.

  Advertencia

  Los registros de depuración contienen todos los datos de solicitud y respuesta, incluyendo información sensible como contraseñas e información de identificación personal (PII). Apart from the values for masked headers, estos datos aparecen en texto sin cifrar en los registros de la nube de Harmony durante 30 días.

• Show Request & Response Payloads in Logs: Este interruptor es visible en la configuración de la API proxy pero no tiene efecto. No se admite el registro de carga útil de solicitud y respuesta para las API proxy.

Después de configurar la pestaña Settings, haz clic en Next para ir a la pestaña Existing API, o haz clic en Prev para volver a la pestaña Profile.

Pestaña Existing API

Usa la pestaña Existing API para especificar la URL base de la API que deseas hacer proxy y proporciona opcionalmente un documento OpenAPI para el descubrimiento automático de servicios.

Configura los siguientes parámetros:

• Base API URL: Introduce la URL base de la API a hacer proxy.

  Nota

  Si la API proporciona un único servicio, puedes introducir la URL completa de la API, incluyendo la ruta del servicio. Las rutas de servicio adicionales se definen en la pestaña Services.

• Provide OpenAPI document: Si proporcionas un documento OpenAPI, el Administrador de API lo utiliza para descubrir automáticamente los servicios de la API. Selecciona No para omitir o Yes para expandir un área adicional para proporcionar el documento OpenAPI:

  

  • Load URL: Abre un cuadro de diálogo para cargar un documento OpenAPI en formato YAML o JSON desde una URL:

    

  • Upload file: Abre un cuadro de diálogo para cargar un documento OpenAPI en formato YAML o JSON después de usar Browse para seleccionar el archivo:

    

  • Clear: Borra un documento OpenAPI que ya se ha proporcionado y cambia la selección Provide OpenAPI document a No. Aparece un cuadro de diálogo de confirmación de Clear editor contents, pidiéndote que confirmes antes de que se elimine el documento. Al borrar el documento también se eliminan los servicios que fueron descubiertos automáticamente del mismo (consulta OpenAPI document auto-discovery), pero no afecta los servicios agregados manualmente ni otros ajustes de la API. Borrar el documento se trata como un cambio sin guardar hasta que guardes la configuración de la API.

  • Document editor: Permite ver y editar un documento OpenAPI proporcionado. También puedes proporcionar un documento OpenAPI ingresándolo aquí directamente. Para ver y editar el documento OpenAPI en un área más grande, haz clic en el icono de expansión. Después de abrir esa área, haz clic en el icono de retorno para volver a esta pantalla.

Después de configurar la pestaña Existing API, haz clic en Next para ir a la pestaña Services, o haz clic en Prev para volver a la pestaña Settings.

Pestaña Services

Usa la pestaña Services para definir los servicios y métodos HTTP que la API proxy expondrá. La forma en que definas los servicios depende de si proporcionaste un documento OpenAPI en la pestaña Existing API.

Definición manual de servicios

Si no proporcionaste un documento OpenAPI, debes definir servicios y métodos manualmente:

Haz clic en New Service para agregar un servicio. Configura los siguientes parámetros:

• Service Name: Introduce un nombre para identificar el servicio.

• Path: Introduce una ruta para el servicio. Si la API no tiene una ruta de servicio, introduce una barra diagonal (/). Para definir un parámetro de ruta, encierra su nombre entre llaves (por ejemplo, /pets/{petId}). Para los caracteres y límites que acepta una ruta, consulta Service path rules.

• Métodos: Selecciona cada método que se creará para el servicio. Los métodos disponibles incluyen GET, PUT, POST y DELETE. Para usar un método no listado, ingresa el nombre del método en el cuadro de texto Escribe un nuevo método y presiona Enter.

• Acciones: Pasa el cursor sobre una fila de servicio para revelar acciones adicionales.

  • Copiar URL del servicio API: Haz clic para copiar la URL del servicio API.
  • Duplicar: Haz clic para duplicar el servicio.
  • Eliminar: Haz clic para eliminar el servicio.

Se debe agregar al menos un servicio para proceder a la siguiente pestaña.

Detección automática de documentos OpenAPI

Si proporcionaste un documento OpenAPI en la pestaña API existente, API Manager detecta automáticamente y enumera los servicios en una tabla:

• Asignar: Usa el conmutador para agregar los servicios a la API de proxy.
• Nombre del servicio: El nombre utilizado para identificar el servicio. Cuando el documento define más de un método para la misma ruta, el nombre incluye el método (por ejemplo, GET /pets y POST /pets) para que cada nombre sea único. Una ruta con un solo método utiliza la ruta como nombre.
• Métodos: El método HTTP que aplica al servicio. Este campo es de solo lectura porque los métodos provienen del documento OpenAPI.
• Ruta: La ruta del servicio.

• Acciones: Pasa el cursor sobre una fila de servicio para revelar acciones adicionales.

  • Copiar URL del servicio API: Haz clic para copiar la URL del servicio API.

API Manager también detecta los parámetros de ruta, consulta y encabezado que el documento define para cada ruta y método, y los enumera en las pestañas de parámetros del servicio.

Parámetros del servicio

Selecciona una fila de servicio para expandirla y ver los parámetros de ese servicio. Los parámetros se almacenan para cada combinación de ruta y método HTTP. Si un servicio tiene más de un método, aparece una pestaña para cada método (por ejemplo, GET y POST) encima de las pestañas de parámetros, y cada pestaña de método tiene sus propios parámetros.

La configuración Requerido en los parámetros de consulta y encabezados marca un parámetro como obligatorio en API Manager y en el Portal de API. El Portal de API te impide probar una solicitud que omita un parámetro obligatorio. La puerta de enlace de API no verifica los parámetros obligatorios cuando reenvía solicitudes a la API existente, por lo que la API existente debe validarlos.

Pestaña Parámetros de ruta

Esta pestaña enumera los parámetros de ruta del servicio:

• Parámetro: El nombre de cada parámetro de ruta. API Manager agrega un parámetro automáticamente para cada nombre que envuelvas en llaves en la Ruta, siguiendo las reglas de ruta del servicio. Este campo es de solo lectura. Un consumidor debe proporcionar un valor para cada parámetro de ruta al llamar al servicio.

• Descripción: Un campo de solo lectura. API Manager no almacena descripciones para parámetros de ruta.

Pestaña Parámetros de consulta

Esta pestaña enumera los parámetros de consulta del servicio. Los parámetros de consulta se detectan desde un documento OpenAPI o se agregan manualmente:

• Agregar parámetro: Haz clic para agregar un parámetro de consulta al servicio. Los siguientes campos están disponibles:

  • Parámetro: Ingresa el nombre del parámetro de consulta. Para los caracteres permitidos y la longitud, consulta reglas de nombre de parámetro.

  • Descripción: Opcionalmente, ingresa una descripción del parámetro de consulta.

  • Requerido: Usa el conmutador para marcar el parámetro de consulta como obligatorio. El valor predeterminado es deshabilitado.

  • Eliminar: Haz clic en el icono de eliminar junto a un parámetro de consulta para eliminar ese parámetro.

Pestaña Encabezados

Esta pestaña enumera los encabezados de solicitud que los consumidores pueden enviar al servicio. Estos encabezados describen lo que acepta la API existente. Para establecer valores de encabezado que API Manager envía a la API existente, usa la pestaña Encabezados de solicitud en su lugar.

• Agregar parámetro: Haz clic para añadir un encabezado de solicitud al servicio. Los siguientes campos quedan disponibles:

  • Parámetro: Ingresa el nombre del encabezado de solicitud. Para conocer los caracteres permitidos y la longitud, consulta Reglas de nombres de parámetros.

  • Descripción: Opcionalmente, ingresa una descripción del encabezado de solicitud.

  • Requerido: Usa el selector para indicar que los consumidores deben enviar el encabezado. Por defecto está deshabilitado.

  • Eliminar: Haz clic en el icono de eliminar al lado de un encabezado de solicitud para borrarlo.

Reglas de nombres de parámetros

API Manager valida los nombres de parámetros y descripciones cuando los editas. Debes resolver todos los errores antes de poder publicar la API:

• Los nombres de parámetros no pueden estar vacíos ni duplicados dentro de la misma pestaña.
• Los nombres de parámetros no pueden exceder 64 caracteres, y las descripciones no pueden exceder 256 caracteres.
• Los nombres de parámetros de consulta solo pueden contener letras, números y los caracteres -, . y _.
• Los nombres de parámetros de encabezado solo pueden contener letras en inglés, números y los caracteres !, #, $, %, &, ', *, +, -, ., ^, _, `, | y ~.

Reglas de rutas de servicio

API Manager valida la Ruta de cada servicio, ya sea que la ingreses manualmente o provenga de un documento OpenAPI. Un error aparece bajo el campo Ruta, y debes resolverlo antes de poder publicar la API. Una ruta debe seguir estas reglas:

• La ruta comienza con una barra diagonal (/). API Manager añade la barra automáticamente.
• La ruta no puede exceder 2000 caracteres.
• Cada segmento de texto de la ruta (las partes fuera de las llaves) solo puede contener letras, números y los caracteres -, _ y .. Las letras y números pueden ser de cualquier idioma.
• Una ruta no puede contener segmentos vacíos (//).
• Las llaves deben estar apareadas y no pueden estar anidadas ni vacías. Un nombre de parámetro de ruta dentro de las llaves sigue las mismas reglas de caracteres que los segmentos de texto y no puede exceder 64 caracteres. Una ruta no puede usar el mismo nombre de parámetro dos veces.
• Una ruta puede terminar con una barra diagonal, y el texto y los parámetros pueden compartir un segmento (por ejemplo, /report.{format}).
• Un servicio puede usar la ruta base (/) sin segmentos adicionales, y la ruta base puede tener múltiples métodos.

Después de configurar la pestaña Servicios, haz clic en Siguiente para proceder a la pestaña Perfiles de seguridad, o haz clic en Anterior para volver a la pestaña API existente.

Pestaña Perfiles de seguridad

La pestaña Perfiles de seguridad es opcional y te permite restringir el acceso para el consumo de la API.

Configura los siguientes parámetros:

• Asignar: Usa el selector para asignar o desasignar perfiles de seguridad para la API.

• Nombre del perfil: El nombre del perfil de seguridad tal como se configuró en Perfiles de seguridad.

• Tipo: El tipo de autenticación para el perfil de seguridad, como Básica, OAuth 2.0 o Clave de API.

• Nombre de usuario: Para autenticación básica, esto muestra el nombre de usuario. Para otros tipos de autenticación, esto muestra el mismo valor que la columna Tipo.

• Acciones: Pasa el cursor sobre una fila de perfil de seguridad para revelar acciones adicionales.

  • Ir al perfil de seguridad: Haz clic para abrir la configuración del perfil de seguridad.

Dependiendo de las políticas de la organización Harmony, es posible que se requiera asignar un perfil de seguridad para guardar la API.

Haz clic en Nuevo perfil de seguridad para crear un nuevo perfil de seguridad. Para obtener instrucciones, consulta Configurar perfiles de seguridad.

Después de configurar la pestaña Perfiles de seguridad, haz clic en Siguiente para ir a la Pestaña de encabezados de solicitud, o haz clic en Anterior para volver a la Pestaña de servicios.

Pestaña de encabezados de solicitud

La pestaña Encabezados de solicitud es opcional y te permite agregar nuevos encabezados de solicitud o anular los existentes.

Haz clic en Nuevo encabezado para agregar un encabezado de solicitud. Configura los siguientes parámetros:

• Clave: Introduce una clave para el encabezado de solicitud. La clave puede contener solo letras, números, guiones (-) y guiones bajos (_). No se permiten espacios, caracteres multibyte ni otros caracteres especiales.

• Valor: Introduce un valor para el encabezado de solicitud. El valor puede contener solo caracteres ASCII imprimibles (letras, números y puntuación estándar), sin espacios iniciales ni finales, y no puede exceder 8192 caracteres. No se permiten caracteres multibyte ni de control. Esto permite valores como JSON Web Tokens (JWT), que requieren puntos (.) como parte de su formato.

• Anular entrada: Activa este interruptor para anular un encabezado de solicitud existente que use la misma Clave. El valor predeterminado es desactivado.

• Acciones: Pasa el cursor sobre una fila de encabezado para ver acciones adicionales.

  • Eliminar: Haz clic para eliminar el encabezado de solicitud.

Después de configurar la pestaña Encabezados de solicitud, haz clic en Publicar para publicar la API, o haz clic en Guardar como borrador para guardar tu progreso.

Opciones de guardar y publicar

Después de configurar todas las pestañas requeridas, puedes guardar o publicar la API:

• Guardar como borrador: Guarda la API con estado Borrador o estado Publicado con borrador. Los borradores de API no cuentan contra el límite de suscripción de URL proxy. Una API cuyo estado era Publicado cuando utilizas Guardar como borrador se guarda como Publicado con borrador. Una API publicada cuenta contra el límite de suscripción de URL proxy, aunque su borrador no sea accesible.

• Publicar: Guarda la API con estado Publicado. La API está activa y es accesible en cinco minutos. Una API publicada cuenta contra el límite de suscripción de URL proxy. Un diálogo indica que la API está activa:

  

  El diálogo proporciona estas opciones:

  • Copiar URL: Copia la URL del servicio de la API a tu portapapeles.
  • Cerrar: Cierra el diálogo.

Editar la API

Después de guardar la API, puedes editarla desde estas ubicaciones:

• Usando vista de tarjeta en la página de API, haz clic en la tarjeta.
• Usando vista de lista en la página de API, haz clic en Editar en la columna Acciones.

Cuando editas una API publicada desde la vista de lista, también está disponible una pestaña Documentación. Usa esta pestaña para ver, editar y publicar documentación OpenAPI para APIs individuales. Para obtener más detalles, consulta Pestaña Documentación en la página API.

Solución de problemas

Para la solución de problemas relacionada, consulta lo siguiente en la guía de solución de problemas de API Manager:

• API de proxy en la nube: la API de destino debe ser accesible públicamente

• API de proxy: guiones en encabezados de solicitud reemplazados por guiones bajos

• La configuración Mostrar cargas útiles de solicitud y respuesta no tiene efecto para las API de proxy