Durant quatre mòduls hem escrit l'API de la Botiga Aroma: la vam dissenyar al mòdul 2, la vam construir al 3 i la vam endurir al 4. I en tot aquest temps l'hem provada de dues maneres: amb curl a mà, escrivint capçaleres llarguíssimes a la terminal, i amb les proves automàtiques de Supertest de 03-08, que són excel·lents per al codi però no serveixen per explorar.

Falta una tercera manera de treballar, la que ocupa el dia a dia real de qui desenvolupa o consumeix una API: obrir un client, llançar una petició, mirar la resposta, canviar un paràmetre, tornar-la a llançar. I, quan alguna cosa funciona, desar-la per no haver-la de tornar a escriure mai més ni dependre que algú recordi la sintaxi exacta.

Aquesta lliçó obre el mòdul 5 amb aquesta eina. Construirem la col·lecció «Botiga Aroma v1»: un fitxer versionable, amb carpetes per recurs, entorns per a local, proves i producció, autenticació que es renova sola, assercions que comproven el contracte i peticions encadenades. I acabarem executant-la sencera des de la terminal amb Newman, que és exactament el que 05-05 connectarà a la integració contínua.

Totes les dades, dominis i credencials d'aquesta lliçó són ficticis. Cap cadena que sembli un token no és un secret real, i cap exemple no s'ha de copiar amb valors reals a dins.

1. Per què cal un client HTTP a més de les proves automàtiques
2. Què és Postman i quines alternatives hi ha
3. Instal·lació i primer contacte: GET /v1/cafes
4. Llegir la resposta: cos, capçaleres i temps
5. Col·leccions i carpetes: l'estructura de «Botiga Aroma v1»
6. Les peticions reals del contracte
7. Variables: de col·lecció, d'entorn i globals
8. Entorns: local, proves i producció
9. Secrets: què no s'exporta mai
10. Autenticació: Bearer Token i herència de carpeta
11. Scripts pre-request: el que passa abans d'enviar
12. Scripts post-response: les assercions
13. Encadenar peticions: desar l'id i fer-lo servir després
14. Generar una Idempotency-Key diferent a cada enviament
15. Assercions sobre l'esquema JSON
16. Executar la col·lecció sencera amb el Collection Runner
17. Fitxers de dades CSV i JSON
18. Newman: la col·lecció des de la terminal
19. Importar openapi.yaml i exportar la col·lecció
20. Documentació i compartició amb l'equip
21. El servidor mock de Postman
22. Bones pràctiques i què va al repositori

Les proves de 03-08 i un client com Postman responen a preguntes diferents, i confondre-les porta a equips que tenen una cosa i troben a faltar l'altra.

La frase clau és l'última fila. Supertest no veuria mai que el balancejador de producció està eliminant la capçalera Aroma-Traca-Id, perquè mai no hi ha balancejador: crida app directament. I Postman no detectaria una regressió si ningú no prem el botó. Per això la meta d'aquesta lliçó no és «aprendre a prémer Send», sinó convertir l'exploració manual en un artefacte repetible i executable que, a 05-05, es premerà sol.

Postman és un client HTTP amb interfície gràfica que desa les peticions en col·leccions: fitxers JSON amb les URL, capçaleres, cossos, variables i scripts. Aquest detall —que una col·lecció és un fitxer— és el que la converteix en una cosa més que una eina personal: es versiona a Git, es revisa en un pull request i s'executa a la integració contínua.

Aquestes són les alternatives serioses que et trobaràs en equips reals:

Comparació pràctica de la mateixa petició en les tres formes de la terminal:

I el mateix cas com a fitxer .http de l'extensió REST Client, que té l'avantatge de viure dins del repositori al costat del codi que prova:

Criteri d'elecció. Si el teu equip ja viu a Postman, queda't a Postman: el guany de canviar poques vegades compensa. Si t'importa per damunt de tot que les peticions es revisin com a codi als pull requests, Bruno o REST Client són millors perquè desen text pla llegible. Tot el que és conceptual d'aquesta lliçó —variables, entorns, encadenat, assercions, execució a CI— existeix a les quatre eines gràfiques amb un altre nom; el que canvia és la sintaxi.

