Configuración de API personalizada en Jitterbit API Manager

Introducción

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

Alternativamente, puedes crear APIs personalizadas utilizando el Asistente de IA o en Studio utilizando la opción Publicar como API desde el menú de acciones de una operación.

Las APIs personalizadas (publicadas y en borrador) se muestran en estas ubicaciones:

• La página de APIs del API Manager.
• La pestaña de Recursos del panel del proyecto para el proyecto de Studio asociado con la API personalizada.

Requisitos previos

Una API personalizada expone una operación de Harmony para su consumo. Debes primero crear y desplegar esta operación en Harmony antes de poder configurar la API personalizada. La operación que activa una API personalizada puede ser una operación de Studio o de Design Studio.

Para instrucciones sobre cómo crear y desplegar una operación, consulta estos recursos:

• Studio
  • Creación y configuración de operaciones
  • Despliegue y ejecución de operaciones
• Design Studio
  • Creando una operación

Crear una nueva API personalizada

Cuando accedes a la página de APIs del Administrador de API, si no existen APIs personalizadas, APIs OData o APIs proxy en la organización seleccionada, esta pantalla está en blanco.

Para crear una nueva API personalizada, haz clic en Nuevo > API personalizada.

Configurar una API personalizada

La pantalla de configuración incluye múltiples pestañas, con dos pestañas requeridas y tres pestañas opcionales. Cada pestaña se cubre en las siguientes secciones:

• Pestaña de perfil (requerida)
• Pestaña de configuración (opcional)
• Pestaña de servicios (requerida)
• Pestaña de perfiles de seguridad (opcional)
• Pestaña de roles de usuario (opcional)

Pestaña de perfil

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

Configura los siguientes ajustes:

• Nombre de la API: Ingresa un nombre para la API 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 de la API convertido a camel case. Este campo no permite espacios ni ciertos caracteres especiales. No se recomienda el uso de 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 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 avanzada 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 se use un agente privado y 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 las solicitudes y respuestas de la API no están cifrados y pueden ser interceptados y vistos por otros. Esto podría exponer información sensible.

• CORS: Habilita 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 provoca que las operaciones que utilizan el método OPTIONS se ejecuten sin autenticación.

• Registro detallado: Habilita este interruptor para registrar los encabezados y cargas útiles de las solicitudes cuando se realiza una solicitud a la API.

  Advertencia

  El registro detallado puede incluir datos sensibles como credenciales de autenticación o información personal identificable. Usa esta configuración con cuidado.

• Habilitar modo de depuración hasta: Habilita este interruptor para activar el registro detallado para la solución de problemas, luego haz 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 habilitas el modo de depuración para operaciones activadas por esta API, los registros de la API incluyen datos de solicitud y respuesta (conservados durante 30 días) a los que puedes acceder a través de la página Runtime en la Consola de Gestión. Por defecto, el Administrador de API solo registra operaciones de API con errores.

  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 la nube de Harmony durante 30 días.

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

Servicios tab

La pestaña Servicios es donde se configuran los servicios de API que definen cómo responde la API a las solicitudes. Se pueden configurar múltiples servicios para una sola API personalizada. Cada servicio debe tener una combinación única de método HTTP y ruta.

Haz clic en Nuevo Servicio para agregar un nuevo servicio de API. Configura los siguientes ajustes para cada servicio:

• Nombre del Servicio: Ingresa un nombre descriptivo para este servicio de API.

• Método: Selecciona el método HTTP para este servicio del menú desplegable. Los métodos disponibles incluyen GET, POST, PUT, DELETE y ALL. 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.

• Ruta: Ingresa la ruta URL que activa este servicio. La ruta se agrega a la raíz del servicio en la URL del servicio de la API.

• Proyecto: Selecciona el proyecto de Harmony que contiene la operación que este servicio activa.

  • Ir al proyecto: Haz clic para abrir un proyecto de Studio en una nueva pestaña del navegador. Esta opción está deshabilitada para proyectos de Design Studio.

• Operación a Activar: Selecciona la operación específica del proyecto elegido que este servicio ejecuta cuando se llama.

  Importante

  Por defecto, las operaciones exitosas configuradas para una API personalizada no se incluyen en los registros de operaciones a menos que se habilite una de estas configuraciones:

  • Agentes en la nube: Para operaciones de API en un agente en la nube, se debe habilitar el registro de depuración de operaciones en la operación.
  • Agentes privados: Para operaciones de API en un agente privado, se debe habilitar el registro de depuración de operaciones en la operación o debes establecer EnableLogging=true en la sección [APIOperation] del archivo de configuración del agente privado.

  Las operaciones no exitosas se incluyen en los registros de operaciones ya sea que la configuración anterior esté habilitada o no.

