API request collection as API product artifact

En el Radar compartido: Trial (valoración de la edición aportada).

Cómo funciona

Las colecciones agrupan solicitudes, datos y comprobaciones. Herramientas como Bruno permiten almacenarlas en Git y ejecutarlas desde CI junto con la versión de la API.

Ejemplo de uso

Un recorrido obtiene un token de pruebas, crea un pedido, guarda su identificador y comprueba el estado al consultarlo. La pipeline ejecuta el recorrido en un entorno desechable.

Qué contiene una buena colección

Elemento	Propósito
Autenticación	Obtener un token de pruebas y reutilizarlo
Recorridos de negocio	Secuencias reales: solicitar → consultar estado → aprobar → desembolsar
Casos de error	Validación, permisos, recursos inexistentes, idempotencia
Entornos	Local, staging y sandbox de socios, sin secretos en el repositorio
Aserciones	Códigos, esquema y valores clave de la respuesta
Documentación	Descripción de cada petición y de su propósito

Ejemplo de petición en Bruno

meta {
  name: Crear solicitud
  type: http
  seq: 2
}

post {
  url: {{baseUrl}}/v1/solicitudes
  body: json
  auth: bearer
}

auth:bearer {
  token: {{token}}
}

headers {
  Idempotency-Key: {{$randomUUID}}
}

body:json {
  { "documento": "1020345678", "monto": 1500000, "plazo": 12 }
}

script:post-response {
  bru.setVar("solicitudId", res.body.id);
}

tests {
  test("responde 202", () => expect(res.status).to.equal(202));
  test("devuelve id", () => expect(res.body.id).to.be.a("string"));
}

Cada petición es un archivo de texto en el repositorio de la API: se revisa en el mismo PR que el cambio del endpoint.

Ejecución en CI

npm install -g @usebruno/cli
bru run colecciones/originacion --env staging --reporter-junit resultados.xml

Ejecutar la colección contra un entorno efímero en cada PR convierte la documentación en una prueba: si un ejemplo deja de funcionar, el pipeline falla.

Formatos y herramientas

Herramienta / formato	Almacenamiento	Ejecución en CI
Bruno	Archivos en Git	bru run
Postman	Nube (exportable a JSON)	Newman / Postman CLI
Hoppscotch	Nube o autoalojado	hopp test
Archivos .http	Git (IDE: IntelliJ, VS Code)	Clientes de línea de comandos

Como producto para socios

Publica la colección junto a la especificación OpenAPI y un entorno sandbox. Para integradores externos (comercios, socios de originación), una colección que funciona en minutos reduce mucho el tiempo de integración y las consultas al equipo. Mide el tiempo hasta la primera llamada exitosa de un socio nuevo.

Criterios de implementación

Cubrir escenarios relevantes y limpiar datos generados. OpenAPI documenta el contrato; la colección aporta una experiencia guiada que debe verificarse en cada release.