Durante cuatro módulos hemos escrito la API de Tienda Aroma: la diseñamos en el módulo 2, la construimos en el 3 y la endurecimos en el 4. Y en todo ese tiempo la hemos probado de dos maneras: con curl a mano, escribiendo cabeceras larguísimas en la terminal, y con las pruebas automáticas de Supertest de 03-08, que son excelentes para el código pero no sirven para explorar.

Falta una tercera forma de trabajar, la que ocupa el día a día real de quien desarrolla o consume una API: abrir un cliente, lanzar una petición, mirar la respuesta, cambiar un parámetro, volver a lanzarla. Y, cuando algo funciona, guardarlo para no volver a escribirlo nunca más ni depender de que alguien recuerde la sintaxis exacta.

Esta lección abre el módulo 5 con esa herramienta. Vamos a construir la colección "Tienda Aroma v1": un fichero versionable, con carpetas por recurso, entornos para local, pruebas y producción, autenticación que se renueva sola, aserciones que comprueban el contrato y peticiones encadenadas. Y terminaremos ejecutándola entera desde la terminal con Newman, que es exactamente lo que 05-05 conectará a la integración continua.

Todos los datos, dominios y credenciales de esta lección son ficticios. Ninguna cadena que parezca un token es un secreto real, y ningún ejemplo debe copiarse con valores reales dentro.

1. Por qué hace falta un cliente HTTP además de las pruebas automáticas
2. Qué es Postman y qué alternativas hay
3. Instalación y primer contacto: GET /v1/cafes
4. Leer la respuesta: cuerpo, cabeceras y tiempos
5. Colecciones y carpetas: la estructura de "Tienda Aroma v1"
6. Las peticiones reales del contrato
7. Variables: de colección, de entorno y globales
8. Entornos: local, pruebas y producción
9. Secretos: qué nunca se exporta
10. Autenticación: Bearer Token y herencia de carpeta
11. Scripts pre-request: lo que pasa antes de enviar
12. Scripts post-response: las aserciones
13. Encadenar peticiones: guardar el id y usarlo después
14. Generar una Idempotency-Key distinta en cada envío
15. Aserciones sobre el esquema JSON
16. Ejecutar la colección entera con el Collection Runner
17. Ficheros de datos CSV y JSON
18. Newman: la colección desde la terminal
19. Importar openapi.yaml y exportar la colección
20. Documentación y compartición con el equipo
21. El servidor mock de Postman
22. Buenas prácticas y qué va al repositorio

Las pruebas de 03-08 y un cliente como Postman responden a preguntas distintas, y confundirlas lleva a equipos que tienen una cosa y echan de menos la otra.

La frase clave es la última fila. Supertest no vería jamás que el balanceador de producción está eliminando la cabecera Aroma-Traza-Id, porque nunca hay balanceador: llama a app directamente. Y Postman no detectaría una regresión si nadie pulsa el botón. Por eso la meta de esta lección no es "aprender a pulsar Send", sino convertir la exploración manual en un artefacto repetible y ejecutable que, en 05-05, se pulsará solo.

Postman es un cliente HTTP con interfaz gráfica que guarda las peticiones en colecciones: ficheros JSON con las URLs, cabeceras, cuerpos, variables y scripts. Ese detalle —que una colección es un fichero— es el que la convierte en algo más que una herramienta personal: se versiona en Git, se revisa en un pull request y se ejecuta en la integración continua.

Estas son las alternativas serias que te vas a encontrar en equipos reales:

Comparación práctica de la misma petición en las tres formas de la terminal:

Y el mismo caso como fichero .http de la extensión REST Client, que tiene la ventaja de vivir dentro del repositorio junto al código que prueba:

Criterio de elección. Si tu equipo ya vive en Postman, quédate en Postman: la ganancia de cambiar rara vez compensa. Si te importa por encima de todo que las peticiones se revisen como código en los pull requests, Bruno o REST Client son mejores porque guardan texto plano legible. Todo lo conceptual de esta lección —variables, entornos, encadenado, aserciones, ejecución en CI— existe en las cuatro herramientas gráficas con otro nombre; lo que cambia es la sintaxis.

