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 APIs de Jitterbit API Manager. Las APIs personalizadas son uno de los tres tipos de APIs que puedes configurar a través de API Manager. Para los otros dos tipos, servicio OData e API proxy, consulta Configuración del servicio OData y Configuración de API proxy.

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

API Manager muestra las APIs personalizadas (publicadas y borrador) en estas ubicaciones:

• La página APIs de API Manager.
• La pestaña Resources 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. Primero debes crear e implementar 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 Design Studio.

Para obtener instrucciones sobre cómo crear e implementar una operación, consulta estos recursos:

• Studio
  • Creación y configuración de operaciones
  • Implementación y ejecución de operaciones
• Design Studio
  • Crear una operación

Crear una nueva API personalizada

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

Para crear una nueva API personalizada, haz clic en New (Nuevo) 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 Customer Success Manager (CSM) para agregar esta opción a tu licencia.

API Manager muestra la siguiente opción solo si existe una URL de API correspondiente disponible:

• Custom API: Abre la pantalla de configuración de API personalizada para crear manualmente una nueva API personalizada. Esta opción se activa solo si existe una URL de API correspondiente disponible.

Configurar una API personalizada

Cuando configuras una API personalizada manualmente, la pantalla de configuración incluye varias pestañas. La pantalla de configuración incluye dos pestañas requeridas y tres pestañas opcionales:

• Pestaña Profile (requerida)
• Pestaña Settings (opcional)
• Pestaña Services (requerida)
• Pestaña Security profiles (opcional)
• Pestaña User roles (opcional)

Pestaña Profile

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

Configura los siguientes parámetros:

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

• Raíz del servicio: 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 Nombre de la API 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 puedes cambiar el entorno. Para mover una API entre entornos, puedes clonar la API o exportar e importar la API en otro entorno. Al exportar, puedes incluir los proyectos de Studio que usan los servicios de la API.

• 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 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 la cantidad 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 usan a menos que se use un agente privado y 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 transferidos a través de solicitudes y respuestas de la API no se cifran y pueden ser interceptados y vistos por otros. Esto podría exponer información confidencial.

• 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 causa que las operaciones que usan 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 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 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 se ocultan, pero los parámetros y cuerpos se registran completamente. Usa esta configuración con cuidado.

• Habilitar modo de depuración hasta: Activa este botón 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 desactive 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 Registro detallado y Mostrar cargas de solicitud y respuesta en registros: cuando el modo de depuración está habilitado, los datos de solicitud y respuesta se incluyen en los registros sin importar si esas configuraciones están habilitadas.

  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 de encabezados enmascarados, estos datos aparecen en texto sin formato en los registros de la nube de Harmony durante 30 días.

• Mostrar cargas de solicitud y respuesta en registros: Activa este botón para capturar y mostrar las cargas de solicitud y respuesta en la página API Logs y la página Runtime de la Consola de Administración cuando se realiza una solicitud de API. Las cargas aparecen en una vista formateada con paneles separados para los cuerpos de solicitud y respuesta, para ejecuciones exitosas e infructuosas. Esta configuración no genera entradas de registro de operaciones de Studio para ejecuciones exitosas. Para registrar ejecuciones de operaciones exitosas en Studio, usa Habilitar modo de depuración hasta en su lugar. Este botón se aplica únicamente a API personalizadas y servicios OData.

  Advertencia

  Las cargas de solicitud y respuesta pueden incluir datos sensibles como credenciales de autenticación o información de identificación personal. Usa esta configuración con cuidado.

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

Pestaña Services

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

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

• Service Name: Ingresa un nombre descriptivo para este servicio de API.

• Method: Selecciona el método HTTP para este servicio desde la lista desplegable. Los métodos disponibles incluyen GET, POST, PUT, DELETE y ALL. Para usar un método que no aparece en la lista, ingresa el nombre del método en el cuadro de texto Type a new method y presiona Enter.

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

