Manual Operativo · Equipo Consumidor

Guía integral y paso a paso para el aprovisionamiento, consumo, inyección de datos de prueba y monitoreo de APIs mediante ambientes efímeros (Mocks) en QA.

Para desarrolladores y equipos consumidores de APIs · Lectura técnica completa

🎥 Cápsulas Ágiles: Todo sobre Ambientes Efímeros

Tenemos para ti cuatro valiosas cápsulas en video con información clara y concisa sobre cada tema: definición y beneficios de los ambientes efímeros, cómo utilizarlos, cómo consumirlos y escenarios definidos en el contrato. Están diseñadas para que las revises rápidamente y con agilidad, facilitando la adopción de esta práctica en tu equipo:

1. ¿Qué es el Reúso de APIs basado en Ambientes Efímeros y para quiénes aplica?

El Reúso de APIs es una práctica mediante la cual, a través de la ejecución de un pipeline operativo automatizado desde Kaizen / Azure DevOps, se aprovisionan bajo demanda en los ambientes de QA los elementos necesarios (infraestructura en AWS, herramienta de simulación Prism Mock y contrato OpenAPI con examples) para simular una API. Su objetivo es entregar respuestas controladas y exitosas que permitan ejecutar satisfactoriamente las pruebas funcionales (E2E) y pruebas de performance cuando el backend real de QA presenta impedimentos.

¿Para quiénes aplica?

Aplica para todos los equipos que sean consumidores de APIs internas, que presenten inconvenientes para obtener respuestas exitosas (peticiones HTTP 200) desde el backend real de QA y que cumplan con los requisitos del modelo.

✅ Los 5 Requisitos Obligatorios para aplicar el Modelo de Reúso

• 1. API habilitada para ambientes efímeros: Antes de consumir el mock, verifica que la API ya se encuentre habilitada dentro del modelo siguiendo el paso a paso de la Sección 2 de esta guía. En caso de que aún no esté habilitada, solicítalo al equipo productor dueño de la API.
• 2. Existencia en Producción y Suscripción Activa: La API ya debe encontrarse desplegada en ambiente productivo (PDN) y como mínimo debe existir un consumidor suscrito para la API que se desea mockear. Debes realizar el proceso normal de reúso de APIs (Gobierno de Apis y Servicios - Modelo Reúso); después de que el equipo productor apruebe la suscripción de tu aplicación (APP-Name), podrás realizar el consumo al ambiente efímero.
• 3. Paridad estricta de versiones (QA == PDN): El contrato de la API en el ambiente de QA debe encontrarse en la misma versión que está desplegada en ambiente productivo (master / trunk), sin alteraciones intermedias.
• 4. Impedimento real en QA: La API que se requiere mockear debe presentar inconvenientes comprobables en el ambiente de QA (problemas de conexión, integridad de información en Base de Datos, casuísticas de negocio específicas difíciles de reproducir, entre otros).
• 5. No aplica para el primer paso a Producción (PDN) de una solución nueva: Si como consumidor estás desarrollando una nueva herramienta, experiencia o servicio y vas a realizar tu primer paso a PDN, ten en cuenta que este proceso NO puede certificarse utilizando ambientes efímeros.

2. ¿Cómo identificar si una API tiene Ambientes Efímeros habilitados?

Antes de aprovisionar un mock, puedes verificar fácilmente si la API que necesitas consumir ya cuenta con la capacidad de ambientes efímeros habilitada:

2.1. Consulta en el API Portal QA (APIs en el Modelo MCI)

Las APIs desplegadas en el Modelo MCI que ya cuentan con ambientes efímeros habilitados se identifican mediante una etiqueta visual directamente en el API Portal QA. Sigue estos 3 pasos:

Ingresa a DEV y QA

Ingresa al API Portal QA y haz clic en el botón DEV y QA.

Filtra por ambiente Certificación

En el catálogo de productos API, ubica en la esquina superior derecha el Filtro por ambiente, selecciona Certificación (también puedes apoyarte en el Filtro por flujo) y haz clic en Conocer más sobre la API que deseas consultar.

Verifica la etiqueta de Ambientes Efímeros

En la vista de detalle de la API, verifica que aparezca en la parte inferior el recuadro con el ícono amarillo:

Ambientes efímeros: Esta API permite crear un mock temporal para agilizar pruebas en QA

Además, allí mismo podrás confirmar la Versión desplegada en Certificación y los datos del Equipo productor.

2.2. Consulta temporal en Excel (APIs en el Modelo Federado - MF)

3. Arquitectura y Motor de Simulación (Prism Mock)

¿Qué herramienta se usa para el mock de APIs?

