Emulador QR Prisma

Un Prisma Gateway QR v27 de bolsillo, con su billetera, que corre en la máquina del desarrollador. Permite probar el gateway sin Prisma y provocar a pedido las fallas que en producción casi nunca se ven. Actualizado el 2026-11-15 contra el módulo prisma-emulator, tools\local-sim y el cockpit de la consola.

1. Qué es

El emulador es el módulo prisma-emulator del repositorio (Spring Boot, sin base de datos: todo el estado vive en memoria). Hace dos papeles a la vez:

  • Prisma emulado: atiende la API que el gateway le llama (crear, completar y cancelar intención, consultar pagos, anulaciones y devoluciones, anulación y devolución forzadas) con los códigos de estado y los cuerpos de error de la especificación v27.
  • Billetera emulada: escanea el QR, envía los BINs al gateway, espera la oferta de planes, elige uno, paga y notifica el pago al gateway con la clave que el gateway le emitió.

Existe por dos motivos. Primero, el gateway debe poder probarse de punta a punta (criterio AC-30 de ACCEPTANCE.md) sin depender de Prisma ni de una billetera real. Segundo, los casos difíciles (la notificación que no llega, el cobro tardío, el segundo cobro, la respuesta que se pierde después de que Prisma hizo el trabajo) hay que poder reproducirlos a demanda y de forma determinística.

Se usa de tres formas:

FormaQuién la usaDónde se explica
En proceso, como bibliotecaLos tests del gateway (*IT, end-to-end), que la arrancan desde el jar planoRUNBOOK sección 7
Simulación local con sim.ps1Un desarrollador que quiere gateway y emulador sin POSsección 7.2
Con el cockpit (banco de pruebas)Desarrollo y QA, con 15 casos catalogadossección 7.3

El emulador implementa lo que dice v27. Donde v27 calla (qué responde una segunda intención completa, un cancelar después de pagar, una anulación forzada repetida) toma la lectura más estricta y lo deja como una opción configurable. Eso está documentado en los comentarios del código y en el modelo de seguridad y los modos estrictos.

2. Arquitectura y secuencia

Tres procesos locales, todos en 127.0.0.1. El POS (o RouterQR) habla con el gateway por la API del POS; el gateway habla con el emulador como si fuera Prisma; y el emulador, en su papel de billetera, devuelve las llamadas al gateway por el listener de callbacks.