Usaremos Postman porque es el estándar de facto y porque Newman nos da la ejecución en CI que necesita 05-05.

Postman se descarga de su sitio oficial para Windows, macOS y Linux; también existe una versión web, aunque para llamar a localhost necesita el Postman Agent instalado, así que para nuestro caso conviene la aplicación de escritorio.

Antes de nada, levanta el proyecto de los módulos 3 y 4:

En Postman, Ctrl/Cmd + N → HTTP Request. Escribe el método GET y la URL:

Pulsa Send. Fíjate en que Postman ha entendido la cadena de consulta y ha rellenado sola la pestaña Params con una fila por parámetro: puedes activarlos y desactivarlos con la casilla, que es la forma cómoda de probar combinaciones de filtros sin editar texto.

La respuesta que devuelve nuestra API:

El cuerpo es lo primero que se mira y lo menos interesante para lo que hemos construido. En la parte inferior de Postman hay tres datos que resumen medio módulo 4:

• Status: 200 OK.
• Time: el tiempo total de la petición. Cuidado: incluye la resolución DNS, la conexión y el TLS, así que siempre será mayor que la latencia que mide prom-client en /metricas (04-07). Pasa el ratón por encima para ver el desglose por fases, que es la forma más rápida de descubrir que "la API va lenta" es en realidad "el handshake TLS tarda 300 ms".
• Size: el tamaño. Si activaste compression en 04-06, verás el tamaño comprimido.

La pestaña Headers de la respuesta es donde se comprueba el trabajo del módulo 4:

Cuatro comprobaciones que conviene hacer a mano la primera vez:

1. ETag y 304. Copia el valor del ETag, crea una petición idéntica con la cabecera If-None-Match puesta a ese valor y envíala. Debe responder 304 Not Modified sin cuerpo. Postman muestra Size: 0 B en el cuerpo: ahí ves de verdad el ahorro de 04-06.
2. Aroma-RateLimit-Restantes. Pulsa Send diez veces seguidas y observa cómo baja. Es la comprobación más simple de que el limitador de 04-04 está activo en este entorno.
3. Link. Copia la URL de rel="next" en una petición nueva: debe traerte la página siguiente sin que tengas que construir tú el desplazamiento. Si tienes que calcularlo a mano, HATEOAS no está funcionando.
4. Aroma-Traza-Id. Cópialo y búscalo en la salida de pino de tu terminal. Debe aparecer en todas las líneas de esa petición. Es la correlación de 04-07 vista desde fuera.

Consejo. Prueba también un error a propósito: GET /v1/cafes?tueste=morado. Debe responder 400 con {"error":{"codigo":"parametro_invalido",...}} y sin trazaId en el cuerpo, porque solo los 5xx lo llevan. Ver el contrato de errores cumpliéndose es tan importante como ver el camino feliz.

Una petición suelta se pierde. El paso siguiente es crear la colección. En el panel izquierdo: Collections → + y nómbrala Tienda Aroma v1.

La estructura que vamos a construir refleja los recursos del contrato de 02-02, no la implementación:

Tres decisiones de esa estructura merecen explicación:

• El prefijo numérico (00, 01, …) no es decorativo: el Collection Runner ejecuta las peticiones en el orden en que aparecen, y la carpeta 00 Sesiones debe correr primero porque es la que obtiene el token que usan todas las demás.
• Una carpeta por recurso, no por caso de uso. Los casos de uso cambian cada trimestre; los recursos son la parte estable del contrato.
• La carpeta 99 Errores esperados es la que distingue una colección profesional de una lista de peticiones. Documenta el comportamiento del catálogo de errores de 02-04 y detecta la regresión más habitual: alguien toca la autorización y un 403 se convierte en 500.

Estas son las peticiones centrales tal como quedan configuradas. Empezamos por el login, del que depende todo lo demás:

Respuesta esperada, 200, con el JWT que emitimos en 03-06:

Listado con filtros, usando la pestaña Params para poder desactivarlos uno a uno:

Creación de un café, que exige rol administrador según la matriz de permisos de 03-06:

Actualización parcial con merge-patch, el formato que fijamos en 02-05. Aquí es fácil equivocarse: el Content-Type no es application/json, y nuestra API responde 415 con Accept-Patch si lo pones mal.

Y la creación de pedido, la única —junto al pago— que exige Idempotency-Key:

Observa que ni un solo valor está escrito a fuego: {{urlBase}}, {{token}}, {{cafeId}}, {{claveIdempotencia}}. De eso trata el apartado siguiente.

Postman resuelve {{nombre}} buscando en varios ámbitos, del más específico al más general. Entender esta jerarquía evita el 80 % de los "pero si yo puse la URL bien".

Regla práctica: si el valor cambia según dónde apuntes, es de entorno; si es igual siempre, es de colección; si crees que es global, casi siempre estás equivocado. Las variables globales son la causa habitual de "en mi máquina funciona": alguien tiene un valor en su instalación que no está en el fichero que compartió.

Variables de colección de "Tienda Aroma v1":

Los identificadores sembrados (caf_001, ped_5001) van en la colección porque los garantiza el npm run sembrar de 03-05 en todos los entornos.

Un entorno es un conjunto de valores para las mismas claves. Se cambia con el desplegable de la esquina superior derecha, y toda la colección apunta a otro sitio sin tocar una sola petición.

Fichero de entorno local, exportable y sí versionable porque no contiene nada sensible:

permiteEscritura no es un capricho. Es el freno de mano que evita la peor historia posible con un cliente HTTP: ejecutar la colección entera contra producción y crear cuarenta cafés de prueba en el catálogo real. En el script pre-request de la carpeta de escritura:

Postman distingue el tipo de una variable: default (texto plano) o secret (se muestra enmascarada y no se incluye al exportar el entorno ni al compartirlo).

Reglas para Tienda Aroma:

• La contraseña real de cualquier cuenta, el client_secret de OAuth de 04-03 y cualquier token: siempre secret.
• Ningún token se escribe a mano. El token es un valor derivado: lo produce el login y lo guarda un script. Si lo pegas a mano, en una hora caduca y vuelves a pegarlo, y así hasta que alguien lo commitea.
• Las claves del entorno "producción" no se guardan en el fichero: se rellenan en el momento, o mejor aún, no existe un entorno de producción con permisos de escritura en la colección compartida.
• El fichero exportado se revisa antes de subirlo al repositorio. Un grep rápido evita disgustos:

Poner Authorization: Bearer {{token}} a mano en treinta peticiones es garantía de que tres se quedarán sin él. La pestaña Authorization existe para eso y funciona por herencia:

1. En la colección: Auth Type → Bearer Token, Token → {{token}}.
2. En cada petición: Auth Type → Inherit auth from parent (el valor por defecto).
3. En la carpeta 00 Sesiones y en el POST /v1/clientes de registro: Auth Type → No Auth, porque son públicas y enviar un token caducado a POST /v1/sesiones es un ruido innecesario.
4. En las peticiones de administración: Bearer Token → {{tokenAdmin}}, sobrescribiendo la herencia.

La carpeta 99 Errores esperados merece atención: la petición "Crear café sin token → 401" debe estar en No Auth explícito, y la de "Crear café como cliente → 403" en Bearer con {{token}} (el de Marta, rol cliente). Si ambas heredan lo mismo, una de las dos no prueba lo que dice probar.

Postman también soporta el flujo OAuth 2.0 completo de 04-03: en Auth Type → OAuth 2.0 puedes configurar Authorization Code con PKCE, y Postman abre el navegador, hace el intercambio y guarda el token. Es la forma correcta de probar la integración de CataBox, y de comprobar de verdad que un token con solo el ámbito cafes.leer recibe 403 permisos_insuficientes al intentar POST /v1/pedidos.

Cada petición, carpeta y colección tiene dos scripts en JavaScript: Pre-request (antes de enviar) y Post-response (al recibir; en versiones anteriores de Postman se llamaba "Tests"). Se ejecutan en cascada: primero el de la colección, luego el de la carpeta y por último el de la petición.