Farem servir Postman perquè és l'estàndard de facto i perquè Newman ens dona l'execució a CI que necessita 05-05.

Postman es descarrega del seu lloc oficial per a Windows, macOS i Linux; també n'existeix una versió web, encara que per cridar localhost necessita el Postman Agent instal·lat, així que per al nostre cas convé l'aplicació d'escriptori.

Abans de res, aixeca el projecte dels mòduls 3 i 4:

A Postman, Ctrl/Cmd + N → HTTP Request. Escriu el mètode GET i la URL:

Prem Send. Fixa't que Postman ha entès la cadena de consulta i ha omplert sola la pestanya Params amb una fila per paràmetre: pots activar-los i desactivar-los amb la casella, que és la manera còmoda de provar combinacions de filtres sense editar text.

La resposta que retorna la nostra API:

El cos és el primer que es mira i el menys interessant per al que hem construït. A la part inferior de Postman hi ha tres dades que resumeixen mig mòdul 4:

• Status: 200 OK.
• Time: el temps total de la petició. Compte: inclou la resolució DNS, la connexió i el TLS, així que sempre serà més gran que la latència que mesura prom-client a /metriques (04-07). Passa-hi el ratolí per sobre per veure'n el desglossament per fases, que és la manera més ràpida de descobrir que «l'API va lenta» és en realitat «l'encaixada TLS triga 300 ms».
• Size: la mida. Si vas activar compression a 04-06, hi veuràs la mida comprimida.

La pestanya Headers de la resposta és on es comprova la feina del mòdul 4:

Quatre comprovacions que convé fer a mà la primera vegada:

1. ETag i 304. Copia el valor de l'ETag, crea una petició idèntica amb la capçalera If-None-Match posada a aquest valor i envia-la. Ha de respondre 304 Not Modified sense cos. Postman mostra Size: 0 B al cos: aquí veus de debò l'estalvi de 04-06.
2. Aroma-RateLimit-Restants. Prem Send deu vegades seguides i observa com baixa. És la comprovació més simple que el limitador de 04-04 està actiu en aquest entorn.
3. Link. Copia la URL de rel="next" en una petició nova: t'ha de portar la pàgina següent sense que hagis de construir tu el desplacament. Si l'has de calcular a mà, HATEOAS no està funcionant.
4. Aroma-Traca-Id. Copia'l i cerca'l a la sortida de pino de la teva terminal. Ha d'aparèixer a totes les línies d'aquella petició. És la correlació de 04-07 vista des de fora.

Consell. Prova també un error a propòsit: GET /v1/cafes?torrefaccio=morat. Ha de respondre 400 amb {"error":{"codi":"parametre_invalid",...}} i sense tracaId al cos, perquè només els 5xx el porten. Veure el contracte d'errors complint-se és tan important com veure el camí feliç.

Una petició solta es perd. El pas següent és crear la col·lecció. Al panell esquerre: Collections → + i anomena-la Botiga Aroma v1.

L'estructura que construirem reflecteix els recursos del contracte de 02-02, no la implementació:

Tres decisions d'aquesta estructura mereixen explicació:

• El prefix numèric (00, 01, …) no és decoratiu: el Collection Runner executa les peticions en l'ordre en què apareixen, i la carpeta 00 Sessions ha d'anar primer perquè és la que obté el token que fan servir totes les altres.
• Una carpeta per recurs, no per cas d'ús. Els casos d'ús canvien cada trimestre; els recursos són la part estable del contracte.
• La carpeta 99 Errors esperats és la que distingeix una col·lecció professional d'una llista de peticions. Documenta el comportament del catàleg d'errors de 02-04 i detecta la regressió més habitual: algú toca l'autorització i un 403 es converteix en 500.

Aquestes són les peticions centrals tal com queden configurades. Comencem per l'inici de sessió, del qual depèn tota la resta:

Resposta esperada, 200, amb el JWT que emetem a 03-06:

Llistat amb filtres, fent servir la pestanya Params per poder desactivar-los un a un:

Creació d'un cafè, que exigeix rol administrador segons la matriu de permisos de 03-06:

Actualització parcial amb merge-patch, el format que vam fixar a 02-05. Aquí és fàcil equivocar-se: el Content-Type no és application/json, i la nostra API respon 415 amb Accept-Patch si el poses malament.

I la creació de comanda, l'única —juntament amb el pagament— que exigeix Idempotency-Key:

Observa que no hi ha ni un sol valor escrit a foc: {{urlBase}}, {{token}}, {{cafeId}}, {{clauIdempotencia}}. D'això tracta l'apartat següent.

Postman resol {{nom}} cercant en diversos àmbits, del més específic al més general. Entendre aquesta jerarquia evita el 80 % dels «però si jo vaig posar bé la URL».

Regla pràctica: si el valor canvia segons on apuntis, és d'entorn; si és igual sempre, és de col·lecció; si creus que és global, gairebé sempre t'equivoques. Les variables globals són la causa habitual de «a la meva màquina funciona»: algú té un valor a la seva instal·lació que no és al fitxer que va compartir.

Variables de col·lecció de «Botiga Aroma v1»:

Els identificadors sembrats (caf_001, com_5001) van a la col·lecció perquè els garanteix el npm run sembrar de 03-05 a tots els entorns.

Un entorn és un conjunt de valors per a les mateixes claus. Es canvia amb el desplegable de la cantonada superior dreta, i tota la col·lecció apunta a un altre lloc sense tocar ni una petició.

Fitxer d'entorn local, exportable i sí versionable perquè no conté res sensible:

permetEscriptura no és un caprici. És el fre de mà que evita la pitjor història possible amb un client HTTP: executar la col·lecció sencera contra producció i crear quaranta cafès de prova al catàleg real. A l'script pre-request de la carpeta d'escriptura:

Postman distingeix el tipus d'una variable: default (text pla) o secret (es mostra emmascarada i no s'inclou en exportar l'entorn ni en compartir-lo).

Regles per a la Botiga Aroma:

• La contrasenya real de qualsevol compte, el client_secret d'OAuth de 04-03 i qualsevol token: sempre secret.
• Cap token no s'escriu a mà. El token és un valor derivat: el produeix l'inici de sessió i el desa un script. Si l'enganxes a mà, en una hora caduca i el tornes a enganxar, i així fins que algú el commiteja.
• Les claus de l'entorn «producció» no es desen al fitxer: s'omplen al moment o, encara millor, no existeix un entorn de producció amb permisos d'escriptura a la col·lecció compartida.
• El fitxer exportat es revisa abans de pujar-lo al repositori. Un grep ràpid evita disgustos:

Posar Authorization: Bearer {{token}} a mà en trenta peticions és garantia que tres es quedaran sense. La pestanya Authorization existeix per a això i funciona per herència:

1. A la col·lecció: Auth Type → Bearer Token, Token → {{token}}.
2. A cada petició: Auth Type → Inherit auth from parent (el valor per defecte).
3. A la carpeta 00 Sessions i al POST /v1/clients de registre: Auth Type → No Auth, perquè són públiques i enviar un token caducat a POST /v1/sessions és un soroll innecessari.
4. A les peticions d'administració: Bearer Token → {{tokenAdmin}}, sobreescrivint l'herència.

La carpeta 99 Errors esperats mereix atenció: la petició «Crear cafè sense token → 401» ha d'estar en No Auth explícit, i la de «Crear cafè com a client → 403» en Bearer amb {{token}} (el de la Marta, rol client). Si totes dues hereten el mateix, una de les dues no prova el que diu que prova.

Postman també admet el flux OAuth 2.0 complet de 04-03: a Auth Type → OAuth 2.0 pots configurar Authorization Code amb PKCE, i Postman obre el navegador, fa l'intercanvi i desa el token. És la manera correcta de provar la integració de CataBox, i de comprovar de debò que un token amb només l'àmbit cafes.llegir rep 403 permisos_insuficients en intentar POST /v1/comandes.