• Tipo de Respuesta: Selecciona cómo la API devuelve la respuesta de la operación. Las opciones disponibles incluyen Objetivo Final, Variable del Sistema y Sin Respuesta.

  • Objetivo Final: La respuesta de la API es el objetivo final de la cadena de operaciones. Cuando seleccionas este tipo de respuesta, la operación seleccionada debe tener, como objetivo final de la cadena de operaciones, una actividad de Respuesta de API o una actividad de Escritura de Variable, o un objetivo de Respuesta de API de Design Studio o un objetivo de Variable Global. Si la operación utiliza cualquier otro objetivo final, la respuesta de la API estará vacía.

  • Variable del Sistema: La respuesta de la API se establece en una variable de Jitterbit en la cadena de operaciones. Cuando seleccionas este tipo de respuesta, la operación seleccionada debe tener, como parte de la cadena de operaciones, un script que establezca la variable de Jitterbit jitterbit.api.response igual a la respuesta que deseas que la API devuelva. Si el script no establece esta variable, la respuesta de la API estará vacía.

  • Sin Respuesta: La respuesta de la API está en blanco. Si la solicitud para ejecutar la operación seleccionada es aceptada, la API devolverá una respuesta vacía inmediata con el código HTTP 202.

• 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 ver un resumen en una sola página de la configuración de la API personalizada.
  • Duplicar: Haz clic para duplicar el servicio de API.
  • Eliminar: Haz clic para eliminar el servicio de API.

Después de configurar los ajustes básicos del servicio, puedes configurar parámetros adicionales utilizando las pestañas debajo de la configuración del servicio:

Pestaña de parámetros de ruta

Cuando los parámetros de solicitud se incluyen en la Ruta, esta pestaña muestra los parámetros definidos en la ruta:

• Parámetro: Muestra cada parámetro de solicitud definido en la Ruta.

• Descripción: Opcionalmente, ingresa una descripción para el parámetro de solicitud.

Pestaña de parámetros de consulta

Esta pestaña te permite agregar parámetros de consulta al servicio API:

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

  • Parámetro: Ingresa el nombre del parámetro de consulta.

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

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

Pestaña de encabezados

Esta pestaña te permite agregar encabezados de solicitud al servicio API:

• Agregar Encabezado: Haz clic para agregar un encabezado de solicitud al servicio API. Los siguientes campos estarán disponibles:

  • Parámetro: Ingresa el nombre del encabezado de solicitud.

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

  • Requerido: Selecciona la casilla de verificación para hacer que este encabezado sea obligatorio para las solicitudes API.

  • Eliminar: Haz clic en el ícono de eliminar junto a un encabezado de solicitud para eliminar ese encabezado.

Puedes configurar múltiples servicios para una sola API personalizada. Cada servicio debe tener una combinación única de método HTTP y ruta.

Utiliza la columna Acciones para editar o eliminar servicios existentes.

Después de configurar la pestaña de 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 de Configuración.

Pestaña de Perfiles de seguridad

La pestaña de 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 según lo configurado 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 la autenticación básica, se muestra el nombre de usuario. Para otros tipos de autenticación, se 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 de Harmony, es posible que se 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 de Perfiles de seguridad, haz clic en Siguiente para proceder a la pestaña de Roles de usuario, o haz clic en Anterior para regresar a la pestaña de Servicios.

Pestaña de roles de usuario

La pestaña de Roles de usuario es opcional y determina qué roles de la organización tienen acceso a la API dentro del Administrador de API.

Configura los siguientes ajustes:

• Rol de usuario: El nombre del rol de la organización según se define en la pestaña Roles de la página de Gestión de usuarios.

• Permisos: Los permisos asignados a este rol, como Leer o Administrador.

• Estado: Indica si el rol está asignado a esta API. Cambia el estado para asignar o desasignar roles.

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

  • Ir al rol de usuario: Haz clic para abrir la configuración del rol de usuario.

Los roles que selecciones aquí determinan el acceso a esta API específica desde estas páginas:

• APIs
• Administrador del portal, incluida la generación de documentación de API
• Portal de API
• Registros de API
• Analíticas

El acceso a la página de Perfiles de seguridad y el acceso para consumir la API no se ven afectados por esta selección. El acceso para consumir una API está controlado por perfiles de seguridad.

Cualquier rol de usuario definido con el permiso Administrador siempre tiene acceso completo a todas las APIs y, por lo tanto, no se puede deseleccionar.

Haz clic en Nuevo rol de usuario para crear un nuevo rol de usuario. Para instrucciones, consulta Roles en Gestión de usuarios.

Después de configurar la pestaña de Roles de usuario, 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 Publicado con Borrador. Las APIs en borrador no cuentan contra tu límite de suscripción de URL de API. 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 API, 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 API. 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.
  • Generar documento OpenAPI: Abre la página del Portal Manager, donde puedes generar documentación de la API para la página del Portal de API.
  • Cerrar: Cierra el diálogo.

Editar la API

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

• Usando vista de mosaico en la página de APIs, haz clic en Ver/Editar.
• Usando vista de lista en la página de APIs, haz clic en Editar en la columna de Acciones.