El uso más útil del pre-request en nuestra API es renovar el token si ha caducado, para que la colección funcione aunque lleves dos horas sin tocarla. En el script pre-request de la colección:

Puntos que conviene entender de este script:

• pm.sendRequest es asíncrono con callback. Postman espera a que termine antes de enviar la petición principal, pero cualquier pm.environment.set que hagas fuera del callback se ejecutará antes de tiempo.
• El margen de un minuto evita la carrera clásica: el token es válido cuando el script comprueba y ha caducado cuando llega al servidor.
• Lanzar un Error detiene la ejecución con un mensaje claro en lugar de dejarte investigando por qué todo devuelve 401.
• console.log escribe en la Postman Console (Ctrl/Cmd + Alt + C), que además muestra la petición HTTP exacta que se envió, cabeceras incluidas. Es la herramienta de depuración número uno y casi nadie la abre.

Aquí es donde la colección deja de ser documentación y se convierte en una prueba. La API es pm.test(nombre, funcion), y dentro se usa pm.expect, que es Chai.

Post-response de POST /v1/cafes:

Post-response de GET /v1/cafes, donde lo que se comprueba es la forma de la colección y la paginación de 02-06:

Y el error esperado de la carpeta 99, tan importante como el camino feliz:

El encadenado es lo que convierte una lista de peticiones en un recorrido. La técnica es siempre la misma: una petición guarda un valor en una variable, la siguiente lo consume.

En el post-response de POST /v1/cafes:

Ahora PATCH {{urlBase}}/cafes/{{cafeId}} con If-Match: {{cafeEtag}} funciona sin tocar nada, y el DELETE posterior también. Detalle importante: tras el PATCH, el ETag cambia (la versión ha subido), así que el post-response del PATCH debe volver a guardarlo, o el DELETE recibirá el 412 precondicion_fallida de 04-06. Es exactamente el mismo error que cometería un cliente real, y descubrirlo aquí es barato.

Este es el recorrido completo que ejecuta la colección:

La última petición es la que casi todo el mundo olvida: limpiar lo creado. Sin ella, cada ejecución deja un café nuevo en la base de datos y la colección deja de ser repetible.

Hay una alternativa al orden fijo que conviene conocer: postman.setNextRequest('nombre de la petición') permite saltar en la ejecución del runner, por ejemplo para omitir el resto de una carpeta si el login falló. Úsalo con moderación: colecciones con saltos por todas partes son ilegibles.

POST /v1/pedidos exige Idempotency-Key (02-03 y 04-01). Si la escribes fija, el segundo envío devolverá la misma respuesta que el primero en lugar de crear un pedido nuevo, que es precisamente lo que la cabecera promete. Y si cambias el cuerpo manteniendo la clave, recibirás 409 clave_idempotencia_reutilizada.

Postman tiene variables dinámicas incorporadas: basta con poner {{$guid}} como valor de la cabecera. Pero conviene generarla en el pre-request para poder reutilizar el mismo valor en la prueba de reintento:

Y una segunda petición idéntica, "Crear pedido (reintento)", que no regenera la clave y comprueba el contrato de idempotencia:

Otras variables dinámicas útiles: {{$timestamp}} (segundos Unix), {{$randomInt}}, {{$isoTimestamp}}, {{$randomEmail}}, {{$randomFullName}}. Sirven para crear clientes de prueba sin colisiones de email.

Comprobar propiedad a propiedad se vuelve insostenible. Postman incluye AJV, así que puedes validar la respuesta completa contra un JSON Schema:

additionalProperties: true es deliberado: si mañana añadimos paisTostado al recurso, la colección no debe romperse. Esa es la regla de compatibilidad hacia delante de 02-07 aplicada a las pruebas.

Duplicar estos esquemas a mano es tedioso y se desincroniza. Lo correcto es que salgan del openapi.yaml, y eso es exactamente lo que hará 05-04 con las pruebas de contrato; aquí queda como la solución rápida y suficiente para la exploración.

Botón derecho sobre la colección → Run collection. El runner ejecuta todas las peticiones en orden y muestra un informe con las aserciones que pasan y las que no.