El motor utilizado para la simulación es Stoplight Prism Mock, una herramienta de código abierto de alto desempeño que simula el comportamiento de las APIs a partir de los esquemas (schemas) y ejemplos (examples) definidos en contratos OpenAPI v3.

• Mocking basado en contratos: Genera respuestas fieles a los esquemas y ejemplos proporcionados en el archivo OpenAPI (.yaml).
• Validación estricta de solicitudes ([VALIDATOR]): Valida que las cabeceras, parámetros y cuerpo (body) de las peticiones entrantes cumplan con el contrato de la API.
• Respuestas estáticas o dinámicas ([NEGOTIATOR]): Permite responder con los ejemplos predefinidos en el contrato o evaluar dinámicamente ejemplos inyectados según los datos enviados en la solicitud.
• Simulación de códigos de error: Permite devolver errores controlados (como códigos HTTP 400, 404 o 500) según los escenarios configurados.

4. Preparación Previa y Estrategia de Datos de Prueba (Examples)

Insumos requeridos para configurar el Mock

Antes de ejecutar el pipeline en Kaizen, ten a la mano la siguiente información técnica:

• Código de Aplicación (APP-Name): Nombre de tu aplicación suscrita a la API en API Connect.
• Repositorio del contrato de la API: Nombre del repositorio en Azure DevOps donde reside el contrato (si es un monorepo, usa el formato monorepo/componente).
• Nombre del archivo YAML: Nombre exacto del archivo .yaml del contrato de la API (siguiendo el patrón nombre-api_version.yaml).
• (Opcional) Datos de prueba personalizados: Repositorio y nombre del archivo JSON de examples propios o Números de documento reservados con EMMA-TDM.

Los examples son pares de solicitudes (request) y respuestas (response) que definen cómo debe responder la API ante cada casuística de prueba. Puedes trabajar con 3 fuentes de examples:

{
  // Parámetro 'endpoints' obligatorio (Array)
  // Se definen todos los paths de la API a los cuales se les agregará ejemplos.
  "endpoints": [
    {
      // Path exacto tal como viene en el contrato de la API
      "path": "/vehicle/{licensePlate}/cities/{city}",
      "method": "GET",

      // Array con la lista de ejemplos para este endpoint
      "examples": [
        {
          "name": "consulta-exitosa-de-informacion-de-vehiculo",
          "statusCode": 200,

          // Obligatorio si el path tiene parámetros entre {}
          "pathParameters": [
            { "name": "licensePlate", "value": "MTX875" },
            { "name": "city", "value": "19001" }
          ],

          // Parámetros de Query (los que van después de ?)
          "queryParameters": [
            { "name": "document-type", "value": "FS001" },
            { "name": "document-number", "value": "1021998446" }
          ],

          // Request body en JSON (opcional si la petición lleva cuerpo)
          "requestBody": {},

          // Response body completo esperado para el ejemplo
          "responseBody": {
            "status": "SUCCESS",
            "data": {
              "plate": "MTX875",
              "registeredCity": "Popayán",
              "vehicleType": "AUTOMOBILE"
            }
          }
        }
      ]
    }
  ]
}

Opción C: Generar examples automáticamente con data solicitada a EMMA - TDM

Si gestionaste reserva de datos de prueba con el equipo de EMMA – TDM, el pipeline puede construir automáticamente los examples a partir de los números de documento entregados:

1. Solicitud previa a EMMA – TDM: Contacta al equipo de EMMA – TDM proporcionando el número de solicitud de data o ID de release, junto con el listado de APIs requeridas.
2. Uso de documentos originales: Ingresa en el pipeline el número de documento exacto entregado por EMMA – TDM.
3. Validación en el stage Generate Examples or API File:
   • Chulo verde El example fue generado correctamente para al menos una operación.
   • X roja No se logró generar el example para ese documento en alguna operación.

 

APIs y operaciones actualmente habilitadas para integración directa con EMMA – TDM:

API / Dominio	Operaciones Soportadas
Customer Personal Data	retrieve-basic-information, retrieve-detail-information
Customer Contact	retrieve-contact-information, customers/contact-information-by-identification, customers/contact-information-by-key
Customer Regulatory Compliance Information	control-list-inquiry
Notifications Subscription	retrieveCustomer
Customer Accounts – Accounts	retrieve-multiple-accounts, retrieve-accounts-by-customer-id
Customer Accounts – Balances	retrieve-account-balances, retrieve-accounts-balances-by-customer-id
Deposit Account Information – Accounts	accounts/retrieve-detail-information
Deposit Account Transactions Information	retrieve-account-transactions
Deposit Account Details – Participants	participants/retrieve-list, belonging
Deposit Account Details – Information	accounts/retrieve-basic, accounts/retrieve-account-plan-characteristics, accounts/retrieve-details
Customer Information – Keys	customers/keys-by-identification, customers/retrieve-information-by-key
Loan Information	loanDetails, retrieveCustomerLoans

