Configuración de la API proxy en Jitterbit API Manager

Introducción

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

Alternativamente, cree APIs OData utilizando el Asistente de IA de APIM.

Requisitos previos

A diferencia de una API personalizada o una API OData, que expone una operación de Harmony para su consumo, una API proxy se utiliza con una API existente. Las APIs proxy no son enrutadas a través de agentes de Jitterbit. La puerta de enlace que procesa la API debe poder acceder a la API que se está proxyando:

• Puerta de enlace de API en la nube: Si utiliza 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 intenta proxyar no puede estar detrás de un firewall. Para permitir las direcciones IP de la puerta de enlace de API en la nube y permitir el acceso de la puerta de enlace a la API que se está proxyando, consulte la Información de lista de permitidos y navegue a https://services.jitterbit para su región.

• Puerta de enlace de API privada: Si utiliza 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 base del proxy consume el derecho de uso.

Crear una nueva API proxy

Para crear una nueva API proxy, haga clic en Nuevo y seleccione una de las siguientes opciones:

• Construir con IA: Abre el Asistente de APIM para crear una API utilizando indicaciones en lenguaje natural. Para más información, consulte Uso del Asistente de IA.

  Nota

  Para usar el Asistente de IA de APIM, su licencia de Harmony debe incluir la opción de Asistente de IA de APIM. Contacte a su Gerente de Éxito del Cliente (CSM) para agregar esta opción a su licencia.

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

Configurar una API proxy

Cuando configura 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 de perfil (requerida)
• Pestaña de configuración (opcional)
• Pestaña de API existente (requerida)
• Pestaña de servicios (requerida)
• Pestaña de perfiles de seguridad (opcional)
• Pestaña de encabezados de solicitud (opcional)

Pestaña de perfil

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

Configure los siguientes ajustes:

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

• Raíz del servicio: El nombre público de la API que se utilizará como parte de la URL del servicio de la API. Por defecto, este campo se completa con el Nombre del Proxy convertido a camel case. Este campo no permite espacios ni ciertos caracteres especiales. No se recomienda usar caracteres especiales distintos de un guion bajo (_). Los siguientes caracteres especiales están permitidos: . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -.

• 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 la creación de 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 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 distintos de un punto (.) o un guion (-). Las convenciones de nomenclatura comunes incluyen versiones incrementales como v1.0, v1.1, v1.2, o usar 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 proceder a la pestaña Configuración, o haz clic en Guardar como borrador para guardar tu progreso.

Pestaña de configuración

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

Configura los siguientes ajustes según sea necesario:

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

  Nota

  Esta configuración es independiente de la configuración de tiempo de espera de operación en Studio o Design Studio. Las configuraciones de tiempo de espera de operación no se utilizan a menos que la configuración EnableAPITimeout en el archivo de configuración del agente privado esté habilitada.

• Solo SSL: Este interruptor está habilitado por defecto y requiere HTTPS para la API. Cuando está habilitado, los datos se cifran a través de SSL y una solicitud HTTP devuelve un error. Cuando está deshabilitado, se admiten solicitudes tanto HTTP como HTTPS.

  Advertencia

  Cuando está deshabilitado, los datos transmitidos a través de solicitudes y respuestas de API no están cifrados y pueden ser interceptados y vistos por otros. Esto podría exponer información sensible.

• CORS: Habilite este interruptor para soportar CORS (Intercambio de Recursos de Origen Cruzado). CORS es un mecanismo que permite a las aplicaciones web que se ejecutan en un navegador web en un dominio acceder 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: Habilite este interruptor para agregar datos de solicitud y respuesta en bruto —incluidos encabezados, parámetros y cuerpos— al registro de llamadas cuando se realiza una solicitud de API. Estos datos aparecen en la página de Registros de API y en la página de Tiempo de Ejecución de la Consola de Gestión para ejecuciones exitosas y no exitosas. El registro detallado no genera entradas de registro de operación de Studio para ejecuciones exitosas. Para registrar ejecuciones exitosas de operaciones en Studio, utilice 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 personal identificable. Utilice esta configuración con cuidado.

