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 APIs 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 de servicio OData.

Alternativamente, crea servicios OData usando el Asistente de IA de APIM.

Requisitos previos

A diferencia de una API personalizada o servicio OData, que expone una operación de Harmony para su consumo, una API proxy se utiliza con una API existente. Las APIs proxy 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á proxy:

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

• Puerta de enlace de API privada: Si utilizas 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 Nuevo y selecciona una de las siguientes opciones:

• Crear con IA: Abre el Asistente de APIM para crear una API usando indicaciones en lenguaje natural. Para obtener 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.

• API proxy: Abre la pantalla de configuración de API proxy para crear manualmente una nueva API proxy. Esta opción se habilita solo si hay 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 parámetros:

• Nombre de API: Ingresa un nombre para la API proxy que se utilizará para propósitos de identificación interna. Se permiten los siguientes caracteres especiales: ( ) - _.

• Raíz de servicio: El nombre público de la API que se utilizará como parte de la URL del servicio de la API. De forma predeterminada, este campo se completa con el Nombre de proxy convertido a notación de camello. Este campo no permite espacios ni ciertos caracteres especiales. No se recomienda utilizar caracteres especiales distintos de un guion bajo (_). Se permiten los siguientes caracteres especiales: . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -.

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

• Entorno: Utiliza 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 puedes 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 utilizarla 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 utilizar caracteres especiales distintos de un punto (.) o un guion (-). Las convenciones de nomenclatura comunes incluyen versiones incrementales como v1.0, v1.1, v1.2, o utilizar una fecha en la que se publicó la API, como 2025-08-28.

Después de completar la pestaña Perfil, haz clic en Siguiente para ir a la pestaña Configuración, o haz clic en Guardar como borrador para guardar tu progreso.

Pestaña Configuración

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

Configura los siguientes parámetros según sea necesario:

• Tiempo de espera: 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 parámetro es independiente del parámetro de tiempo de espera de la operación en Studio o Design Studio. Los parámetros de tiempo de espera de la operación no se utilizan a menos que el parámetro EnableAPITimeout en el archivo de configuración del agente privado esté habilitado.

• Solo SSL: Este botón 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 transmitidos 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 botón 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 utilizan el método OPTIONS se ejecuten sin autenticación.

• Registro detallado: Habilita este botón 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 Registros de API y en la página Tiempo de ejecución de la Consola de administración para ejecuciones exitosas e infructuosas. El registro detallado no genera entradas de registro de operación de Studio para ejecuciones exitosas. Para registrar ejecuciones de operación exitosas en Studio, utiliza Habilitar modo de depuración hasta 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 de encabezados enmascarados están ocultos, pero los parámetros y cuerpos se registran en su totalidad. Utiliza este parámetro con cuidado.

• Habilitar modo de depuración hasta: Activa este interruptor para activar el registro detallado para solucionar problemas, luego haz clic en el icono de calendario para seleccionar una fecha hasta dos semanas a partir de 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. También se habilita el registro de depuración a nivel de actividad, capturando datos de entrada y salida de componentes en la pestaña Debug Logging. Esta configuración 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, incluida información sensible como contraseñas e información de identificación personal (PII). Aparte de los valores para encabezados enmascarados, estos datos aparecen en texto sin cifrar en los registros en la nube de Harmony durante 30 días.

• Mostrar cargas útiles de solicitud y respuesta en registros: Este interruptor es visible en la configuración de API proxy pero no tiene efecto. El registro de cargas útiles de solicitud y respuesta no es compatible con API proxy.

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

Pestaña Existing API

Utiliza la pestaña Existing API para especificar la URL base de la API que deseas usar como proxy y, opcionalmente, proporciona un documento OpenAPI para la detección automática de servicios.

Configura los siguientes parámetros:

• Base API URL: Ingresa la URL base de la API para usar como proxy.

  Nota

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