Nota: A medida que se integren nuevas APIs a este proceso, serán comunicadas oportunamente por este medio.

5. Aprovisionamiento del Mock (Ejecución del Pipeline en Kaizen)

¿Quiénes pueden ejecutar el pipeline operativo?

El pipeline operativo puede ser ejecutado por cualquier persona que tenga acceso a la organización de Azure DevOps (Vicepresidencia Servicios de Tecnología) y cuente con permisos sobre el repositorio NU0007001_Reuso_Apis_Create_Examples_DOP (en caso de no contar con permisos, solicítalos al movilizador de tu equipo).

Paso a paso para diligenciar la plantilla en Kaizen

Ingresa a la plantilla oficial: Kaizen - API Reuse Create Example y completa los siguientes parámetros:

Application Code (APP-Name)

Ingresa el APP-Name de tu aplicación suscrita a la API en API Connect. Es indispensable para que el balanceador del mock identifique al consumidor que realiza la petición.

API Repository Name y API File Name

Ingresa el nombre del repositorio donde se encuentra el contrato de la API (si es monorepo, usa monorepo/componente) y el nombre exacto del archivo .yaml.

API File Branch

Rama donde reside el contrato. Como consumidor trabajas sobre la versión productiva (trunk o master), por lo que debes dejar este campo vacío.

Test Type (Tipo de Prueba)

Elige el modo de configuración de Prism según el objetivo de tu prueba:

• Modo Funcional (Casos E2E): Evalúa dinámicamente examples del contrato y los inyectados por JSON o EMMA. Permite activar la casilla Enable Mock Logging para depurar trazas en Grafana.
• Modo Performance (Carga y Estrés): Configura Prism en una instancia EC2 multi-core optimizada. No evalúa examples externos ni genera logging para no degradar el rendimiento. Habilita dos campos adicionales:
  • API Delay: Retardo en milisegundos que emula la latencia del backend real.
  • Amount of Threads: Concurrencia máxima calculada en el checklist de Performance.

 

Execution Duration (Duración del Mock en minutos)

Tiempo durante el cual estará aprovisionada la infraestructura. Una vez cumplido este tiempo, la instancia EC2 y las reglas del balanceador se destruirán automáticamente.

 

Uso responsable (FinOps):

Selecciona únicamente los minutos estrictamente necesarios para tus pruebas. Tiempos excesivos generan infraestructura subutilizada y sobrecostos para la organización.

Add Examples from JSON

Si vas a inyectar data propia (solo para pruebas Funcionales), selecciona Yes e ingresa el Examples Repository Name, Examples File Name y Examples File Branch.

 

Add Examples from EMMA

Si cuentas con documentos reservados con EMMA-TDM, selecciona Yes e ingresa los números de documento separados por comas.

 

Reglas de Concurrencia entre Equipos

El pipeline no tiene un límite global de mocks desplegados en simultáneo. Sin embargo, la clave única de despliegue es la combinación APP-Name + API File Name:

• Si dos ejecuciones repiten exactamente ambos campos, solo quedará activo el último despliegue. Es fundamental la comunicación entre equipos que compartan el mismo APP-Name.
• Si necesitas ejecutar pruebas Funcionales y de Performance para la misma API, ejecuta primero el mock funcional y, al terminar, corre el mock de performance.

6. ¿Cómo consumir el Mock en tus pruebas (Funcional y Performance)?

El punto de inyección sigue siendo exactamente el mismo endpoint del API Gateway (IBM API Connect) en QA al cual apuntas tus pruebas habitualmente.

La conmutación entre el backend real de QA y el ambiente efímero ocurre de forma transparente dentro del Gateway cuando envías en las cabeceras (Headers) de tu petición:

Si no envías la cabecera mock: true (o la envías en false), la petición continuará su flujo normal hacia el backend real de QA.

7. Observabilidad en Grafana y Diagnóstico de Errores (Troubleshooting)

7.1. Monitoreo de Infraestructura y Tráfico en Grafana

Para observar en tiempo real el estado y rendimiento de la infraestructura donde corre tu mock, ingresa al tablero oficial:

📊 Observabilidad Modelo Reúso APIs - Pruebas Continuas - Grafana

7.2. ¿Cómo inspeccionar el Log detallado de peticiones? (Enable Mock Logging)