• Project: Selecciona el proyecto de Harmony que contiene la operación que este servicio activa. Para migrar una API personalizada junto con sus proyectos de Studio, consulta Include linked Studio projects.

  • Go to project: 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 invoca.

  Para obtener información sobre lo que aparece en los registros de operaciones para operaciones activadas por API y cómo habilitar registro adicional, consulta Datos de solicitud y respuesta de API en Registros de operaciones.

• Tipo de respuesta: Selecciona cómo el API devuelve la respuesta de la operación. Las opciones disponibles incluyen Destino final, Variable del sistema y Sin respuesta.

  • Destino final: La respuesta del API es el destino final de la cadena de operaciones. Cuando seleccionas este tipo de respuesta, la operación seleccionada debe tener, como destino final de la cadena de operaciones, una actividad de respuesta del API o actividad de escritura de variables de Studio, o un destino de respuesta del API de Design Studio o un destino de variable global. Si la operación utiliza cualquier otro destino final, la respuesta del API estará vacía.

  • Variable del sistema: La respuesta del 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 el API devuelva. Si el script no establece esta variable, la respuesta del API estará vacía.

  • Sin respuesta: La respuesta del API está en blanco. Si la solicitud para ejecutar la operación seleccionada se acepta, el API devolverá una respuesta vacía inmediata con 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 del API.
  • Ir a la operación: Haz clic para abrir el proyecto de Studio en una nueva pestaña del navegador. La operación en el campo Operación a activar se resalta en el lienzo de diseño de Studio. Esta acción está deshabilitada para operaciones de Design Studio.
  • Duplicar: Haz clic para duplicar el servicio API.
  • Eliminar: Haz clic para eliminar el servicio API.

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

Pestaña de parámetros de ruta

Cuando se incluyen parámetros de solicitud 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 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 icono de eliminar junto a un parámetro de consulta para eliminar ese parámetro.

Pestaña de encabezados

Esta pestaña 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: Marca la casilla para hacer que este encabezado sea obligatorio para las solicitudes de API.

  • Eliminar: Haz clic en el icono de eliminación 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 Servicios, haz clic en Siguiente para ir a la pestaña Perfiles de seguridad, o haz clic en Anterior para volver a la pestaña Configuración.

Pestaña Perfiles de seguridad

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

Configura los siguientes parámetros:

• Asignar: Utiliza 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ásico, 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 Roles de usuario, o haz clic en Anterior para volver a la pestaña Servicios.

Pestaña Roles de usuario

La pestaña 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 parámetros:

• Rol de usuario: El nombre del rol de la organización tal como se define en la pestaña Roles de la página 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 de portal, incluida la generación de documentación de API
• Portal de API
• Registros de API
• Análisis

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

Los roles de usuario definidos con el permiso Admin siempre tienen acceso completo a todas las APIs y, por lo tanto, no se pueden desmarcar.

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

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

Opciones de guardado y publicación

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

• Guardar como borrador: Guarda la API con el estado Borrador o Publicada con Borrador. Las APIs en borrador no cuentan en tu límite de suscripción de URL de API. Una API cuyo estado era Publicada cuando usas Guardar como borrador se guarda como Publicada con Borrador. Una API publicada cuenta en tu límite de suscripción de URL de API, aunque su borrador no sea accesible.

• Publicar: Guarda la API con el estado Publicada. La API está activa y accesible en un plazo de cinco minutos. Una API publicada cuenta en 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 a tu portapapeles.
  • Generar documento OpenAPI: Abre la página Portal Manager, donde puedes generar documentación de API para todas las APIs en un entorno. Para generar documentación de APIs individuales, usa la pestaña Documentación al editar la API desde la página APIs.
  • Cerrar: Cierra el diálogo.

Editar la API

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

• Usando la vista de tarjetas en la página APIs, haz clic en la tarjeta.
• Usando la 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 APIs individuales. Para obtener más detalles, consulta la pestaña Documentación en la página APIs.