Algunas solicitudes requieren trabajo antes de salir de tu máquina, y otras necesitan trabajo en el momento en que llega una respuesta. Una API de pago quiere una firma HMAC calculada a partir de una marca de tiempo y tu secreto. Un punto final de inicio de sesión devuelve un token que cada llamada posterior necesita. Un flujo de pago tiene que afirmar que la respuesta realmente devolvió un 200 y el ID de pedido correcto. Puedes hacer todo esto manualmente, pero eso se vuelve tedioso rápidamente y se rompe en el momento en que compartes la solicitud con un compañero de equipo.
Los scripts solucionan eso. En Apidog, adjuntas pequeños fragmentos de JavaScript a una solicitud que se ejecutan automáticamente: un conjunto antes de que se envíe la solicitud, otro después de que la respuesta regrese. Si ya has escrito scripts de Postman, la memoria muscular se traslada, porque el motor de Apidog es compatible con la misma API de objeto pm. Esta guía recorre ambas etapas con un ejemplo realista: firmar una solicitud en un script de pre-solicitud y luego extraer un token en un script de post-respuesta. El comportamiento está documentado completamente en la documentación de scripts de Apidog, pero los nombres de las pestañas y algunos comportamientos difieren de Postman, y esas diferencias importan.
Qué hacen realmente los scripts de pre y post
Apidog ejecuta scripts en dos etapas, y los nombra claramente.
Preprocesadores se ejecutan antes de que la solicitud sea enviada al servidor. Aquí es donde preparas las cosas: generas una marca de tiempo, calculas una firma, estableces un ID de pedido aleatorio, o lees una variable y la conviertes en una cabecera. La respuesta aún no existe en este punto, por lo que cualquier cosa que inspeccione una respuesta está prohibida aquí.
Postprocesadores se ejecutan después de que se recibe la respuesta. Aquí es donde verificas lo que regresó con aserciones, y donde extraes valores del cuerpo para reutilizarlos más tarde. Extrae un token de autenticación, toma el ID de un recurso recién creado, verifica el código de estado, guarda un cursor para la paginación.
De esa división se derivan dos reglas. Primero, pm.response (con su code, status, headers, responseTime, responseSize, text(), y json()) solo funciona en los Postprocesadores. No hay respuesta que leer antes de enviar, por lo que llamarlo en un Preprocesador no te ayudará. Segundo, las variables son la forma en que las dos etapas se comunican entre sí. Un Preprocesador establece un valor, la solicitud lo usa, y un Postprocesador puede leerlo o sobrescribirlo.
Si vienes de Postman, ten en cuenta el cambio de etiquetas desde el principio. Las pestañas de Apidog son Preprocesadores y Postprocesadores, no "Script de Pre-solicitud" y "Pruebas". El comportamiento es muy similar, pero los nombres en pantalla son diferentes.
Configuración: abre una solicitud y encuentra las pestañas
Descarga Apidog para seguir la guía. Es gratis y funciona en macOS, Windows y Linux, así que descárgalo desde la página Descargar Apidog si aún no lo tienes.
Abre la solicitud de API que quieres programar dentro de Apidog. Cada endpoint tiene una pestaña de Preprocesadores y una pestaña de Postprocesadores junto a las pestañas habituales de Params, Headers y Body. Para añadir lógica a cualquiera de las etapas, abre la pestaña y selecciona añadir un Script Personalizado. Esto abre un editor de código donde escribes JavaScript puro contra el objeto pm.
Antes de escribir cualquier cosa, es útil saber dónde residen los valores. Apidog resuelve las variables en este orden de prioridad:
Variables Locales > Variables de Entorno > Variables Globales Compartidas dentro del Proyecto > Variables Globales Compartidas dentro del Equipo.
Así, una variable local prevalece sobre una variable de entorno del mismo nombre, y así sucesivamente en la lista. Ten esto en cuenta cuando un valor no sea lo que esperas: algo superior en el orden probablemente lo está ocultando. Si quieres valores que persistan en muchas solicitudes, los parámetros globales en Apidog se encuentran más abajo en el orden de prioridad y son un buen lugar para configuraciones estables a nivel de proyecto.
Ejemplo de Preprocesador: firmar una solicitud con HMAC
Supongamos que llamas a un endpoint de pagos que autentica cada solicitud con una firma HMAC-SHA256. Este es el mismo patrón que muchos proveedores utilizan para la verificación de webhooks, y la documentación de firmas de Stripe lo describe bien: el servidor espera una marca de tiempo y una firma calculada sobre esa marca de tiempo más el cuerpo de la solicitud, con clave de tu secreto de API. Necesitas construir ambos desde cero en cada envío.
Apidog incluye crypto-js como una librería incorporada, por lo que no necesitas instalar nada. Abre la pestaña de Preprocesadores, selecciona añadir un Script Personalizado, y escribe esto:
// Preprocesador: firma la solicitud antes de que se envíe
const CryptoJS = require('crypto-js');
// marca de tiempo unix actual en segundos
const timestamp = Math.floor(Date.now() / 1000).toString();
// lee el secreto de una variable de entorno
const secret = pm.environment.get('payments_api_secret');
// construye la cadena a firmar: marca de tiempo + nueva línea + cuerpo crudo
const body = pm.request.body ? pm.request.body.toString() : '';
const payload = timestamp + '\n' + body;
// calcula la firma HMAC-SHA256, codificada en hexadecimal
const signature = CryptoJS.HmacSHA256(payload, secret).toString(CryptoJS.enc.Hex);
// guarda ambos valores como variables de entorno para que la solicitud los use
pm.environment.set('x_timestamp', timestamp);
pm.environment.set('x_signature', signature);
pm.console.log('Solicitud firmada en ' + timestamp);
Ese script calcula la firma y guarda tanto la marca de tiempo como la firma en variables de entorno. Ahora incorpóralas a la solicitud. En la pestaña Headers, referencia los valores almacenados con la sintaxis {{variableName}}:
X-Timestamp: {{x_timestamp}}
X-Signature: {{x_signature}}
Cuando envías, Apidog ejecuta primero el Preprocesador, establece las dos variables, y luego las sustituye en las cabeceras. El servidor recibe una firma que era válida en el momento del envío, cada vez, sin pasos manuales. Ten en cuenta que la llamada a require('crypto-js') importa el módulo completo. Importas la librería entera, no un submódulo, por lo que require('crypto-js') funciona y require('crypto-js/sha256') no.
Una cosa a tener en cuenta: las operaciones con variables solo afectan a los valores actuales, no a los valores iniciales que podrías haber escrito en el editor de entorno. Esto es lo que se busca aquí, ya que la firma está destinada a ser efímera. Si también necesitas explicaciones sobre patrones de firma para el lado de Postman, la guía sobre scripts de pre-solicitud de Postman cubre la misma idea con las etiquetas de Postman, y se aplica directamente a los Preprocesadores de Apidog.
Ejemplo de Postprocesador: extraer un token y afirmar
Ahora la otra etapa. Imagina una solicitud de inicio de sesión que devuelve un token que necesitas para cada llamada autenticada posterior:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": { "id": 4812, "email": "dana@example.com" },
"expires_in": 3600
}
Abre la pestaña de Postprocesadores, selecciona añadir un Script Personalizado, y extrae el token del cuerpo, guardándolo para futuras solicitudes:
// Postprocesador: verifica la respuesta y luego extrae el token
pm.test('El estado es 200', function () {
pm.response.to.have.status(200);
});
const jsonData = pm.response.json();
pm.test('La respuesta devuelve un token', function () {
pm.expect(jsonData.token).to.be.a('string').and.not.empty;
});
pm.test('El ID de usuario está presente', function () {
pm.expect(jsonData.user.id).to.be.a('number');
});
// guarda el token para que otras solicitudes puedan enviarlo
pm.environment.set('auth_token', jsonData.token);
pm.console.log('Token guardado para el usuario ' + jsonData.user.email);
Aquí suceden dos cosas. Los bloques pm.test() afirman que la respuesta tiene la forma que esperas, utilizando los matchers pm.expect() de estilo Chai que Apidog soporta nativamente. Y pm.environment.set('auth_token', jsonData.token) guarda el token en el entorno. Cualquier solicitud posterior ahora puede enviar Authorization: Bearer {{auth_token}} sin que tengas que copiar nada manualmente.
La mitad de aserción de esto merece atención por sí misma. Las buenas comprobaciones posteriores a la respuesta son lo que convierte un clic y una inspección manual en una prueba real, y nuestra guía sobre aseraciones de API en Apidog profundiza en los matchers y patrones que vale la pena conocer. Si también quieres introducir datos falsos realistas en estos flujos, Faker.js en Apidog se combina bien con la configuración de variables mostrada anteriormente.
Un par de comportamientos a tener claros en los Postprocesadores. pm.iterationData (tus datos de prueba) es de solo lectura, por lo que puedes leer un valor basado en datos pero no puedes escribirlo de nuevo desde un script. Y pm.cookies devuelve la cookie de la respuesta, la que el servidor envió de vuelta, no la cookie que salió con tu solicitud.
Reutilizar lógica con Scripts Públicos
Una vez que hayas escrito ese bloque de firma HMAC, probablemente lo querrás en más de una solicitud. Copiar y pegarlo en diez endpoints significa diez lugares para arreglar cuando el algoritmo cambie. La respuesta de Apidog son los Scripts Públicos: fragmentos reutilizables que escribes una vez y adjuntas donde sea necesario.
Crea uno en Configuración > Scripts Públicos, luego añádelo a la pestaña de Preprocesadores o Postprocesadores de una solicitud. Dentro de una lista de procesadores, un Script Público y un Script Personalizado se encuentran uno al lado del otro, y el orden importa: los scripts públicos se ejecutan antes que los scripts personalizados en la misma lista, y si tienes varios scripts públicos, se ejecutan de arriba a abajo en el orden listado.
Hay un truco que confunde a la gente. Si quieres que un Script Personalizado llame a una función definida en un Script Público, esa función tiene que ser global. Una declaración de function normal o una función ligada a const es local a su propio script e invisible para el siguiente. Declárala asignando sin var, let o const:
// En el Script Público: haz que sign() sea global omitiendo la palabra clave
sign = function (payload, secret) {
const CryptoJS = require('crypto-js');
return CryptoJS.HmacSHA256(payload, secret).toString(CryptoJS.enc.Hex);
};
// En el Script Personalizado debajo: llama a la función global por su nombre
const timestamp = Math.floor(Date.now() / 1000).toString();
const secret = pm.environment.get('payments_api_secret');
pm.environment.set('x_timestamp', timestamp);
pm.environment.set('x_signature', sign(timestamp, secret));
Añade primero el Script Público, coloca el Script Personalizado debajo, y la llamada se resuelve. Si el orden es incorrecto o añades un const, obtendrás un error de función indefinida.
Librerías, paquetes externos y depuración
La importación de crypto-js anterior es una de un conjunto de librerías que Apidog incluye sin necesidad de configuración. Puedes require() cualquiera de ellas directamente:
crypto-js(v3.1.9-1) para hashing y HMACjsrsasign(v10.3.0) para JWT y trabajo RSA, que requiere Apidog 1.4.5 o posteriorchai(v4.2.0) para los matchers de aserciónlodash,moment,uuid,xml2js,cheerio,postman-collection,atob,btoa,csv-parse/lib/sync,tv4,ajv- Funciones incorporadas de Node como
path,assert,buffer,util,url,querystring,streamyevents
Si necesitas algo que no esté en esa lista, incorpóralo en tiempo de ejecución con $$.liveRequire(), que descarga el paquete sobre la marcha:
$$.liveRequire('nanoid', (nanoid) => {
const id = nanoid.nanoid();
pm.environment.set('request_id', id);
});
Esa ruta necesita una conexión a internet, ya que Apidog descarga el paquete cuando se ejecuta el script. Las librerías incluidas no.
Cuando un script se comporta mal, depura con logs. Tanto pm.console.log() como el simple console.log() imprimen en la consola de Apidog, para que puedas volcar una firma calculada o un campo extraído y ver exactamente lo que produjo el script antes de que la solicitud salga o después de que regrese.
Dos límites más que vale la pena mencionar para que no te sorprendan. pm.sendRequest(), para disparar una llamada HTTP extra dentro de un script, utiliza un patrón de callback en lugar de Promesas, así que escríbelo con un callback, no con await. Y pm.nextRequest() de Postman para encadenar solicitudes no es compatible aquí. Cuando necesitas una orquestación de flujo de trabajo real, con bifurcaciones y pasos condicionales, Apidog utiliza en su lugar Escenarios de Prueba, donde se secuencian las solicitudes visualmente con pasos de Condición e If-Else. Si escribes muchos scripts, el Generador de Scripts de Apidog incorporado también puede redactar uno a partir de una descripción en lenguaje natural para darte un punto de partida.
Automatiza el flujo de trabajo con la CLI de Apidog
Los scripts no solo se ejecutan cuando haces clic en Enviar. Cuando empaquetas tus solicitudes y aserciones en un Escenario de Prueba guardado, la CLI de Apidog ejecuta todo ese escenario sin interfaz gráfica, incluyendo Preprocesadores y Postprocesadores, lo que convierte tu lógica de firma y extracción de tokens en parte de la CI en lugar de un paso manual.
Instala la CLI y autentícate, luego ejecuta un escenario por ID:
npm install -g apidog-cli
apidog login --with-token <TU_TOKEN_DE_ACCESO>
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <ID_ESCENARIO> -e <ID_ENTORNO> -r cli
La bandera -t es el ID del escenario de prueba, -e es el ID del entorno, y -r selecciona el reportero (cli, html o junit, separados por comas para varios). Genera el token de acceso en la configuración de tu cuenta de Apidog, expórtalo como APIDOG_ACCESS_TOKEN, y el mismo escenario que se ejecutó en tu escritorio ahora se ejecuta en CI, incluyendo Preprocesadores y Postprocesadores.
Una advertencia honesta: un script que se apoya en algo presente solo en tu máquina, un archivo local o un paquete que cargaste una vez, puede pasar en la aplicación de escritorio y luego fallar en la CLI, porque el ejecutor no tiene esa dependencia. Mantén los scripts con las librerías incluidas o $$.liveRequire() para que se ejecuten igual en todas partes.
Preguntas Frecuentes
¿Son compatibles los scripts de Apidog con mis scripts de Postman existentes?
En su mayoría, sí. El motor de Apidog utiliza la misma API de objeto pm, por lo que pm.environment.set(), pm.response.json(), pm.test() y pm.expect() se comportan como ya conoces. Las dos diferencias a recordar son los nombres de las pestañas, Preprocesadores y Postprocesadores en lugar de "Script de Pre-solicitud" y "Pruebas", y algunas llamadas no compatibles como pm.nextRequest(). La mayoría de los scripts se pueden pegar y ejecutar.
¿Por qué pm.response devuelve indefinido en mi script de pre-solicitud?
Porque aún no hay respuesta. Los Preprocesadores se ejecutan antes de que se envíe la solicitud, por lo que nada ha regresado para inspeccionar. Cualquier código que lea pm.response (su estado, cuerpo, cabeceras) pertenece a un Postprocesador. Si necesitas un valor en la etapa previa, recupéralo de pm.request, de una variable o de una librería.
¿Cómo comparto un script entre varias solicitudes?
Usa Scripts Públicos en Configuración > Scripts Públicos. Escribe la lógica una vez, adjúntala a la pestaña de Preprocesadores o Postprocesadores de cada solicitud, y recuerda que los scripts públicos se ejecutan antes que los scripts personalizados en la misma lista. Para llamar a una función de un Script Público desde un Script Personalizado, declárala global asignando sin var, let o const.
¿Puedo importar un paquete npm que Apidog no incluye?
Sí, con $$.liveRequire('package-name', (pkg) => { ... }), que descarga el paquete en tiempo de ejecución y necesita una conexión a internet. Para cualquier cosa de la lista incorporada, como crypto-js, moment o uuid, usa un simple require() sin necesidad de red. Ten en cuenta que solo puedes requerir un módulo completo, no una ruta de submódulo.
¿Dónde veo lo que imprimió mi script?
Usa pm.console.log() o console.log() y lee la salida en la consola de Apidog después de enviar la solicitud. Es la forma más rápida de confirmar que se calculó una firma o se extrajo un token antes de confiar en ello en un escenario.
Conclusión
Los Preprocesadores y Postprocesadores convierten una solicitud estática en una que se prepara y verifica su propio trabajo. Firma antes de enviar, extrae y afirma después de recibir, y eleva la lógica compartida a Scripts Públicos para que la escribas una sola vez. La API pm y las librerías incluidas significan que la mayoría de lo que conoces de Postman se traslada directamente. Abre Apidog, elige cualquier solicitud y añade tu primer Script Personalizado para ver cómo ambas etapas se ejecutan en un solo envío. Es gratis para empezar, no se requiere tarjeta de crédito.