Activar una operación de Studio desde un webhook en Jitterbit Studio

Introducción

API Manager permite publicar una operación de Studio como un endpoint HTTP. Cuando un sistema externo envía una solicitud HTTP a ese endpoint, API Manager recibe la solicitud y ejecuta inmediatamente la operación vinculada, pasando el cuerpo de la solicitud y los encabezados a través de variables de Jitterbit.

Este patrón es útil para reaccionar a eventos en tiempo real de sistemas externos como plataformas CRM, herramientas de tickets o aplicaciones personalizadas que admiten webhooks salientes.

Esta guía cubre el tipo Custom API en API Manager. Asume lo siguiente:

Se configura una API personalizada y se publica en API Manager en el mismo entorno que el proyecto.
Existe un proyecto de Studio con al menos una operación para recibir la solicitud entrante.

El flujo general es:

flowchart LR A[Sistema externo] -->|HTTP POST| B[API Manager custom API] --> C[Operación de Studio] --> D[Respuesta HTTP]

Parte 1: Crear la API personalizada

Paso 1: Crear la API

Abre API Manager y haz clic en New API.
Selecciona Custom API como tipo de API.
API Name: Ingresa un nombre para la API (por ejemplo, Webhook Receiver). Este nombre aparece en API Manager y en los registros de operaciones.
URL Prefix: Ingresa el segmento de ruta base para la URL del endpoint público (por ejemplo, my-webhook).
Version: Ingresa una cadena de versión (por ejemplo, 1.0). Esto se convierte en parte de la URL del endpoint.
Enable SSL: Habilita para requerir conexiones HTTPS. Esto se recomienda para todos los endpoints de producción.
Enable CORS: Habilita si el sistema externo envía solicitudes de origen cruzado desde un contexto de navegador.
Haz clic en Save.

Paso 2: Configurar el endpoint de servicio

En el editor de API, haz clic en Add Service.
Method: Selecciona el método HTTP que el sistema externo utiliza para enviar el webhook (por ejemplo, POST).
Path: Ingresa la subruta del endpoint (por ejemplo, /events). Esto se añade a la URL base.
Operation: Selecciona la operación de Studio que procesará la solicitud entrante.
Response Type: Selecciona System Variable. Con esta configuración, el cuerpo de la respuesta se determina por el valor que la operación asigna a $jitterbit.api.response.
Timeout: Establece el tiempo máximo que API Manager espera a que se complete la operación. El valor predeterminado es 30 segundos.
Haz clic en Save y luego en Publish.

Después de publicar, API Manager muestra la URL del endpoint completa en el formato https://<host>/<prefix>/<version>/<path>. Copia esta URL y configura el sistema externo para enviar cargas útiles de webhook a ella.

Parte 2: Acceder a la carga útil de la solicitud en la operación

Cuando API Manager activa la operación vinculada, completa variables de Jitterbit con los datos de la solicitud entrante. Lee estas variables en un paso de script al inicio de la operación.

Variable	Contenido
`$jitterbit.api.request.body`	El cuerpo de la solicitud sin procesar como una cadena.
`$jitterbit.api.request.headers.content-type`	El valor del encabezado de solicitud `Content-Type`.
`$jitterbit.api.request.headers.fulluri`	La URI de solicitud completa, incluida la ruta. Útil para enrutamiento cuando varias rutas se asignan a una operación.
`$jitterbit.api.request.method`	El método HTTP de la solicitud (por ejemplo, `POST`).

El siguiente ejemplo registra el cuerpo entrante y la URI en el registro de operaciones:

<trans>
WriteToOperationLog("Received body: " + $jitterbit.api.request.body);
WriteToOperationLog("URI: " + $jitterbit.api.request.headers.fulluri);
</trans>

Para usar la carga útil en una transformación, asígnala a una variable y mapea esa variable como origen:

<trans>
$payload = $jitterbit.api.request.body;
</trans>

Enrutar solicitudes a través de múltiples rutas

Si la API tiene varias rutas de servicio (por ejemplo, /createRecord y /updateRecord), puedes asignar todas las rutas a una única operación controladora y usar una declaración Case() para distribuir a suboperaciones según la URI:

<trans>
Case(
  Index($jitterbit.api.request.headers.fulluri, "/createRecord") >= 0,
    RunOperation("<TAG>operation:Create Record</TAG>");,
  Index($jitterbit.api.request.headers.fulluri, "/updateRecord") >= 0,
    RunOperation("<TAG>operation:Update Record</TAG>");
);
</trans>

Esto mantiene la configuración de la API simple (un único punto de entrada) mientras que la operación del controlador maneja la lógica de distribución.

Parte 3: Devolver una respuesta al llamador

Cuando Response Type se establece en System Variable, API Manager devuelve el valor de $jitterbit.api.response como el cuerpo de la respuesta HTTP. Establece esta variable en la operación antes de que se complete.

El siguiente ejemplo devuelve un reconocimiento JSON:

<trans>
$jitterbit.api.response = '{"status":"received"}';
</trans>

Si $jitterbit.api.response no se establece, API Manager devuelve una respuesta vacía 200 OK.

Para devolver un código de estado HTTP diferente a 200, establece $jitterbit.api.response.status_code junto con el cuerpo de la respuesta:

<trans>
$jitterbit.api.response.status_code = "400";
$jitterbit.api.response = '{"error":"Missing required field"}';
</trans>

Nota

Algunos sistemas externos requieren una respuesta dentro de una ventana de tiempo corta (a menudo 3–10 segundos). Si la operación realiza trabajo que consume tiempo, considera devolver un reconocimiento inmediatamente y procesar la carga útil de forma asincrónica usando RunOperation con el parámetro async establecido en true.

Verificar la integración

Implementa y ejecuta el proyecto.
En API Manager, copia la URL del punto de conexión publicado.
Envía una solicitud POST de prueba al punto de conexión usando una herramienta como curl o Postman, incluyendo un cuerpo JSON.
Abre los registros de operación y confirma que la operación se ejecutó y que el cuerpo registrado coincide con la carga útil de prueba.
Confirma que el cuerpo de la respuesta HTTP y el código de estado coincidan con los valores establecidos en $jitterbit.api.response y $jitterbit.api.response.status_code.