• Provide OpenAPI document: Si proporcionas un documento OpenAPI, API Manager lo utiliza para detectar 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 diálogo para cargar un documento OpenAPI en formato YAML o JSON desde una URL:

    

  • Upload file: Abre un 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 ha sido proporcionado y cambia la selección de Provide OpenAPI document a No. Aparece un diálogo de confirmación Clear editor contents, pidiéndote que confirmes antes de que se elimine el documento. Borrar el documento también elimina cualquier servicio que se haya detectado automáticamente desde él (consulta OpenAPI document auto-discovery), pero no afecta los servicios agregados manualmente ni otras configuraciones de 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 continuar 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 defines 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: Ingresa un nombre para identificar el servicio.

• Path: Ingresa una ruta para el servicio. Si la API no tiene una ruta de servicio, ingresa una barra diagonal (/).

  Nota

  No se pueden usar caracteres como llaves ({ }) en una ruta de servicio cuando defines servicios manualmente. Para usar caracteres no permitidos en una ruta de servicio, proporciona un documento OpenAPI que defina la ruta en la pestaña Existing API.

• Methods: 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 que no aparezca en la lista, ingresa el nombre del método en el cuadro de texto Type a new method y presiona Enter.

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

  • Copy API service URL: Haz clic para copiar la URL del servicio de la API.
  • Duplicate: Haz clic para duplicar el servicio.
  • Delete: Haz clic para eliminar el servicio.

Debes 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 Existing API, API Manager detecta automáticamente y enumera los servicios en una tabla:

• Assign: Usa el botón de alternancia para agregar los servicios a la API proxy.
• Service Name: El nombre usado para identificar el servicio.
• Methods: El método HTTP que se aplica al servicio.
• Path: La ruta del servicio.

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

  • Copy API service URL: Haz clic para copiar la URL del servicio de la API.
  • Go to API Service: Haz clic para configurar la API en una interfaz de asistente.

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

Pestaña Security profiles

La pestaña Security profiles es opcional y permite restringir el acceso para el consumo de la API.

Configura los siguientes parámetros:

• Assign: Usa el botón de alternancia para asignar o desasignar perfiles de seguridad para la API.

• Profile Name: El nombre del perfil de seguridad tal como se configuró en Security Profiles.

• Type: El tipo de autenticación para el perfil de seguridad, como Basic, OAuth 2.0 o API Key.

• User Name: Para autenticación básica, se muestra el nombre de usuario. Para otros tipos de autenticación, se muestra el mismo valor que la columna Type.

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

  • Go to security profile: 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 Encabezados de solicitud, o haz clic en Anterior para volver a la pestaña Servicios.

Pestaña Encabezados de solicitud

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

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

• Clave: Ingresa una clave para el encabezado de solicitud.

• Valor: Ingresa un valor para el encabezado de solicitud. El valor debe contener solo letras, números, espacios y puntuación, sin espacios al principio ni al final, y no puede exceder 8192 caracteres. Esto permite valores como tokens web JSON (JWT), que requieren puntos (.) como parte de su formato.

• Anular entrada: Habilita este botón para anular un encabezado de solicitud existente que use la misma Clave. El valor predeterminado es deshabilitado.

• Acciones: Pasa el cursor sobre una fila de encabezado para revelar 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 Publicado con Borrador. Las API en borrador no cuentan contra tu límite de suscripción de URL de proxy. Una API cuyo estado era Publicado cuando usas Guardar como borrador se guarda como Publicado con Borrador. Una API publicada cuenta contra tu límite de suscripción de URL de proxy, aunque su borrador no sea accesible.

• Publicar: Guarda la API con estado Publicado. La API está activa y accesible en cinco minutos. Una API publicada cuenta contra tu límite de suscripción de URL de 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 APIs, haz clic en la tarjeta.
• Usando vista de lista en la página APIs, haz clic en Editar en la columna Acciones.

Al editar 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 de OpenAPI para API individuales. Para obtener más detalles, consulta Pestaña Documentación en la página APIs.

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: Los parámetros de ruta de servicio requieren un documento OpenAPI

• 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 API de proxy