Opciones que importan:

• Iterations: cuántas veces se repite la colección entera (con un fichero de datos, una por fila).
• Delay: milisegundos entre peticiones. Con el rate limiting de 04-04 activo, un runner sin delay puede comerse la cuota y provocar 429 a mitad de la ejecución. 50-100 ms suele bastar.
• Keep variable values: si se persisten los valores que escribieron los scripts. Actívalo mientras depuras, desactívalo para comprobar que la colección funciona desde cero.
• Run manually / Automatically: la ejecución paso a paso es utilísima para depurar un encadenado roto.

Para probar varios cafés sin duplicar peticiones, el runner acepta un fichero de datos; cada fila es una iteración y sus columnas se convierten en variables.

postman/datos-cafes.csv:

El cuerpo de la petición usa las columnas como variables, y observa el detalle de las comillas: {{precioEuros}} va sin comillas porque es un número, y {{nombre}} con ellas porque es texto.

La columna esperado permite que una sola petición valide casos válidos e inválidos:

Esto prueba de golpe la validación con Zod de 03-04 y el formato de error de 03-07, con cinco líneas de CSV en lugar de cinco peticiones.

Newman es el ejecutor de colecciones por línea de comandos. Es la pieza que hace que todo lo anterior sirva para algo más que para ti.

Exporta primero los ficheros (botón derecho → Export, formato Collection v2.1) a la carpeta postman/ del repositorio:

Y ejecuta:

El punto clave para 05-05: Newman devuelve un código de salida distinto de cero si alguna aserción falla. Eso es todo lo que necesita una tubería de CI para bloquear un despliegue.

Añádelo como script en package.json:

Y newman con newman-reporter-htmlextra van a devDependencies.

No hace falta crear las peticiones a mano si ya tienes el contrato. Import → File → openapi.yaml genera una colección completa con todas las rutas, parámetros, cuerpos de ejemplo y carpetas por tag.

Ventajas e inconvenientes, porque no es magia:

• A favor: cobertura instantánea de todos los endpoints, cuerpos prerrellenados con los example de la especificación, y una comprobación indirecta de que el openapi.yaml describe lo que crees.
• En contra: no trae scripts, ni encadenado, ni aserciones —lo que da valor a la colección—, y reimportar sobrevive mal: Postman crea una colección nueva en lugar de fusionar, y pierdes tus scripts.

Estrategia práctica: importa una vez para tener el esqueleto, añade encima scripts y encadenado, y a partir de ahí mantén la colección a mano. Cuando el contrato añada un endpoint nuevo, se importa a una colección temporal y se copia la petición que falte. La sincronización de verdad entre contrato e implementación no se resuelve aquí: se resuelve con las pruebas de contrato de 05-04.

Postman genera documentación navegable a partir de la colección: descripciones en Markdown de cada petición y carpeta, parámetros, y ejemplos de código en curl, JavaScript, Python o Go generados automáticamente.

Dos hábitos que multiplican su valor:

1. Guardar ejemplos de respuesta. En cada petición, botón "Save as Example" tras una respuesta buena. Guarda al menos el caso de éxito y uno de error por endpoint. Los ejemplos son lo que se ve en la documentación y, además, lo que sirve al servidor mock del apartado siguiente.
2. Escribir la descripción de cada carpeta explicando qué rol hace falta, qué precondiciones tiene y qué errores esperar. Es documentación que vive donde se usa.

Formas de compartir, de menos a más comprometida: exportar el JSON y meterlo en el repositorio (la que recomendamos, porque se revisa en pull requests y no depende de cuentas); publicar la documentación como enlace público; o usar los workspaces de equipo con sincronización en la nube, que son cómodos pero implican que el contenido de tus colecciones vive en un servidor de terceros —revísalo con seguridad antes de meter ahí una API interna—.

Para consumidores externos como CataBox, la documentación de Postman es una opción, pero el destino natural es el portal de desarrollador de 05-06, alimentado por el openapi.yaml de 05-02.

