Paso JavaScript - Insurance Boosters API

El paso code.javascript ejecuta un script en un entorno aislado. Úsalo para transformar datos, validar, armar payloads o integrar fuentes que no cubre un HTTP simple.

Campos del paso

Campo	Requerido	Descripción
`actionKey`	Sí	Debe ser `code.javascript`.
`code`	Sí	Script JavaScript. Máximo `100000` caracteres.
`input`	No	Objeto de variables. Se resuelven plantillas `{{...}}` y queda disponible como `input`.
`timeoutMs`	No	Límite de ejecución en milisegundos.
`capture`	No	Copia campos de `output` a `context`.
`debug`	No	Activa metadatos adicionales de depuración cuando aplica.
`gmailCredentialKey`	No	Cuenta Gmail disponible para el global `gmail`. Requiere permisos de administrador.

Contrato de ejecución

La API resuelve plantillas en input.
El sandbox recibe ese objeto como global input.
Tu código debe asignar output = ....
Ese output es la salida del paso (y response.body para capture).

Consulta Variables y contexto para armar input y pasar datos entre pasos.

Pasar variables desde un paso anterior

Declara en input lo que necesitas del trigger, de context o de steps.<n>.output. Luego léelo como input.* en el script.

{
  "name": "Calcular IVA",
  "actionKey": "code.javascript",
  "input": {
    "monto": "{{steps.0.output.monto}}",
    "token": "{{context.accessToken}}"
  },
  "code": "const monto = Number(input.monto);\noutput = {\n  monto,\n  iva: Number((monto * 0.16).toFixed(2)),\n  total: Number((monto * 1.16).toFixed(2)),\n  hasToken: Boolean(input.token)\n};",
  "capture": {
    "totales": {
      "from": "response.body",
      "required": true
    }
  }
}

Para publicar datos al siguiente paso:

Asigna output = { ... }.
En el paso siguiente usa {{steps.N.output.<campo>}}, o
Declara capture y lee {{context.<clave>}}.

Objetos y APIs disponibles

Global	Uso
`input`	Variables inyectadas desde el `input` del paso.
`output`	Resultado que debes asignar.
`console`	`log`, `info`, `warn`, `error`, `table` (aparecen en los logs del paso).
`fetch`	HTTP nativo (`Headers`, `Request`, `Response` también disponibles).
`axios`	Cliente HTTP.
`files`	Lee o crea archivos reutilizables por otros pasos de la misma ejecución. Límite: `100 MB` por archivo.
`xlsx`	Lee hojas de cálculo: `xlsx.read(bytes)` devuelve `{ sheets }`.
`DateTime`	Luxon anclado a la zona de la automatización.
`DateTimeUTC`	Luxon en UTC.
`WORKFLOW_TIMEZONE`	Zona IANA activa (string).
`sleep(ms)`	Pausa asíncrona.
`Buffer`, `crypto`, `URL`, `URLSearchParams`	Utilidades Node/Web habituales.
`_`	Lodash.
`z`	Zod, para validar estructuras.
`setTimeout` / `setInterval`	Temporizadores (se limpian al terminar).
`mysql`	Helper para MySQL.
`sftp`	Helper para SFTP.
`workflow`	`workflow.stop(motivo?)` termina la automatización al acabar el paso.
`gmail`	`send` y `getThread` con la cuenta de `gmailCredentialKey`.
`files`	Abre, crea, analiza y guarda archivos en campos `files` de tableros.

Zona horaria

Trigger cron: DateTime.now() usa la timezone del trigger.
Otros triggers (p. ej. webhook): la zona efectiva es UTC.

Buen ejemplo: normalizar y validar

{
  "name": "Normalizar pago",
  "actionKey": "code.javascript",
  "input": {
    "referencia": "{{trigger.body.referencia}}",
    "monto": "{{trigger.body.monto}}"
  },
  "code": "const referencia = String(input.referencia || '').trim();\nconst monto = Number(input.monto);\nif (!referencia) throw new Error('referencia requerida');\nif (!Number.isFinite(monto) || monto <= 0) throw new Error('monto inválido');\noutput = { referencia, monto, moneda: 'MXN' };",
  "capture": {
    "pago": {
      "from": "response.body",
      "required": true
    }
  }
}