Cada petició, carpeta i col·lecció té dos scripts en JavaScript: Pre-request (abans d'enviar) i Post-response (en rebre; en versions anteriors de Postman es deia «Tests»). S'executen en cascada: primer el de la col·lecció, després el de la carpeta i finalment el de la petició.

L'ús més útil del pre-request a la nostra API és renovar el token si ha caducat, perquè la col·lecció funcioni encara que faci dues hores que no la toques. A l'script pre-request de la col·lecció:

Punts que convé entendre d'aquest script:

• pm.sendRequest és asíncron amb callback. Postman espera que acabi abans d'enviar la petició principal, però qualsevol pm.environment.set que facis fora del callback s'executarà abans d'hora.
• El marge d'un minut evita la cursa clàssica: el token és vàlid quan l'script ho comprova i ha caducat quan arriba al servidor.
• Llançar un Error atura l'execució amb un missatge clar en lloc de deixar-te investigant per què tot retorna 401.
• console.log escriu a la Postman Console (Ctrl/Cmd + Alt + C), que a més mostra la petició HTTP exacta que s'ha enviat, capçaleres incloses. És l'eina de depuració número u i gairebé ningú no l'obre.

Aquí és on la col·lecció deixa de ser documentació i es converteix en una prova. L'API és pm.test(nom, funcio), i a dins es fa servir pm.expect, que és Chai.

Post-response de POST /v1/cafes:

Post-response de GET /v1/cafes, on el que es comprova és la forma de la col·lecció i la paginació de 02-06:

I l'error esperat de la carpeta 99, tan important com el camí feliç:

L'encadenat és el que converteix una llista de peticions en un recorregut. La tècnica és sempre la mateixa: una petició desa un valor en una variable, la següent el consumeix.

Al post-response de POST /v1/cafes:

Ara PATCH {{urlBase}}/cafes/{{cafeId}} amb If-Match: {{cafeEtag}} funciona sense tocar res, i el DELETE posterior també. Detall important: després del PATCH, l'ETag canvia (la versió ha pujat), així que el post-response del PATCH l'ha de tornar a desar, o el DELETE rebrà el 412 conflicte_versio de 04-06. És exactament el mateix error que cometria un client real, i descobrir-lo aquí és barat.

Aquest és el recorregut complet que executa la col·lecció:

L'última petició és la que gairebé tothom oblida: netejar el que s'ha creat. Sense ella, cada execució deixa un cafè nou a la base de dades i la col·lecció deixa de ser repetible.

Hi ha una alternativa a l'ordre fix que convé conèixer: postman.setNextRequest('nom de la petició') permet saltar en l'execució del runner, per exemple per ometre la resta d'una carpeta si l'inici de sessió ha fallat. Fes-ho servir amb moderació: col·leccions amb salts per tot arreu són il·legibles.

POST /v1/comandes exigeix Idempotency-Key (02-03 i 04-01). Si l'escrius fixa, el segon enviament retornarà la mateixa resposta que el primer en lloc de crear una comanda nova, que és precisament el que la capçalera promet. I si canvies el cos mantenint la clau, rebràs 409 clau_idempotencia_reutilitzada.

Postman té variables dinàmiques incorporades: n'hi ha prou amb posar {{$guid}} com a valor de la capçalera. Però convé generar-la al pre-request per poder reutilitzar el mateix valor a la prova de reintent:

I una segona petició idèntica, «Crear comanda (reintent)», que no regenera la clau i comprova el contracte d'idempotència:

Altres variables dinàmiques útils: {{$timestamp}} (segons Unix), {{$randomInt}}, {{$isoTimestamp}}, {{$randomEmail}}, {{$randomFullName}}. Serveixen per crear clients de prova sense col·lisions de correu.

Comprovar propietat a propietat es torna insostenible. Postman inclou AJV, així que pots validar la resposta completa contra un JSON Schema:

additionalProperties: true és deliberat: si demà afegim paisTorrefaccio al recurs, la col·lecció no s'ha de trencar. Aquesta és la regla de compatibilitat cap endavant de 02-07 aplicada a les proves.

Duplicar aquests esquemes a mà és tediós i es desincronitza. El correcte és que surtin de l'openapi.yaml, i això és exactament el que farà 05-04 amb les proves de contracte; aquí queda com la solució ràpida i suficient per a l'exploració.

Botó dret sobre la col·lecció → Run collection. El runner executa totes les peticions en ordre i mostra un informe amb les assercions que passen i les que no.

Opcions que importen:

• Iterations: quantes vegades es repeteix la col·lecció sencera (amb un fitxer de dades, una per fila).
• Delay: mil·lisegons entre peticions. Amb el rate limiting de 04-04 actiu, un runner sense delay pot menjar-se la quota i provocar 429 a mitja execució. 50-100 ms sol bastar.
• Keep variable values: si es persisteixen els valors que van escriure els scripts. Activa'l mentre depures, desactiva'l per comprovar que la col·lecció funciona des de zero.
• Run manually / Automatically: l'execució pas a pas és utilíssima per depurar un encadenat trencat.

Per provar diversos cafès sense duplicar peticions, el runner accepta un fitxer de dades; cada fila és una iteració i les seves columnes es converteixen en variables.

postman/dades-cafes.csv:

El cos de la petició fa servir les columnes com a variables, i observa el detall de les cometes: {{preuEuros}} va sense cometes perquè és un número, i {{nom}} amb elles perquè és text.

La columna esperat permet que una sola petició validi casos vàlids i invàlids:

Això prova de cop la validació amb Zod de 03-04 i el format d'error de 03-07, amb cinc línies de CSV en lloc de cinc peticions.

Newman és l'executor de col·leccions per línia d'ordres. És la peça que fa que tot l'anterior serveixi per a alguna cosa més que per a tu.

Exporta primer els fitxers (botó dret → Export, format Collection v2.1) a la carpeta postman/ del repositori:

I executa:

El punt clau per a 05-05: Newman retorna un codi de sortida diferent de zero si alguna asserció falla. Això és tot el que necessita una canalització de CI per bloquejar un desplegament.

Afegeix-lo com a script al package.json:

I newman amb newman-reporter-htmlextra van a devDependencies.

No cal crear les peticions a mà si ja tens el contracte. Import → File → openapi.yaml genera una col·lecció completa amb totes les rutes, paràmetres, cossos d'exemple i carpetes per tag.

Avantatges i inconvenients, perquè no és màgia:

• A favor: cobertura instantània de tots els endpoints, cossos preemplenats amb els example de l'especificació, i una comprovació indirecta que l'openapi.yaml descriu el que creus.
• En contra: no porta scripts, ni encadenat, ni assercions —el que dona valor a la col·lecció—, i reimportar sobreviu malament: Postman crea una col·lecció nova en lloc de fusionar, i perds els teus scripts.

Estratègia pràctica: importa una vegada per tenir l'esquelet, afegeix-hi al damunt scripts i encadenat, i a partir d'aquí mantén la col·lecció a mà. Quan el contracte afegeixi un endpoint nou, s'importa a una col·lecció temporal i es copia la petició que falti. La sincronització de debò entre contracte i implementació no es resol aquí: es resol amb les proves de contracte de 05-04.

Postman genera documentació navegable a partir de la col·lecció: descripcions en Markdown de cada petició i carpeta, paràmetres, i exemples de codi en curl, JavaScript, Python o Go generats automàticament.

Dos hàbits que multipliquen el seu valor:

1. Desar exemples de resposta. A cada petició, botó «Save as Example» després d'una resposta bona. Desa almenys el cas d'èxit i un d'error per endpoint. Els exemples són el que es veu a la documentació i, a més, el que serveix al servidor mock de l'apartat següent.
2. Escriure la descripció de cada carpeta explicant quin rol cal, quines precondicions té i quins errors esperar. És documentació que viu on es fa servir.

Formes de compartir, de menys a més compromesa: exportar el JSON i posar-lo al repositori (la que recomanem, perquè es revisa en pull requests i no depèn de comptes); publicar la documentació com a enllaç públic; o fer servir els workspaces d'equip amb sincronització al núvol, que són còmodes però impliquen que el contingut de les teves col·leccions viu en un servidor de tercers —revisa-ho amb seguretat abans de posar-hi una API interna—.

Per a consumidors externs com CataBox, la documentació de Postman és una opció, però el destí natural és el portal de desenvolupador de 05-06, alimentat per l'openapi.yaml de 05-02.

Postman pot aixecar una URL pública que respon amb els exemples desats de la teva col·lecció. Serveix perquè l'equip de la SPA comenci a maquetar la pantalla del catàleg abans que existeixi l'endpoint.

Es crea en tres clics i té dos límits importants: respon exemples fixos, sense lògica —el filtre ?torrefaccio=clar no filtra res—, i depèn del núvol de Postman.

És una de diverses opcions, i no la millor si ja tens contracte: Prism genera el mock directament des d'openapi.yaml, sense exemples per mantenir a part. Ho veurem a fons a 05-04, juntament amb msw i nock.

• Escriure la URL completa a cada petició. El dia que apareix un entorn de preproducció s'han d'editar quaranta peticions. {{urlBase}} des de la primera, sempre.
• Enganxar el token a mà. Caduca en una hora i acabes amb tokens a la col·lecció exportada, és a dir, al repositori. El token s'obté amb l'inici de sessió i es desa amb un script.
• Exportar l'entorn amb secrets a dins. Marca les variables sensibles com a secret, revisa el fitxer abans de commitejar i afegeix postman/*.local.json al .gitignore.
• Assercions que només comproven l'estat. pm.response.to.have.status(200) passa encara que l'API retorni un array buit perquè el filtre s'ha ignorat. Comprova també la forma i el contingut.
• Oblidar la neteja. Cada execució deixa dades. Acaba cada carpeta amb el DELETE del que ha creat, o sembra la base de dades abans amb npm run bd:reiniciar.
• Confondre variables d'entorn amb variables de col·lecció. Si urlBase és a la col·lecció, el desplegable d'entorns no fa res i acabes apuntant sempre al mateix lloc.
• Executar el runner sense delay contra un entorn amb rate limiting. Fallades aleatòries 429 que semblen bugs de l'API i no ho són. --delay-request 100, o una quota específica per al client de CI (04-04).
• Content-Type: application/json al PATCH. La nostra API respon 415 format_no_suportat amb Accept-Patch. El valor correcte és application/merge-patch+json.
• No obrir la Postman Console. Allà es veu la petició literal enviada, amb les variables ja substituïdes. La majoria dels «no entenc què passa» es resolen en deu segons mirant-la.
• Consell: anomena les peticions pel que proven, no pel mètode. «Crear cafè com a client → 403» diu molt més que «POST cafes 2».
• Consell: posa la col·lecció al mateix repositori que l'API. Així el pull request que canvia un endpoint canvia també la seva petició, i la revisió detecta les incoherències.

Construeix la carpeta 99 Errors esperats de la col·lecció «Botiga Aroma v1» amb cinc peticions que verifiquin el catàleg de 02-04, i escriu-ne les assercions. Els casos: cafè inexistent (404 cafe_no_trobat), paràmetre de consulta invàlid (400 parametre_invalid), creació sense token (401 no_autenticat amb WWW-Authenticate), creació amb rol client (403 permisos_insuficients) i PUT /v1/cafes (405 metode_no_permes amb Allow).

Indica per a cadascuna quina configuració d'Authorization necessita i escriu l'script post-response d'almenys tres d'elles.

Crea una carpeta 10 Recorregut de compra que executi, en ordre i sense intervenció manual: iniciar sessió com la Marta → llistar cafès (desant l'id del primer amb estoc disponible) → crear comanda amb Idempotency-Key generada → pagar la comanda → consultar la comanda i comprovar que el seu estat és pagat.

Escriu els scripts necessaris i explica quines variables es passen entre peticions i en quin àmbit les desaries.

Prepara l'execució de la col·lecció a la terminal perquè serveixi com a porta de qualitat abans d'un desplegament: un fitxer de dades amb almenys dos casos vàlids i dos d'invàlids de creació de cafè, l'ordre de Newman que l'executa contra l'entorn de proves injectant la contrasenya sense escriure-la a cap fitxer, i l'script del package.json. Explica com sabrà el sistema de CI si ha de bloquejar el desplegament.

Configuració d'autenticació per petició:

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

Petició 4 — POST {{urlBase}}/cafes amb el token de la Marta (rol client):

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

Àmbits triats: totes les variables del recorregut van a pm.collectionVariables, no a pm.environment. Motiu: són valors efímers d'una execució concreta i no han d'embrutar el fitxer d'entorn que es comparteix. El token és l'excepció: va a l'entorn perquè el comparteixen totes les carpetes i el gestiona el pre-request de la col·lecció.

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

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

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

Cos i post-response:

Petició 4 — POST {{urlBase}}/comandes/{{comandaId}}/pagament amb Idempotency-Key: {{$guid}}:

Petició 5 — GET {{urlBase}}/comandes/{{comandaId}}:

Variables que viatgen: token (entorn) → totes; clientId i cafeId (col·lecció) → petició 3; comandaId (col·lecció) → peticions 4 i 5; clauIdempotencia (col·lecció) → petició 3.

Fitxer postman/dades-cafes.csv:

Post-response que cobreix tots dos casos:

Ordre amb el secret injectat des de fora:

--env-var sobreescriu el valor del fitxer d'entorn. Així el fitxer versionat pot tenir clauClient buida i el valor real arriba d'una variable d'entorn que a CI prové del gestor de secrets (05-05), mai del repositori.

Script al package.json:

Com bloqueja el desplegament. Newman surt amb codi 0 si totes les assercions passen i amb un codi diferent de zero si alguna falla o hi ha un error de xarxa. Qualsevol sistema de CI interpreta un codi de sortida diferent de zero com a pas fallit i atura la canalització. A més, l'informe junit permet que la interfície mostri exactament quina asserció ha fallat, sense haver de llegir el log. Si es vol que la fallada sigui immediata en lloc d'executar tota la col·lecció, s'hi afegeix --bail.

Has convertit l'exploració manual en un artefacte. La col·lecció «Botiga Aroma v1» ja no és una llista d'URL: té carpetes per recurs que reflecteixen el contracte de 02-02, entorns que permeten apuntar a local, proves o producció sense editar ni una petició, un fre de mà que impedeix escriure a producció per accident, i un pre-request que renova el token de l'inici de sessió de 03-06 abans que caduqui, sense que ningú enganxi credencials a mà.

Damunt d'aquesta base hi has posat el que la converteix en una prova: assercions que verifiquen el 201 i el seu Location, la forma {dades, total} de les col·leccions, que els filtres de 02-06 filtrin de debò, que el preu surti en euros i no en cèntims, que els errors del catàleg de 02-04 arribin amb el seu codi exacte i sense tracaId als 4xx, i esquemes JSON validats amb AJV que toleren camps nous. Has encadenat un recorregut complet de compra passant l'id i l'ETag d'una petició a la següent, has generat una Idempotency-Key per execució per provar el reintent de 02-03, i has multiplicat els casos amb un fitxer CSV en què cada fila declara el codi que espera. I amb Newman tot això s'executa des de la terminal, amb un codi de sortida que basta per bloquejar un desplegament: els fitxers nous del projecte són postman/botiga-aroma-v1.postman_collection.json, postman/local.postman_environment.json, postman/proves.postman_environment.json i postman/dades-cafes.csv, amb newman a devDependencies i els scripts proves:api i proves:fum al package.json.

Queda un cap solt i és l'important: la col·lecció és una segona descripció de l'API, escrita a mà, que pot desviar-se de la real sense que ningú se n'assabenti. Ja tenim una descripció millor —l'openapi.yaml que arrosseguem des de 02-08— però està a mitges: un sol endpoint, sense esquemes complets, sense seguretat declarada i sense publicar. A 05-02, Swagger i OpenAPI per a documentació, l'acabem: l'anatomia completa del document secció a secció, components amb esquemes, paràmetres i respostes reutilitzables, els securitySchemes amb els àmbits OAuth de 04-03, la diferència entre escriure'l a mà i generar-lo des del codi, Swagger UI servit a /docs dins del mateix projecte, la validació amb swagger-cli i les regles de Spectral de 04-01, i la generació de clients TypeScript per a la SPA i per a l'Aroma Mòbil a partir del contracte.