Postman puede levantar una URL pública que responde con los ejemplos guardados de tu colección. Sirve para que el equipo de la SPA empiece a maquetar la pantalla del catálogo antes de que exista el endpoint.

Se crea en tres clics y tiene dos límites importantes: responde ejemplos fijos, sin lógica —el filtro ?tueste=claro no filtra nada—, y depende de la nube de Postman.

Es una de varias opciones, y no la mejor si ya tienes contrato: Prism genera el mock directamente desde openapi.yaml, sin ejemplos que mantener aparte. Lo veremos a fondo en 05-04, junto con msw y nock.

• Escribir la URL completa en cada petición. El día que aparece un entorno de preproducción hay que editar cuarenta peticiones. {{urlBase}} desde la primera, siempre.
• Pegar el token a mano. Caduca en una hora y acabas con tokens en la colección exportada, es decir, en el repositorio. El token se obtiene con el login y se guarda con un script.
• Exportar el entorno con secretos dentro. Marca las variables sensibles como secret, revisa el fichero antes de commitear y añade postman/*.local.json al .gitignore.
• Aserciones que solo comprueban el estado. pm.response.to.have.status(200) pasa aunque la API devuelva un array vacío porque el filtro se ignoró. Comprueba también la forma y el contenido.
• Olvidar la limpieza. Cada ejecución deja datos. Termina cada carpeta con el DELETE de lo que creó, o siembra la base de datos antes con npm run bd:reiniciar.
• Confundir variables de entorno con variables de colección. Si urlBase está en la colección, el desplegable de entornos no hace nada y acabas apuntando siempre al mismo sitio.
• Ejecutar el runner sin delay contra un entorno con rate limiting. Fallos aleatorios 429 que parecen bugs de la API y no lo son. --delay-request 100, o una cuota específica para el cliente de CI (04-04).
• Content-Type: application/json en el PATCH. Nuestra API responde 415 formato_no_soportado con Accept-Patch. El valor correcto es application/merge-patch+json.
• No abrir la Postman Console. Ahí se ve la petición literal enviada, con las variables ya sustituidas. La mayoría de los "no entiendo qué pasa" se resuelven en diez segundos mirándola.
• Consejo: nombra las peticiones por lo que prueban, no por el método. "Crear café como cliente → 403" dice mucho más que "POST cafes 2".
• Consejo: mete la colección en el mismo repositorio que la API. Así el pull request que cambia un endpoint cambia también su petición, y la revisión detecta las incoherencias.

Construye la carpeta 99 Errores esperados de la colección "Tienda Aroma v1" con cinco peticiones que verifiquen el catálogo de 02-04, y escribe sus aserciones. Los casos: café inexistente (404 cafe_no_encontrado), parámetro de consulta inválido (400 parametro_invalido), creación sin token (401 no_autenticado con WWW-Authenticate), creación con rol cliente (403 permisos_insuficientes) y PUT /v1/cafes (405 metodo_no_permitido con Allow).

Indica para cada una qué configuración de Authorization necesita y escribe el script post-response de al menos tres de ellas.

Crea una carpeta 10 Recorrido de compra que ejecute, en orden y sin intervención manual: login como Marta → listar cafés (guardando el id del primero con stock disponible) → crear pedido con Idempotency-Key generada → pagar el pedido → consultar el pedido y comprobar que su estado es pagado.

Escribe los scripts necesarios y explica qué variables se pasan entre peticiones y en qué ámbito las guardarías.

Prepara la ejecución de la colección en la terminal para que sirva como puerta de calidad antes de un despliegue: un fichero de datos con al menos dos casos válidos y dos inválidos de creación de café, el comando de Newman que la ejecuta contra el entorno de pruebas inyectando la contraseña sin escribirla en ningún fichero, y el script de package.json. Explica cómo sabrá el sistema de CI si debe bloquear el despliegue.

Configuración de autenticación por petición:

Petición 3 — POST {{urlBase}}/cafes sin token:

Petición 4 — POST {{urlBase}}/cafes con el token de Marta (rol cliente):

Petición 5 — PUT {{urlBase}}/cafes:

Ámbitos elegidos: todas las variables del recorrido van a pm.collectionVariables, no a pm.environment. Motivo: son valores efímeros de una ejecución concreta y no deben ensuciar el fichero de entorno que se comparte. El token es la excepción: va al entorno porque lo comparten todas las carpetas y lo gestiona el pre-request de la colección.

Petición 1 — POST {{urlBase}}/sesiones (No Auth). Post-response:

Petición 2 — GET {{urlBase}}/cafes?disponible=true&limite=5:

Petición 3 — POST {{urlBase}}/pedidos. Pre-request:

Cuerpo y post-response:

Petición 4 — POST {{urlBase}}/pedidos/{{pedidoId}}/pago con Idempotency-Key: {{$guid}}:

Petición 5 — GET {{urlBase}}/pedidos/{{pedidoId}}:

Variables que viajan: token (entorno) → todas; clienteId y cafeId (colección) → petición 3; pedidoId (colección) → peticiones 4 y 5; claveIdempotencia (colección) → petición 3.

Fichero postman/datos-cafes.csv:

Post-response que cubre ambos casos:

Comando con el secreto inyectado desde fuera:

--env-var sobrescribe el valor del fichero de entorno. Así el fichero versionado puede tener claveCliente vacía y el valor real llega de una variable de entorno que en CI proviene del gestor de secretos (05-05), nunca del repositorio.

Script en package.json:

Cómo bloquea el despliegue. Newman sale con código 0 si todas las aserciones pasan y con un código distinto de cero si alguna falla o hay un error de red. Cualquier sistema de CI interpreta un código de salida distinto de cero como paso fallido y detiene la tubería. Además, el informe junit permite que la interfaz muestre exactamente qué aserción falló, sin tener que leer el log. Si se quiere que el fallo sea inmediato en lugar de ejecutar toda la colección, se añade --bail.

Has convertido la exploración manual en un artefacto. La colección "Tienda Aroma v1" ya no es una lista de URLs: tiene carpetas por recurso que reflejan el contrato de 02-02, entornos que permiten apuntar a local, pruebas o producción sin editar una sola petición, un freno de mano que impide escribir en producción por accidente, y un pre-request que renueva el token del login de 03-06 antes de que caduque, sin que nadie pegue credenciales a mano.

Sobre esa base has puesto lo que la convierte en una prueba: aserciones que verifican el 201 y su Location, la forma {datos, total} de las colecciones, que los filtros de 02-06 filtren de verdad, que el precio salga en euros y no en céntimos, que los errores del catálogo de 02-04 lleguen con su código exacto y sin trazaId en los 4xx, y esquemas JSON validados con AJV que toleran campos nuevos. Has encadenado un recorrido completo de compra pasando el id y el ETag de una petición a la siguiente, has generado una Idempotency-Key por ejecución para probar el reintento de 02-03, y has multiplicado los casos con un fichero CSV en el que cada fila declara el código que espera. Y con Newman todo eso se ejecuta desde la terminal, con un código de salida que basta para bloquear un despliegue: los ficheros nuevos del proyecto son postman/tienda-aroma-v1.postman_collection.json, postman/local.postman_environment.json, postman/pruebas.postman_environment.json y postman/datos-cafes.csv, con newman en devDependencies y los scripts pruebas:api y pruebas:humo en package.json.

Queda un cabo suelto y es el importante: la colección es una segunda descripción de la API, escrita a mano, que puede desviarse de la real sin que nadie se entere. Ya tenemos una descripción mejor —el openapi.yaml que arrastramos desde 02-08— pero está a medias: un solo endpoint, sin esquemas completos, sin seguridad declarada y sin publicar. En 05-02, Swagger y OpenAPI para documentación, lo terminamos: la anatomía completa del documento sección a sección, components con esquemas, parámetros y respuestas reutilizables, los securitySchemes con los ámbitos OAuth de 04-03, la diferencia entre escribirlo a mano y generarlo desde el código, Swagger UI servido en /docs dentro del propio proyecto, la validación con swagger-cli y las reglas de Spectral de 04-01, y la generación de clientes TypeScript para la SPA y para Aroma Móvil a partir del contrato.