Script equivalente (más legible):

const referencia = String(input.referencia || "").trim();
const monto = Number(input.monto);

if (!referencia) {
  throw new Error("referencia requerida");
}
if (!Number.isFinite(monto) || monto <= 0) {
  throw new Error("monto inválido");
}

output = {
  referencia,
  monto,
  moneda: "MXN",
};

Buen ejemplo: llamar una API con `fetch`

const response = await fetch("https://ejemplo.com/api/pagos", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${input.token}`,
  },
  body: JSON.stringify({
    referencia: input.referencia,
    monto: input.monto,
  }),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

output = await response.json();

Pasa token, referencia y monto por input con plantillas; no los incrustes en code.

Reutilizar archivos de pasos anteriores

Consulta Archivos entre pasos para ver el contrato completo, límites y un ejemplo GNP → JavaScript. Los archivos de los pasos anteriores están disponibles automáticamente. No necesitas agregarlos al input:

const [pdf] = files.fromStep(0);
const bytes = await pdf.bytes();

output = {
  name: pdf.name,
  size: pdf.size,
  loadedBytes: bytes.length,
};

Métodos disponibles:

Método	Resultado
`files.fromStep(index)`	Archivos producidos por un paso anterior.
`file.bytes()`	Contenido como `Uint8Array`.
`file.text()`	Contenido UTF-8.
`file.json()`	JSON parseado.
`file.xlsx()`	Hojas de una hoja de cálculo: `{ sheets: [{ name, rows }] }`.
`files.create({ name, type, data })`	Crea y devuelve un archivo reutilizable.

Para crear un JSON o XML:

const file = await files.create({
  name: "resultado.json",
  type: "application/json",
  data: JSON.stringify(input.data),
});

output = { file };

Sólo puedes leer artefactos de pasos anteriores de la misma ejecución. Las referencias no contienen rutas del bucket ni URLs persistentes.

Detener el flujo con `workflow.stop`

Llama workflow.stop(motivo?) para terminar la ejecución al acabar este paso. La ejecución queda como exitosa y los pasos siguientes aparecen con estado skipped (Omitido). El detalle de la ejecución muestra stoppedAtStepIndex y stopReason.

if (!input.solicitudId) {
  workflow.stop("El correo no pertenece a ninguna solicitud");
  return { matched: false };
}

output = { solicitudId: input.solicitudId };

workflow.stop() sólo marca la ejecución; el código sigue hasta terminar o hasta un return.
Para salir en ese momento usa return valor: el valor que regreses es el output del paso. Un return; vacío deja el output sin valor.
Para fallar el paso usa throw new Error(...); workflow.stop() es para terminar sin error.

Enviar y leer correos con `gmail`

Declara gmailCredentialKey en el paso para habilitar el global gmail con esa cuenta. Igual que Enviar correo con Gmail, guardar o publicar una automatización con Gmail requiere permisos de administrador y una cuenta conectada. La cuenta va en gmailCredentialKey. El objeto de gmail.send() es solo el mensaje: los campos, la respuesta en hilo y los adjuntos están en Campos del mensaje. Las plantillas {{...}} se resuelven en input; dentro de code lee input.*. La comparación entre el paso y esta función está en Elige la interfaz.

{
  "name": "Responder a la aseguradora",
  "actionKey": "code.javascript",
  "gmailCredentialKey": "<gmail-credential-key>",
  "input": {
    "from": "{{trigger.body.message.from}}",
    "messageId": "{{trigger.body.message.id}}"
  },
  "code": "const sent = await gmail.send({ to: input.from, replyToMessageId: input.messageId, text: 'Gracias, lo revisamos.' });\noutput = sent;"
}

gmail.send(message) envía el mensaje del paso gmail.send. La cuenta queda fuera de ese objeto. El correo enviado no vuelve a disparar Nuevo correo en Gmail: el trigger ignora los mensajes de la cuenta conectada.

Campo	Descripción
`to`, `cc`, `bcc`, `replyTo`	Destinatarios. `to` es obligatorio.
`subject`	Asunto de un correo nuevo.
`replyToMessageId`	ID Gmail del mensaje al que respondes, dentro de su hilo. Usa `subject` o `replyToMessageId`, no ambos.
`text` / `html`	Cuerpo del correo; al menos uno.
`attachments`	Hasta 25 adjuntos Gmail (`filename`, `storagePath`, `contentType`).
`idempotencyKey`	Opcional. Evita duplicados si el paso se vuelve a ejecutar; por defecto `call-1`, `call-2`… según el orden de envío.

Devuelve { messageId, threadId, idempotentReplay }. Guarda messageId si un seguimiento posterior debe responder en el mismo hilo. gmail.getThread(threadId) lee el hilo desde Gmail y devuelve { id, messages: [{ id, from, to, cc, subject, text, snippet, internalDate, attachmentNames }] }, del mensaje más antiguo al más reciente.

Analizar adjuntos con `files.analyze`

files.analyze({ storagePath, instructions?, schema? }) lee un adjunto de un trigger Gmail y lo analiza con IA. Acepta PDF, DOCX e imágenes (JPEG, PNG, WEBP, GIF) de hasta 25 MB.

const [adjunto] = input.attachments;
const resultado = await files.analyze({
  storagePath: adjunto.storagePath,
  instructions: "Extrae los datos de la cotización.",
  schema: {
    type: "object",
    properties: {
      aseguradora: { type: ["string", "null"] },
      primaTotal: { type: ["number", "null"] },
      vigenciaFin: { type: ["string", "null"] },
    },
  },
});

output = resultado.data;

Sin schema devuelve { text } con un resumen estructurado; con schema (un objeto JSON Schema con type: "object") devuelve { data }.
También devuelve filename, mimeType y cached. El resultado se guarda: analizar otra vez el mismo archivo con las mismas instrucciones y esquema no vuelve a llamar al modelo.

Guardar un archivo en un tablero

files.open(ref) acepta tanto un WorkflowFileRef como el objeto de un adjunto Gmail. El file handle puede guardar el binario real en un campo files; no necesitas descargarlo, subir multipart ni usar una API key.

const [adjunto] = input.attachments;
const file = files.open(adjunto);

const guardado = await file.attachToRecord({
  databaseId: input.databaseId,
  recordId: input.recordId,
  fieldKey: "attachments",
});

output = { file: guardado };

El backend obtiene el tenant del token de ejecución y valida que el database, record y field existan, que el campo sea files, y que cumpla MIME, tamaño y maxFiles. Si el paso se reintenta, devuelve el mismo archivo sin duplicarlo.

storagePath sólo acepta adjuntos Gmail del mismo tenant.

Ejemplo: responder a una aseguradora

Automatización con trigger gmail_email_received. input recibe {{trigger.body.message.threadId}}, {{trigger.body.message.id}}, {{trigger.body.message.from}}, {{trigger.body.message.attachments}} y tu API key y tablero de solicitudes:

const buscar = await fetch(
  `https://api.insuranceboosters.com/api/v1/databases/${input.databaseId}/records/search`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-ib-api-key": input.apiKey },
    body: JSON.stringify({
      filters: [{ fieldId: input.threadFieldId, operator: "eq", value: input.threadId }],
      limit: 1,
    }),
  },
);
const [solicitud] = (await buscar.json()).records ?? [];
if (!solicitud) {
  workflow.stop("El correo no pertenece a ninguna solicitud");
  return { matched: false };
}

