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:
| Forma | Quién la usa | Dónde se explica |
|---|---|---|
| En proceso, como biblioteca | Los tests del gateway (*IT, end-to-end), que la arrancan desde el jar plano | RUNBOOK sección 7 |
Simulación local con sim.ps1 | Un desarrollador que quiere gateway y emulador sin POS | sección 7.2 |
| Con el cockpit (banco de pruebas) | Desarrollo y QA, con 15 casos catalogados | secció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.
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.
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 ruta | Respuesta | Qué hace | Operación de falla |
|---|---|---|---|
POST /largeaccounts/intentions | 201 | Crea 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&checkout | 204 | Recibe 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} | 204 | Cancela una intención viva. 404 si ya se pagó, cancelló o reemplazó. | CANCEL_INTENTION |
GET /payments/qr?intention_id= | 200 | Estado del pago (approved, rejected, annulled, refunded). 404 si no hay pago. | QUERY_PAYMENT |
GET /annulments?intention_id= | 200 | Estado 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 /forcedannulments | 201 | Inicia 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 /forcedrefunds | 201 | Í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)
| Llamada | Cuándo |
|---|---|
PUT {callbacks}/intentions/{id} | La billetera envía sus BINs. Espera 204. |
POST {callbacks}/payment | Notificación del pago, aprobado o rechazado. |
POST {callbacks}/annulment y /refund | Fin 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 ruta | Qué hace |
|---|---|
GET /emulator/health | {"status":"UP"}. |
POST /emulator/reset | 204. Olvida intenciones, pedidos registrados y reglas de falla, y vuelve al destino de callbacks de arranque. |
PUT /emulator/gateway | Indica adónde van los callbacks. Cuerpo: callbacksUrl, apiKey, opcional notifyReversals. |
POST /emulator/scenarios | 202 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/faults | 201. Agrega una regla de falla a la cola. |
DELETE /emulator/faults | 204. Vacía la cola de fallas. |
POST /emulator/reversals/{intentionId}/{kind}?approved=true | Termina a mano una anulación o devolución forzada (kind = ANNULMENT o REFUND) y notifica al gateway. Responde {"gatewayStatus": n}. |
GET /emulator/requests | Lo 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/catalog | Lista 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.
| Propiedad | Por defecto | Efecto |
|---|---|---|
emulator.complete-deadline | 27 s | Plazo para aceptar la intención completa desde los BINs. |
emulator.require-bins | true | Rechaza (404) la intención completa si los BINs no llegaron. |
emulator.allow-second-complete | false | Acepta una segunda intención completa. |
emulator.scenario-complete-timeout | 30 s | Cuánto espera un escenario la intención completa del gateway. |
emulator.reversal-delay | 200 ms | Demora hasta terminar una anulación o devolución forzada. |
emulator.gateway.timeout | 5 s | Tiempo de lectura de cada callback. |
emulator.gateway.notify-reversals | true | Notifica solo el fin de una anulación o devolución. |
emulator.reject-duplicate-integrator-id | false | Modo estricto: un integrator_intention_id repetido es 422. |
emulator.alphanumeric-codes-only | false | Modo estricto: branch y checkout solo con letras y dígitos. |
emulator.dashed-cuit-only | false | Modo 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.
| Outcome | Qué simula | El gateway debe |
|---|---|---|
APPROVED | BINs, intención completa, pago aprobado y una notificación. | Responder AUTORIZACION_DE_PAGO_APROBADA; pago APPROVED; sin tareas de compensación. |
REJECTED | Igual, pero el autorizador de la billetera rechaza el pago. | Denegar con el motivo de la billetera; pago REJECTED; sin compensación. |
MISSING_BINS | La 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_NOTIFICATION | El 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_NOTIFICATION | La notificación llega dos veces. | Aplicarla una sola vez: resultados APPROVED y luego DUPLICATE, un solo cobro registrado. |
LATE_NOTIFICATION | La 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_CANCEL | La 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_MISMATCH | Pago 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_PLAN | Pago aprobado en una cantidad de cuotas que la oferta nunca incluyó. | Igual que el anterior, con motivo UNOFFERED_PLAN. |
DOUBLE_CHARGE | Un 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_NUMBERS | El 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):
| Campo | Por defecto | Significado |
|---|---|---|
operation | ANY | CREATE_INTENTION, COMPLETE_INTENTION, CANCEL_INTENTION, QUERY_PAYMENT, FORCED_ANNULMENT, FORCED_REFUND, QUERY_ANNULMENT, QUERY_REFUND o ANY. |
mode | STATUS | Ver la tabla siguiente. |
status | 500 | Código HTTP para STATUS. (En sim.ps1 el parámetro se llama -HttpStatus.) |
delayMillis | 0 | Demora para DELAY, TIMEOUT y STALL_AFTER_HEADERS. |
count | 1 | A cuántas llamadas se aplica. |
executeAnyway | false | Solo para STATUS y CONFLICT: la operación se realiza y recién después se contesta la falla. |
garbageId | not-a-number | Valor de intention_id para GARBAGE_ID. |
| Modo | Lo que ve el gateway |
|---|---|
STATUS | El 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). |
DELAY | Espera delayMillis y responde normal: un Prisma lento. |
TIMEOUT | En 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. |
CONFLICT | 409 (también admite executeAnyway). |
GARBAGE_ID | Solo al crear: 201 con un intention_id que no es un número usable. |
STALL_AFTER_HEADERS | La 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_REQUEST | La 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_BODY | La 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 -ExecuteAnywayLa 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 100La 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-clearLo 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.
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 cabeceraapikey; la comparación es de tiempo constante. Una clave faltante o incorrecta responde 403 conInvalid 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.1por defecto (--server.addresslo cambia, a su propio riesgo).sim.ps1fija las direcciones de forma explícita, verifica conGet-NetTCPConnectionque 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 upgenera una clave de Prisma y una de callbacks de 64 caracteres, las guarda solo entools\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
adminque creaupsí se imprime (enupystatus) y se guarda en.state\state.json. Protege un entorno local, solo loopback, con una base descartable que se recrea en cadaup; 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-keyoEMULATOR_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.ps1las lee en silencio de variables de entorno o del bloquegpqr.db(ospring.datasource) deconfig\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.release25; sim.ps1 construye los jars conmvn -q package -DskipTestssi faltan). - SQL Server accesible en
localhost.upelimina y recrea una base desechableGatewayPrismaQR_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.ymlo en las variablesGPQR_DB_USERyGPQR_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 upup 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 1status 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_NOTIFICATIONLos 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 resetrequests 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 downsmoke 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 devAbra 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 previewsirve el build sin cockpit y no expone ni el POS ni el emulador. Las llamadas a los servicios sin clave van concredentials: '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_APIKEYde 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 (
clearFaultsyreset, más una falla si corresponde), ejecuta pasos (pedirtrxid,trxpagoasí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).
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.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:9090ygateway.prisma.api-key=<clave-de-prisma>(perfillocal). Para ver la página «Emulador» en la consola,gateway.admin.emulator-url=http://localhost:9090(con cualquier otro perfil que no sealocalotest, 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íntoma | Causa y solución |
|---|---|
Port N is already in use on 127.0.0.1; refusing to start | Otro 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 running | Hay 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 conectar | Revise 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 emulador | Intenciones 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 404 | Pasaron 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 minuto | Es 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 uno | La 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 7Mensajes
Todavía no hay mensajes.
Gateway
GatewayPrismaQRMedios 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).
| Medio | Banco | BIN desde | hasta | Cuotas | % | Desde | Hasta | Días | Mín $ |
|---|
Mensajes
Todavía no hay mensajes.
Prisma · Billetera
Gateway QR v0.27Tarjetas en la billetera del cliente
| BIN | Medio | Banco | Nombre |
|---|
Mensajes
Todavía no hay mensajes.