Arquitectura de la simulación local El POS o RouterQR llama al gateway en el puerto 8090. El gateway llama al emulador en el puerto 9090. La billetera emulada, dentro del emulador, llama a los callbacks del gateway en el puerto 8443. La consola de administración usa el puerto 8091. POS / RouterQR o el cockpit, o sim.ps1 trxid, trxpago, trxes, trxanulacion Gateway (perfil local) POS API :8090 /api/* Callbacks :8443 /prisma/v1/* (apikey) Admin :8091 consola y cockpit SQL Server: base _SIM desechable, se recrea en cada up Emulador :9090 Prisma emulado API v27 con apikey + inyección de fallas Billetera emulada escenarios (hilos virtuales) BINs, pago, notificación /emulator/* control sin apikey, solo loopback HTTP como Prisma callbacks
Todos los listeners son de loopback. La clave de Prisma y la de los callbacks se generan por corrida (ver seguridad).

Secuencia de un pago aprobado

La billetera emulada no actúa sola: un escenario (POST /emulator/scenarios) la pone en marcha cuando el gateway ya creó la intención. sim.ps1 pay -Outcome y el cockpit lo hacen por usted.

01 / Id del pago 02 / Intención en Prisma 03 / QR fijo de la caja y BINs 04 / Intención completa (reloj de 27 s) 05 / Pago y respuesta al POS POST /api/trxid pos, sucursal, comercio 201 {id} POST /api/trxpago id y totalitem (importe original); el POS espera POST /largeaccounts/intentions cuit, branch, checkout, mcc, original_amount, bins_max_quantity 99 201 intention_id escanea el QR fijo recibe la última intención de esa caja PUT /prisma/v1/intentions/{id} BINs de la billetera; exige la apikey (AC-09) 204 (< 200 ms p95) PUT intentions/complete planes por medio y BIN, terminal, trace y ticket; siempre 1 cuota y medio 112 204 muestra medios y planes el cliente elige y paga POST /prisma/v1/payment amount, installments, status 200 AUTORIZACION_DE_PAGO_APROBADA importe, importe_recdesc, importe_final POS caja del comercio Gateway GatewayPrismaQR Prisma Gateway QR v27 Billetera app del cliente Leyenda solicitud respuesta seguridad asíncrono
Prisma y la billetera son las del emulador: sus llamadas hacia el gateway (BINs y notificación de pago) las dispara un escenario, y las llamadas del gateway hacia Prisma van contra el emulador.

Teclas: ← → cambian de paso, Inicio y Fin saltan al primero y al último, Esc vuelve a la vista completa.

Las reglas de estado que el emulador aplica a cada intención: hay una sola intención viva por cuit/branch/checkout y una nueva reemplaza (SUPERSEDED) a la anterior; la intención completa solo se acepta hasta 27 s después de los BINs y, por defecto, solo si los BINs ya llegaron (si no, responde 404); una billetera no puede pagar una intención cancelada o reemplazada salvo en el escenario explícito de pago tardío.

3. Endpoints

Lado Prisma (el gateway los llama)

Todos exigen la cabecera apikey; con una clave ausente o equivocada responden 403 {"message":"Invalid authentication credentials"} (Prisma responde 403, no 401). Los errores de validación son 400 invalid_request_error con la lista validation_errors, y lo que no existe es 404 not_found_error.

Método y rutaRespuestaQué haceOperación de falla
POST /largeaccounts/intentions201Crea la intención y devuelve intention_id, qr_raw (no es un EMVCo real, sin CRC) y payment_methods_data vacío. Reemplaza a la intención viva del mismo cuit, sucursal y caja.CREATE_INTENTION
PUT /largeaccounts/intentions/complete?cuit&branch&checkout204Recibe los planes del gateway. 404 si no hay intención en estado creado, si faltan los BINs (requireBins) o si pasaron más de 27 s desde ellos.COMPLETE_INTENTION
DELETE /intentions/{id}204Cancela una intención viva. 404 si ya se pagó, cancelló o reemplazó.CANCEL_INTENTION
GET /payments/qr?intention_id=200Estado del pago (approved, rejected, annulled, refunded). 404 si no hay pago.QUERY_PAYMENT
GET /annulments?intention_id=200Estado de la anulación que terminó última; si hay una en curso, responde annulment_in_progress.QUERY_ANNULMENT
GET /refunds?intention_id=200Ídem para devoluciones.QUERY_REFUND
POST /forcedannulments201Inicia la anulación forzada del cobro nombrado por método, establecimiento, traza y ticket. Una segunda sobre el mismo cobro es 400 invalid_param.FORCED_ANNULMENT
POST /forcedrefunds201Ídem para devolución forzada.FORCED_REFUND

Tras una anulación o devolución forzada, y si hay un gateway configurado con notifyReversals activo (por defecto sí), el emulador espera reversalDelay (200 ms) y notifica al gateway.

Llamadas del emulador al gateway (callbacks)

LlamadaCuándo
PUT {callbacks}/intentions/{id}La billetera envía sus BINs. Espera 204.
POST {callbacks}/paymentNotificación del pago, aprobado o rechazado.
POST {callbacks}/annulment y /refundFin de una anulación o devolución forzada.

{callbacks} es la URL base configurada (en la simulación local, el listener 8443 con el prefijo /prisma/v1). Cada llamada lleva la cabecera apikey con la clave que el gateway emitió.

Control (/emulator/..., sin apikey)

Método y rutaQué hace
GET /emulator/health{"status":"UP"}.
POST /emulator/reset204. Olvida intenciones, pedidos registrados y reglas de falla, y vuelve al destino de callbacks de arranque.
PUT /emulator/gatewayIndica adónde van los callbacks. Cuerpo: callbacksUrl, apiKey, opcional notifyReversals.
POST /emulator/scenarios202 con {"id": "..."}. Arranca un escenario de billetera en un hilo virtual.
GET /emulator/scenarios/{id}Traza del escenario: state (RUNNING, DONE, FAILED), detail y los pasos con su estado HTTP.
POST /emulator/faults201. Agrega una regla de falla a la cola.
DELETE /emulator/faults204. Vacía la cola de fallas.
POST /emulator/reversals/{intentionId}/{kind}?approved=trueTermina a mano una anulación o devolución forzada (kind = ANNULMENT o REFUND) y notifica al gateway. Responde {"gatewayStatus": n}.
GET /emulator/requestsLo que recibió el Prisma emulado: instante, método, URI con query, cuerpo y estado de respuesta. No incluye la clave.
GET /emulator/intentions/{id}Fase de la intención y su pedido, su intención completa y su pago.
GET /emulator/catalogLista descrita de escenarios, operaciones y modos de falla. Falla al construirse si un valor del enum no tiene descripción, de modo que no puede quedar desactualizado. La página «Emulador» de la consola la lee.

Cuerpo de un escenario: cuit, branch, checkout (qué QR se escanea) y, opcionales, outcome (por defecto APPROVED), wallet (por defecto bsf), bins, benefitCards, waitForComplete (por defecto true), paymentMethodId, installments (por defecto 1), lateByMillis (por defecto 2000) y cashback. Sin bins la billetera ofrece un solo medio (método 1, banco 22, BIN 450799).

Configuración del emulador

El emulador no tiene archivo de configuración propio: todos los valores por defecto viven en EmulatorProperties y se cambian con propiedades --emulator.* o variables de entorno.

PropiedadPor defectoEfecto
emulator.complete-deadline27 sPlazo para aceptar la intención completa desde los BINs.
emulator.require-binstrueRechaza (404) la intención completa si los BINs no llegaron.
emulator.allow-second-completefalseAcepta una segunda intención completa.
emulator.scenario-complete-timeout30 sCuánto espera un escenario la intención completa del gateway.
emulator.reversal-delay200 msDemora hasta terminar una anulación o devolución forzada.
emulator.gateway.timeout5 sTiempo de lectura de cada callback.
emulator.gateway.notify-reversalstrueNotifica solo el fin de una anulación o devolución.
emulator.reject-duplicate-integrator-idfalseModo estricto: un integrator_intention_id repetido es 422.
emulator.alphanumeric-codes-onlyfalseModo estricto: branch y checkout solo con letras y dígitos.
emulator.dashed-cuit-onlyfalseModo estricto: el CUIT debe escribirse XX-XXXXXXXX-X.

4. Escenarios de la billetera

Son los valores de outcome (enum WalletSimulator.Outcome). La columna «El gateway debe» resume lo que los casos del cockpit comprueban hoy contra el gateway real; los detalles de cada caso están en console\src\cockpit\catalog\cases.ts.

OutcomeQué simulaEl gateway debe
APPROVEDBINs, intención completa, pago aprobado y una notificación.Responder AUTORIZACION_DE_PAGO_APROBADA; pago APPROVED; sin tareas de compensación.
REJECTEDIgual, pero el autorizador de la billetera rechaza el pago.Denegar con el motivo de la billetera; pago REJECTED; sin compensación.
MISSING_BINSLa billetera escanea pero nunca envía los BINs.Al vencer la espera, denegar («no se pudo confirmar»), cancelar la intención en Prisma y pasar el pago a compensación (tarea CANCEL_INTENTION).
MISSING_NOTIFICATIONEl pago se hace, pero la notificación nunca se envía.Preguntar GET /payments/qr y aprobar por consulta. Si esa consulta también falla (503), denegar y pasar a compensación.
DUPLICATE_NOTIFICATIONLa notificación llega dos veces.Aplicarla una sola vez: resultados APPROVED y luego DUPLICATE, un solo cobro registrado.
LATE_NOTIFICATIONLa notificación llega lateByMillis después del pago, posiblemente tras la espera.Si el POS ya recibió «sin venta», compensar el cobro tardío (tareas CANCEL_INTENTION y REVERSE_CHARGE).
LATE_PAYMENT_AFTER_CANCELLa billetera paga una intención que el gateway ya canceló (o que otra venta reemplazó): el cliente queda cobrado.Rechazar los BINs tardíos (NOT_LIVE), compensar el pago (COMPENSATE) y crear CANCEL_INTENTION y REVERSE_CHARGE. Ver la limitación conocida.
APPROVED_AMOUNT_MISMATCHPago aprobado de un plan realmente elegido, pero cobrado un centavo más que el total ofrecido.No aprobarlo: rechazar la notificación (AMOUNT_MISMATCH), denegar al POS, registrar el pago de la billetera y compensar (REVERSE_CHARGE).
APPROVED_UNOFFERED_PLANPago aprobado en una cantidad de cuotas que la oferta nunca incluyó.Igual que el anterior, con motivo UNOFFERED_PLAN.
DOUBLE_CHARGEUn segundo cobro de una intención ya paga, con id de pago propio pero con los números de traza y ticket del primero. Requiere un primer pago aprobado.Conservar la venta (APPROVED). Como los dos cobros no se distinguen, no enviar ninguna anulación forzada: cerrar la reversión como FAILED por seguridad y alertar (tarea REVERSE_CHARGE en COMPENSATION_FAILED).
DOUBLE_CHARGE_OWN_NUMBERSEl mismo segundo cobro, con traza y ticket propios.Anular solo el segundo: un único POST /forcedannulments, reversión COMPLETED, venta intacta.

Anulación y devolución forzadas no son un outcome: las dispara el propio gateway con POST /forcedannulments o /forcedrefunds. El emulador responde 201, y 200 ms después notifica el fin (/annulment o /refund) si notifyReversals está activo. Con POST /emulator/reversals/{id}/{kind}?approved=false se fuerza la variante rechazada. Con esto queda cubierto el conjunto completo de AC-30: aprobación, rechazo, BINs faltantes, notificación faltante, duplicada y tardía, y anulación y devolución forzadas.

5. Inyección de fallas

El emulador mantiene una cola de reglas. Cada llamada a la API de Prisma consume la primera regla cuya operación coincide (o es ANY). Una regla con count mayor que 1 se reutiliza y descuenta uno por llamada. POST /emulator/reset y DELETE /emulator/faults vacían la cola.

Campos de una regla (cuerpo de POST /emulator/faults):

CampoPor defectoSignificado
operationANYCREATE_INTENTION, COMPLETE_INTENTION, CANCEL_INTENTION, QUERY_PAYMENT, FORCED_ANNULMENT, FORCED_REFUND, QUERY_ANNULMENT, QUERY_REFUND o ANY.
modeSTATUSVer la tabla siguiente.
status500Código HTTP para STATUS. (En sim.ps1 el parámetro se llama -HttpStatus.)
delayMillis0Demora para DELAY, TIMEOUT y STALL_AFTER_HEADERS.
count1A cuántas llamadas se aplica.
executeAnywayfalseSolo para STATUS y CONFLICT: la operación se realiza y recién después se contesta la falla.
garbageIdnot-a-numberValor de intention_id para GARBAGE_ID.
ModoLo que ve el gateway
STATUSEl código indicado con un cuerpo JSON pequeño ({"message":"injected failure 503"}). Con executeAnyway, Prisma hizo el trabajo y la respuesta se pierde: resultado desconocido (ADR-002).
DELAYEspera delayMillis y responde normal: un Prisma lento.
TIMEOUTEn el código se comporta igual que DELAY; la diferencia es de intención: usar una demora mayor que el tiempo de lectura del cliente, que ya abandonó cuando llega la respuesta.
CONFLICT409 (también admite executeAnyway).
GARBAGE_IDSolo al crear: 201 con un intention_id que no es un número usable.
STALL_AFTER_HEADERSLa operación se realiza, el estado y las cabeceras salen de inmediato y el cuerpo llega tras delayMillis: lo que un cliente limitado solo por un timeout de cabeceras espera indefinidamente.
RESET_AFTER_REQUESTLa operación se realiza, se anuncia un cuerpo y la conexión se corta tras unos pocos bytes (un servlet no puede enviar un TCP reset; un cuerpo más corto que su Content-Length es lo más parecido).
HUGE_BODYLa operación se realiza y se responde un JSON válido de 2 MiB: una respuesta que nunca debe leerse entera.

Ejemplos

La creación de la intención falla con 503 después de que Prisma la creó (resultado desconocido; es el caso CREATE_INTENTION_503 del cockpit):

$sim = 'tools\local-sim\sim.ps1'
powershell -NoProfile -ExecutionPolicy Bypass -File $sim fault -Operation CREATE_INTENTION -Mode STATUS -HttpStatus 503 -Count 1 -ExecuteAnyway

La consulta de estado del pago falla 100 veces seguidas (casos MISSING_NOTIFICATION_QUERY_PAYMENT_503 y LATE_NOTIFICATION_QUERY_PAYMENT_503):

powershell -NoProfile -ExecutionPolicy Bypass -File $sim fault -Operation QUERY_PAYMENT -Mode STATUS -HttpStatus 503 -Count 100

La intención completa tarda 5 s en contestar, y luego se limpian las fallas:

powershell -NoProfile -ExecutionPolicy Bypass -File $sim fault -Operation COMPLETE_INTENTION -Mode DELAY -DelayMillis 5000
powershell -NoProfile -ExecutionPolicy Bypass -File $sim faults-clear

Lo mismo directamente contra la API de control (cuerpo con status, no HttpStatus):

Invoke-RestMethod -Method Post -Uri http://127.0.0.1:9090/emulator/faults -ContentType application/json `
  -Body '{"operation":"ANY","mode":"RESET_AFTER_REQUEST","count":1}'

La captura siguiente es el caso del cockpit con la falla 503 en COMPLETE_INTENTION: el panel «Requests recibidos» muestra el 503 del emulador y el pago termina en compensación.

Cockpit con una falla 503 inyectada en la intención completa: el pago queda COMPENSATED y el emulador registró el 503
Cockpit: panel manual con una regla COMPLETE_INTENTION / STATUS / 503 inyectada, los pedidos recibidos por el emulador y el recorrido del pago en el gateway (la imagen es alta; desplace dentro del recuadro).

6. Modelo de seguridad

  • Filtro de apikey (ApiKeyFilter). Toda ruta fuera de /emulator/ exige la cabecera apikey; la comparación es de tiempo constante. Una clave faltante o incorrecta responde 403 con Invalid authentication credentials.
  • La API de control no tiene clave. Por eso solo es seguro en loopback: permite arrancar escenarios, inyectar fallas y borrar el estado.
  • Solo loopback. El jar independiente escucha en 127.0.0.1 por defecto (--server.address lo cambia, a su propio riesgo). sim.ps1 fija las direcciones de forma explícita, verifica con Get-NetTCPConnection que ningún proceso escuche en otra interfaz y, si algo escucha afuera, aborta y limpia. El proxy de Vite del cockpit también es de loopback.
  • Claves aleatorias por corrida. sim.ps1 up genera una clave de Prisma y una de callbacks de 64 caracteres, las guarda solo en tools\local-sim\.state\state.json (carpeta con su propio .gitignore) y las pasa a los procesos hijos por variables de entorno, no por la línea de comandos, así que no aparecen en la lista de procesos ni se imprimen. El navegador y el cockpit nunca las ven.
  • Excepción deliberada: la contraseña de la consola. La contraseña del usuario admin que crea up sí se imprime (en up y status) y se guarda en .state\state.json. Protege un entorno local, solo loopback, con una base descartable que se recrea en cada up; mostrarla simplifica la prueba. Es aleatoria por corrida, no está en el repositorio y no viaja por la línea de comandos. No debe copiarse a un entorno real.
  • Sin secretos en el registro. El emulador no guarda la clave al registrar pedidos (es una cabecera, no parte del cuerpo) y enmascara las claves en toString. La clave por defecto que existe en el código es solo para pruebas en proceso: en un uso manual debe fijarse siempre (--emulator.api-key o EMULATOR_APIKEY).
  • Nada se expone. No hay túnel ni tráfico saliente: la URL base de Prisma del gateway es el emulador local.
  • Credenciales de base de datos. No viajan por el emulador (que no usa base). sim.ps1 las lee en silencio de variables de entorno o del bloque gpqr.db (o spring.datasource) de config\application-local.yml, y no las imprime.

Carrera de registro: el pedido se registra después de enviada la respuesta. El filtro anota cada pedido (método, URI, cuerpo, estado) en un bloque finally, cuando el controlador ya produjo la respuesta. Un cliente rápido puede recibir la respuesta antes de que el pedido figure en GET /emulator/requests.

Por eso un test, o un script, que lea los pedidos justo después de una llamada debe esperar por condición hasta que aparezca el pedido esperado, nunca asumirlo ni dormir un tiempo fijo. Es el motivo de la rama fix/emulator-requests-race (PR #24, commit cade9e7: los tests del gateway esperan a que el emulador registre los pedidos antes de afirmar sobre ellos). Los pedidos de /emulator/* no se registran.

7. Cómo ejecutarlo

7.1 Requisitos

  • Java 25 y Maven (el repositorio compila con maven.compiler.release 25; sim.ps1 construye los jars con mvn -q package -DskipTests si faltan).
  • SQL Server accesible en localhost. up elimina y recrea una base desechable GatewayPrismaQR_SIM (el nombre debe cumplir ^[A-Za-z0-9_]+_SIM$, con mayúsculas y minúsculas exactas).
  • Credenciales de la base: en config\application-local.yml o en las variables GPQR_DB_USER y GPQR_DB_PASSWORD. Este documento no las contiene.
  • Node.js y npm, solo para el cockpit (carpeta console\).
  • Windows PowerShell 5.1 o pwsh 7 para sim.ps1.

7.2 Con sim.ps1 (gateway y emulador, sin POS)

Ejecutar desde la raíz del repositorio. Puertos: emulador 9090, callbacks 8443, API del POS 8090, administración 8091, todos en 127.0.0.1.

$sim = 'tools\local-sim\sim.ps1'
powershell -NoProfile -ExecutionPolicy Bypass -File $sim up

up recrea la base, arranca el emulador y el gateway (perfil local), verifica que cada listener sea de loopback, comprueba que Flyway migró la base _SIM y apunta el emulador a los callbacks del gateway. Después crea el usuario ADMIN admin de la consola con una contraseña aleatoria de 20 caracteres (el comando de un solo uso del RUNBOOK, sección 12) y, al final, imprime Console: http://127.0.0.1:5173/admin/ user: admin password: .... La contraseña queda también en .state\state.json y status la vuelve a mostrar. Si ese paso falla, up avisa con la ruta del registro (.state\admin-bootstrap.log) y sigue arriba.

Con esperas cortas, para el cockpit y para probar a mano sin aguardar el vencimiento (la espera del POS baja de 45 s a 15 s):

powershell -NoProfile -ExecutionPolicy Bypass -File $sim up -FastWaits

-FastWaits ajusta gateway.pos.wait.deadline a 15 s (45 s), status-query-lead a 5 s (15 s), caller-read-timeout a 25 s (59 s), gateway.compensation.initial-backoff a 1 s (5 s) y poll-delay a 2 s (10 s). Para reutilizar los jars sin reconstruir: up -NoBuild.

Estado y pago

powershell -NoProfile -ExecutionPolicy Bypass -File $sim status
powershell -NoProfile -ExecutionPolicy Bypass -File $sim trxid
powershell -NoProfile -ExecutionPolicy Bypass -File $sim pay -Id 1 -Amount 100.00 -Outcome APPROVED
powershell -NoProfile -ExecutionPolicy Bypass -File $sim poll -Id 1

status muestra la salud de 9090, 8090, 8091 y 8443, los PID registrados, cada uno marcado ours, gone o mismatch, y el usuario y la contraseña de la consola de esta corrida. trxid pide un id (por defecto comercio ALMACOR-DEMO, sucursal 1, caja 1); use ese id en pay -Id. Con -Outcome, la billetera se juega sola en cuanto el gateway crea la intención.

Escenario a mano

Sin -Outcome, pay espera a que usted juegue la billetera desde otra terminal:

# terminal 1
powershell -NoProfile -ExecutionPolicy Bypass -File $sim pay -Id 2 -Amount 100.00

# terminal 2, mientras trxpago espera
powershell -NoProfile -ExecutionPolicy Bypass -File $sim scenario -Outcome MISSING_NOTIFICATION

Los valores admitidos de -Outcome son los de la sección 4. Por defecto scenario usa el cuit, sucursal y caja del seed de demostración (-Cuit -BranchCode -CheckoutCode lo cambian).

Fallas, pedidos y reinicio

powershell -NoProfile -ExecutionPolicy Bypass -File $sim fault -Operation CANCEL_INTENTION -Mode CONFLICT
powershell -NoProfile -ExecutionPolicy Bypass -File $sim requests
powershell -NoProfile -ExecutionPolicy Bypass -File $sim faults-clear
powershell -NoProfile -ExecutionPolicy Bypass -File $sim reset

requests imprime lo que recibió el Prisma emulado. faults-clear vacía la cola de fallas y reset olvida todo el estado del emulador.

Prueba de humo y apagado

powershell -NoProfile -ExecutionPolicy Bypass -File $sim smoke
powershell -NoProfile -ExecutionPolicy Bypass -File $sim down

smoke ejecuta un pago aprobado, uno rechazado, una anulación (con su repetición idempotente) y una cancelación del cajero durante la espera; imprime una tabla PASS/FAIL y termina con código 1 ante cualquier FAIL. Un reinicio o rechazo de conexión es una fila FAIL, no un volcado de pila.

down detiene exactamente los procesos de .state\state.json, y solo si PID, nombre y hora de inicio (dentro de 2 s) coinciden. Si el PID ahora pertenece a otro proceso, no lo toca: informa estado obsoleto y borra el archivo de estado.

Opcional: seed aplica db\seed\seed-dev.sql (idempotente, solo base de desarrollo) cuando falta el comercio de demostración. cancel -Id N llama a POST /api/trxanulacion.

7.3 Con el cockpit (banco de pruebas)

El cockpit es una página solo para desarrollo de la consola de administración (menú «Banco de pruebas», rol ADMIN) que maneja esta simulación. Arranque la simulación con up -FastWaits para que los casos que esperan el vencimiento terminen en unos 15 s y, en otra terminal:

cd console
npm install
npm run dev

Abra http://127.0.0.1:5173/admin/, ingrese con el usuario admin y la contraseña que imprimió up (no hace falta crear ningún usuario a mano) y entre al banco de pruebas. (npm install solo la primera vez.)

  • Cómo se conecta. El servidor de desarrollo de Vite, solo en loopback, reenvía /api/ a la API del POS (8090) y /emulator/ al emulador (9090). vite preview sirve el build sin cockpit y no expone ni el POS ni el emulador. Las llamadas a los servicios sin clave van con credentials: 'omit', así la cookie de sesión de la consola no llega a ellos; el carril del gateway usa el cliente de administración existente.
  • La clave de callbacks llega al emulador solo por la variable de entorno EMULATOR_GATEWAY_APIKEY de su proceso, nunca por el navegador ni la línea de comandos.
  • Catálogo fijo de 15 casos (código revisado como un test, sin API para crear casos). Cada caso prepara el estado (clearFaults y reset, más una falla si corresponde), ejecuta pasos (pedir trxid, trxpago asíncrono, esperar la intención, jugar la billetera, cancelar...) y evalúa expectativas sobre la respuesta al POS y la primera reacción del gateway: estado del pago, tareas de compensación, registro de cable y pedidos recibidos por el emulador.
  • Ejecutar todos corre los 15 casos en serie con un candado de ejecución; los dos casos de reintentos largos (*_QUERY_PAYMENT_503) van al final para que un resto de actividad contamine la menor cantidad de casos.
  • Panel manual. POS manual (pedir trxid, pagar, consultar, anular), selector de escenario con «Reproducir escenario» y «Reiniciar emulador», formulario de falla con «Encolar falla» y «Limpiar fallas», pedidos recibidos y correlación de ids (intención de Prisma, pago de la billetera).
Banco de pruebas recién abierto: POS, emulador y gateway alcanzables, lista de casos con botón Ejecutar
Banco de pruebas recién abierto: se confirma que POS, emulador y gateway responden y se listan los casos, cada uno con su botón «Ejecutar».
Caso Pago aprobado ejecutado, con todas las expectativas en PASS
Caso «Pago aprobado»: el escenario APPROVED se juega solo y cada expectativa (respuesta de trxpago, estado del pago, ausencia de tareas, cuatro llamadas en el log de cable) queda en PASS.
Ejecutar todos: los 15 casos del banco de pruebas en PASS
«Ejecutar todos»: los 15 casos del catálogo en PASS, con el camino observado de cada uno desplegable.

7.4 Jar independiente del emulador

El código lo soporta: PrismaEmulatorApplication es una aplicación ejecutable (el jar -exec) con puerto 9090 y bind a 127.0.0.1 por defecto. Es la vía para manejar un gateway que usted arranca por su cuenta (procedimiento completo en RUNBOOK sección 7).

mvn -q -pl prisma-emulator package -DskipTests
java -jar prisma-emulator\target\prisma-emulator-<version>-exec.jar --emulator.api-key=<clave-de-prisma>
  • --server.port= cambia el puerto; --server.address= la interfaz; --server.ssl.* habilita HTTPS.
  • Apunte el gateway al emulador con gateway.prisma.base-url=http://localhost:9090 y gateway.prisma.api-key=<clave-de-prisma> (perfil local). Para ver la página «Emulador» en la consola, gateway.admin.emulator-url=http://localhost:9090 (con cualquier otro perfil que no sea local o test, el gateway se niega a arrancar).
  • Indique al emulador adónde están los callbacks del gateway:
Invoke-RestMethod -Method Put -Uri http://localhost:9090/emulator/gateway -ContentType application/json `
  -Body '{"callbacksUrl":"http://localhost:8443/prisma/v1","apiKey":"<clave-de-callbacks>"}'

Después de que un trxpago creó la intención, juegue la billetera. waitForComplete vale true por defecto (la billetera espera la intención completa y paga uno de sus planes); pase false mientras el gateway no envíe planes:

Invoke-RestMethod -Method Post -Uri http://localhost:9090/emulator/scenarios -ContentType application/json `
  -Body '{"cuit":"30000000000","branch":"ALMACOR-DEMO-01","checkout":"CAJA-01","outcome":"APPROVED"}'

El estado se pierde al reiniciar el proceso: es memoria pura. Para variables de entorno equivalentes a las propiedades (por ejemplo EMULATOR_GATEWAY_CALLBACKSURL y EMULATOR_GATEWAY_APIKEY, que hacen que POST /emulator/reset conserve el destino), Spring Boot aplica su asociación relajada de nombres.

7.5 Problemas frecuentes

SíntomaCausa y solución
Port N is already in use on 127.0.0.1; refusing to startOtro proceso usa 9090, 8090, 8091 u 8443. Identifíquelo con Get-NetTCPConnection -LocalPort 9090 -State Listen y deténgalo; sim.ps1 nunca mata un proceso que no sea el suyo.
A simulation is already runningHay una simulación activa: down primero.
down informa «estado obsoleto»El PID registrado se reutilizó por otro proceso o ya no existe; down no lo toca y borra .state\state.json. Vuelva a ejecutar up.
up aborta al migrar o al conectarRevise que SQL Server responda en localhost y que las credenciales (config\application-local.yml o GPQR_DB_USER / GPQR_DB_PASSWORD) sean correctas, y que el nombre de la base termine en _SIM. up exige que exista flyway_schema_history con filas; si no, limpia y aborta. Los registros están en .state\gateway.log y .state\emulator.log (más *.err.log).
Estado viejo en el emuladorIntenciones o fallas de una prueba anterior alteran la siguiente: reset y faults-clear. El cockpit lo hace al inicio de cada caso.
Escenario FAILED con «no intention for this checkout»Se jugó la billetera antes de que el gateway creara la intención (falta el trxpago) o con otro cuit, sucursal o caja.
Escenario FAILED con «the wallet cannot pay it»La intención está cancelada, reemplazada o ya paga. Para pagar una cancelada use LATE_PAYMENT_AFTER_CANCEL.
«no gateway callbacks URL is configured»Faltó indicar los callbacks: PUT /emulator/gateway (en un jar independiente), o up de sim.ps1.
Intención completa con 404Pasaron más de 27 s desde los BINs, o los BINs no llegaron (requireBins), o ya se envió una completa (allowSecondComplete es false).
trxpago tarda casi un minutoEs la espera por defecto (45 s). Reinicie la simulación con up -FastWaits.
El cockpit muestra «Emulator: unreachable»El emulador no está arriba, o Vite se arrancó antes de la simulación o con otra configuración: status y reinicie npm run dev.
Un test lee pedidos y falta unoLa carrera de registro: espere por condición.

8. Limitación conocida (detectada el 2026-11-15)

El pago tardío tras una cancelación puede salir sin los datos de terminal. En el escenario LATE_PAYMENT_AFTER_CANCEL, el emulador arma el pago con el medio, el establecimiento, la terminal, la traza y el ticket del plan elegido solo si el gateway ya había enviado la intención completa antes de cancelar (plansKnown en WalletSimulator). Si el gateway canceló antes de enviar los planes, el emulador usa el medio de pago del BIN y un establecimiento fijo por defecto, pero la notificación sale con terminal_data vacío: sin terminal_number, trace_number ni ticket_number. Un test del módulo (s4_theLatePaymentOfAnIntentionThatNeverGotItsPlansHasNoNumbersToCarry) fija este comportamiento.

Del lado del gateway, una anulación forzada solo puede armarse para un cobro que se pueda nombrar: ForcedReversalRequest exige el número de terminal, la traza y el ticket. Resultado observado el 2026-11-15: la anulación del cobro tardío termina en COMPENSATION_FAILED.

El caso LATE_PAYMENT_AFTER_CANCEL del cockpit sigue en PASS porque no comprueba la compensación final: solo exige la anulación del cajero, los BINs tardíos NOT_LIVE, el pago tardío COMPENSATE y la existencia de las tareas CANCEL_INTENTION y REVERSE_CHARGE. Ese caso cancela durante la espera, antes de la intención completa, que es justo la combinación que deja el pago sin números.

Queda como brecha abierta, no como un defecto resuelto. Falta decidir si el emulador debe inventar números propios para el cobro tardío (si Prisma real los asignaría de todos modos) o si el gateway debe tratar un cobro tardío sin números como un caso de atención manual, y entonces el caso del cockpit debería comprobarlo. Este documento no afirma cómo notifica un Prisma real un pago tardío; el emulador toma una lectura y esa lectura no está confirmada.

9. Simulador interactivo del flujo

Esta sección conserva el simulador paso a paso que ya tenía este documento. No es el emulador: es un modelo ilustrativo que corre solo en el navegador, sin llamar a nada, para entender la oferta de planes. Los planes se configuran en el gateway (consola), por comercio y sucursal. Edite los planes, los medios aceptados y las tarjetas de la billetera y observe qué viaja en cada salto. El POS cobra por QR el importe indicado y, después de la aprobación, imputa la diferencia (descuento o recargo) y cierra por lo efectivamente cobrado. Si la espera vence sin resultado, el gateway cancela la intención, responde «denegado» (nunca «sin respuesta») y anula por su cuenta un cobro tardío. Los recargos y descuentos están construidos, pero no se habilitan en producción hasta que Prisma conteste la pregunta 10. Todos los datos son de ejemplo.

    POS

    Almacor · suc 3 · caja 7

    Mensajes

    Todavía no hay mensajes.

    Gateway

    GatewayPrismaQR

    Medios aceptados por el comercio

    Planes del gateway

    Gana el más específico: BIN > banco > medio (la sucursal gana sobre el comercio; aquí se simula un solo alcance). Banco 0 = todos. Días: lun,mar,mie,jue,vie,sab,dom (vacío = todos).

    MedioBancoBIN desdehastaCuotas%DesdeHastaDíasMín $

    Mensajes

    Todavía no hay mensajes.

    Prisma · Billetera

    Gateway QR v0.27

    Tarjetas en la billetera del cliente

    BINMedioBancoNombre

    Mensajes

    Todavía no hay mensajes.