const [adjunto] = input.attachments ?? [];
if (adjunto) {
  const { data } = await files.analyze({
    storagePath: adjunto.storagePath,
    schema: { type: "object", properties: { primaTotal: { type: ["number", "null"] } } },
  });
  return { solicitudId: solicitud.id, cotizacion: data };
}

await gmail.send({
  to: input.from,
  replyToMessageId: input.messageId,
  text: "Gracias. ¿Nos compartes la cotización en PDF?",
});
output = { solicitudId: solicitud.id, respondido: true };

Para clasificar la respuesta con IA antes de este paso, usa Criterio IA o llama a tu agente con fetch. En una automatización de seguimiento, guarda el messageId del primer gmail.send y úsalo como replyToMessageId en cada seguimiento.

Buen ejemplo: fechas con `DateTime`

const ahora = DateTime.now();
const vencimiento = DateTime.fromISO(input.fechaVencimiento);

output = {
  timezone: WORKFLOW_TIMEZONE,
  ahora: ahora.toISO(),
  vencido: vencimiento < ahora,
  diasRestantes: Math.floor(vencimiento.diff(ahora, "days").days),
};

Malos ejemplos

No asignar `output`

const total = Number(input.monto) * 1.16;
// falta: output = { total };

Sin output, el paso no deja un resultado útil para pasos siguientes ni para capture.