La opción Enable Mock Logging activa el modo trace de Prism en Grafana (exclusivo para tipo de prueba Funcional):

Aplica el filtro por API

En el Dashboard de Grafana, selecciona tu componente en el selector API Name.

 

Ubica el panel inferior de Logs

Desplázate al panel "Log respuesta del mock" al final de la página de Grafana.

 

Inspecciona la negociación de Examples

Despliega el registro para observar el detalle de [HTTP SERVER] y [NEGOTIATOR] evaluando tus datos contra el contrato.

 

Diagnostica fallos con [VALIDATOR]

Si algún campo o header incumple la especificación OpenAPI (por ejemplo, formato UUID incorrecto), el componente [VALIDATOR] te señalará el campo exacto que causó el rechazo.

 

 

7.3. Guía Rápida de Trazabilidad de Errores

• 404 Error 404 Not Found (Diagnóstico con Server Espejo): Cuando una petición llega al balanceador pero no coincide con ninguna regla activa, el Server Espejo devuelve un JSON reflejando tu petición. Revisa:

  • Que el app-name del JSON coincida exactamente con el APP-Name ingresado en Kaizen.
  • Que la versión en la URL (ej. /1.0.0/...) coincida con la rama productiva (paridad QA vs PDN).

  • 

   

• 504 Error 504 Gateway Time-out (Ventana Horaria): Confirma en la tarea Deploy Mock Infrastructure del pipeline el rango horario activo ("El Mock estará activo entre..."). Peticiones antes o después de esa ventana devolverán 504. 

  

   

• 500/502 Errores 500 / 502 Persistentes: Si estás dentro del horario activo y persisten estos errores, escala al Primer Nivel de Soporte (equipo productor) para validar la integración de su backend.

• TLS Error de Conexión TLS (Socket disconnected): Suele originarse por falta de permisos en el API Gateway. Contacta al analista de ciberseguridad asignado a tu ECV para validar los grupos de seguridad del gateway. 

  

   

8. Niveles de Soporte

Si presentas algún inconveniente durante el proceso, sigue este esquema escalonado de atención:

• Primer nivel: Equipo Productor Busca apoyo en el equipo dueño de la API para validar suscripciones, paridad de versiones QA/PDN o ajustes en el contrato OpenAPI.
• Segundo nivel: Célula QualityForce (PO: Sara Cardona López) vía IntegrApp Si el primer nivel no logra resolverlo o requieres acompañamiento especializado sobre la práctica de ambientes efímeros, radica una solicitud formal en IntegrApp (APB28560) siguiendo el instructivo que se detalla a continuación.
• Tercer nivel: Tableros de Pruebas DOR Crea una solicitud de asesoría especializada según la naturaleza técnica:
  • Infraestructura o Performance: DOR EQU0669 - Prácticas de Performance.
  • Pruebas funcionales o Examples adicionales: DOR EQU0668 - Pruebas Continuas.

¿Cómo radicar una solicitud a QualityForce en IntegrApp?

Todas las solicitudes de acompañamiento a la célula QualityForce sobre ambientes efímeros se gestionan formalmente a través de IntegrApp (APB28560):

Ingresa a IntegrApp

Ingresa a IntegrApp (APB28560) y, en la tarjeta Nueva solicitud, haz clic en Realiza tu solicitud.

 

Selecciona Asesorías y configuraciones

En la opción Asesorías y configuraciones, haz clic en Solicítala aquí.

 

Realiza el Autodiagnóstico

Antes de continuar, valida si tu duda se resuelve en esta guía o con tu equipo, y haz clic en Acepto.

 

Diligencia el Formulario

Completa los campos con los siguientes valores estándar:

• Tipo solicitud: Asesoría
• Plataforma/Componente: API
• Stack: APIC
• Infraestructura de despliegue: AWS (MCI) o AWS según corresponda.
• Código/Nombre del Componente: Nombre de la API a consultar.
• Ambiente: Pruebas (QA)
• Solicitud: Selecciona cualquiera de las opciones habilitadas:
  • Asesoría en implementación de ambientes efímeros
  • Asesoría en la revisión de la implementación de ambientes efímeros
• Fuentes consultadas, Detalle y Adjuntos: Describe tu caso y adjunta evidencias (logs de pipeline, Server Espejo, Grafana).

 

Envía y consulta en Mis solicitudes

Haz clic en enviar. Podrás consultar el avance de tu caso en cualquier momento desde la sección Mis solicitudes de IntegrApp.

Solo para productores: Si eres dueño o desarrollador de una API y necesitas instrumentar el contrato OpenAPI en IBM API Connect, consulta la Habilita Ambientes Efímeros para tus consumidores - Guía del Productor.