• Habilitar modo de depuración hasta: Habilite este interruptor para activar el registro detallado para la solución de problemas, luego haga clic en el ícono del calendario para seleccionar una fecha hasta dos semanas a partir de hoy cuando el modo de depuración se apague automáticamente. Cuando está habilitado, los datos de solicitud y respuesta (conservados durante 30 días) aparecen en la página de Registros de API, en la página de Tiempo de Ejecución de la Consola de Gestión y en los registros de operación de Studio para ejecuciones exitosas y no exitosas. 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 de Registro de Depuración. Esta configuración anula Registro detallado: cuando el modo de depuración está habilitado, los datos de solicitud y respuesta se incluyen en los registros independientemente de si Registro detallado 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 personal identificable (PII). Estos datos aparecen en texto claro en los registros de Harmony durante 30 días.

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

Después de configurar la pestaña de Configuración, haga clic en Siguiente para continuar a la pestaña de API existente, o haga clic en Anterior para regresar a la pestaña de Perfil.

Pestaña de API existente

Utilice la pestaña de API existente para especificar la URL base de la API que desea proxy y opcionalmente proporcionar un documento OpenAPI para el descubrimiento automático del servicio.

Configure los siguientes ajustes:

• URL base de la API: Ingrese la URL base de la API a la que se hará proxy.

  Nota

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

• Proporcionar documento OpenAPI: Si proporciona un documento OpenAPI, el Administrador de API lo utiliza para descubrir automáticamente los servicios de la API. Seleccione No para omitir o Sí para expandir un área adicional para proporcionar el documento OpenAPI:

  

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

    

  • Subir archivo: Abre un diálogo para subir un documento OpenAPI en formato YAML o JSON después de usar Examinar para seleccionar el archivo:

    

  • Clear: Limpia un documento OpenAPI que ya ha sido proporcionado y cambia la selección de Proveer Documento OpenAPI a No.

  • 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 ícono de popout. Después de abrir esa área, haz clic en el ícono de retorno para volver a esta pantalla.

Después de configurar la pestaña API Existente, haz clic en Siguiente para proceder a la pestaña Servicios, o haz clic en Anterior para regresar a la pestaña Configuración.

Services tab

Utiliza la pestaña Servicios 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 API Existente.

Manual service definition

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

Haz clic en Nuevo Servicio para agregar un servicio. Configura los siguientes ajustes:

• 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 puedes usar caracteres como llaves ({ }) en una ruta de servicio cuando defines servicios manualmente. Para usar caracteres no permitidos en una ruta de servicio, proporciona en su lugar un documento OpenAPI que defina la ruta en la pestaña API Existente.

• 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 no listado, ingresa el nombre del método en el cuadro de texto Escribe un nuevo método 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.

Auto-descubrimiento del documento OpenAPI

Si proporcionaste un documento OpenAPI en la pestaña API existente, el Administrador de API descubre automáticamente y lista los servicios en una tabla:

• Asignar: Usa el interruptor para agregar los servicios a la API proxy.
• Nombre del Servicio: El nombre utilizado para identificar el servicio.
• Métodos: El método HTTP que se aplica al servicio.
• 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 de la API.
  • Ir al Servicio API: Haz clic para configurar la API en una interfaz de asistente.

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

Pestaña de perfiles de seguridad

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

Configura los siguientes ajustes:

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

• Nombre del Perfil: El nombre del perfil de seguridad tal como está configurado en Perfiles de Seguridad.

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

• Nombre de Usuario: Para la 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 te requiera asignar un perfil de seguridad para poder guardar la API.

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

Después de configurar la pestaña Perfiles de seguridad, haz clic en Siguiente para proceder a la pestaña de encabezados de solicitud, o haz clic en Anterior para regresar 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 sobrescribir encabezados de solicitud existentes.

Haz clic en Nuevo encabezado para agregar un encabezado de solicitud. Configura los siguientes ajustes:

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

• Valor: Ingresa un valor para el encabezado de solicitud.

• Sobrescribir Entrada: Activa este interruptor para sobrescribir 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 revelar acciones adicionales.

  • Eliminar: Haz clic para eliminar el encabezado de la 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 en estado Borrador o estado Publicado con Borrador. Las APIs en borrador no cuentan contra tu límite de suscripción de URL de Proxy. Una API cuyo estado fue Publicado en el momento en que 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 en 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 en 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 APIs, haz clic en la tarjeta.
• Usando vista de lista en la página de APIs, haz clic en Editar en la columna de Acciones.

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