Usar `require` o APIs de sistema

const fs = require("fs");
process.env.SECRET;

El sandbox no expone require, process, ni acceso al sistema de archivos del runner. Usa input, fetch/axios, mysql o sftp.

Leer el trigger directo sin pasarlo por `input`

output = { referencia: trigger.body.referencia };

trigger no existe como global. Declara "referencia": "{{trigger.body.referencia}}" en input y usa input.referencia.

Mutar estado “global” entre pasos

if (!globalThis.cache) globalThis.cache = {};
globalThis.cache.token = input.token;
output = { ok: true };

Cada paso corre en un proceso aislado. Comparte datos con output + capture/context o con el input del siguiente paso.

MySQL (opcional)

const db = await mysql.connect({
  host: input.mysql.host,
  port: input.mysql.port || 3306,
  user: input.mysql.user,
  password: input.mysql.password,
  database: input.mysql.database,
});

try {
  const rows = await db.execute(
    "SELECT id, email FROM customers WHERE status = ? LIMIT ?",
    ["active", 10]
  );
  output = { customers: rows };
} finally {
  await db.close();
}

Pasa host, usuario y contraseña por input (idealmente desde el body del webhook o un secreto que tú controles en tu integración). No hardcodees credenciales en code.

SFTP (opcional)

const client = await sftp.connect({
  host: input.sftp.host,
  port: input.sftp.port || 22,
  username: input.sftp.username,
  password: input.sftp.password,
});

try {
  const files = await client.list("/entradas");
  output = {
    archivos: files.filter((f) => f.isFile).map((f) => f.name),
  };
} finally {
  await client.close();
}

Límites prácticos

El script corre con "use strict".
Usa throw new Error("...") para fallar el paso con un mensaje claro.
Los console.* se recortan si son muy grandes; no uses logs para transportar el resultado final: usa output.
Prefiere pasos cortos y deterministas; deja esperas largas al paso Esperar.

Ejemplo de solicitud completo

curl -X POST "https://api.insuranceboosters.com/api/v1/workflows" \
  -H "Content-Type: application/json" \
  -H "x-ib-api-key: TU_API_KEY" \
  -d '{
    "name": "Normalizar pago por webhook",
    "status": "disabled",
    "trigger": { "type": "webhook" },
    "steps": [
      {
        "name": "Normalizar pago",
        "actionKey": "code.javascript",
        "input": {
          "referencia": "{{trigger.body.referencia}}",
          "monto": "{{trigger.body.monto}}"
        },
        "code": "const referencia = String(input.referencia || \"\").trim();\nconst monto = Number(input.monto);\nif (!referencia) throw new Error(\"referencia requerida\");\nif (!Number.isFinite(monto) || monto <= 0) throw new Error(\"monto inválido\");\noutput = { referencia, monto };"
      }
    ]
  }'

​Campos del paso

​Contrato de ejecución

​Pasar variables desde un paso anterior

​Objetos y APIs disponibles

​Zona horaria

​Buen ejemplo: normalizar y validar

​Buen ejemplo: llamar una API con fetch

​Reutilizar archivos de pasos anteriores

​Detener el flujo con workflow.stop

​Enviar y leer correos con gmail

​Analizar adjuntos con files.analyze

​Guardar un archivo en un tablero

​Ejemplo: responder a una aseguradora

​Buen ejemplo: fechas con DateTime

​Malos ejemplos

​No asignar output

​Usar require o APIs de sistema

​Leer el trigger directo sin pasarlo por input

​Mutar estado “global” entre pasos

​MySQL (opcional)

​SFTP (opcional)

​Límites prácticos

​Ejemplo de solicitud completo