1. Resumen ejecutivo
GatewayPrismaQR es el gateway de cobro QR que une el POS de supermercado de Tipre con Gateway QR de Prisma. Actúa como Sistema Propio / Integrador Grande Cuenta según la especificación Integradores Grandes Cuentas QR v0.27 de Prisma. Se despliega una sola vez, en el servidor central donde ya corre GatewayQR, y atiende a varios comercios (un comercio por CUIT) desde uno o más nodos contra la misma base de datos.
Qué hace en un cobro:
- El POS pide un identificador de transacción (
trxid) y después el cobro (trxpago) por el importe a pagar con QR. - El gateway crea la intención de pago en Prisma. El cliente escanea el QR fijo de la caja con su billetera.
- Prisma envía al gateway los BINs de las tarjetas del cliente. El gateway responde, dentro de 27 segundos, la intención completa: por tarjeta, los planes de cuotas con su recargo o descuento, TNA y CFT.
- El cliente elige el plan en la billetera y paga. Prisma notifica el resultado.
- El gateway responde al POS con el importe cobrado y la diferencia (descuento o recargo). El POS imputa la diferencia al ticket después del pago y cierra por el importe realmente cobrado.
La garantía central (CONSTITUTION INV-01): si el gateway le dijo al POS que el pago no se hizo, o el POS lo canceló, el cliente no queda cobrado. Un vencimiento de espera equivale a una cancelación con anulación automática; el POS nunca recibe un resultado «desconocido».
| Dato | Valor | Fuente |
|---|---|---|
| Primeros comercios | Almacor y Becerra (clientes existentes de Prisma) | SPEC §2 |
| Volumen por comercio | 5.000 a 10.000 pagos QR por día | SPEC §2 |
| Pico derivado | ≈ 1.000 pagos en la hora más cargada (≈ 0,3 pagos/s); objetivo de diseño 5 pagos/s | SPEC §2 |
| Presupuesto crítico | 27 s entre los BINs y la intención completa | v27 p.22 |
| Pila | Java 25 (Temurin) · Spring Boot 4.1 · SQL Server 2022 · Windows Server | ADR-001 |
Qué está construido y qué falta
El sistema se construyó en slices verticales, cada uno con su revisión independiente (§14, §15). Los seis están convergidos e integrados en la rama feat/s2-prisma:
| Capacidad | Estado |
|---|---|
| Esqueleto, tres listeners, esquema completo de la base (19 tablas), CI, semilla, RUNBOOK | Implementado (S0) |
Contrato POS: trxid, trxpago con espera acotada, consulta GET /api/trxes/{id}, trxanulacion, mapeo de estado, marcas de aprobación |
Implementado (S1, S2b, S4) |
| Llamada «crear intención», clasificación del resultado, callbacks con apikey, buzón de notificaciones, registro de cables con enmascarado, BINs → intención completa, notificación → respuesta al POS, emulador de Prisma | Implementado (S2a, S2b) |
| Planes del gateway, recargos y descuentos, cuotas MiPyME, cashback | Implementado (S3) |
| Compensación: tarea con lease, una reversa por cobro de la billetera, anulaciones y devoluciones forzadas, conciliaciones, cancelación del cajero, reemplazo, recuperación multinodo | Implementado (S4) |
| Consola: usuarios propios y roles, tablero, auditoría, ABM, planes con rechazo de empates, simulador, catálogo del emulador | Implementado (S5) |
Entorno de pruebas para desarrollo: simulación local de gateway y emulador (tools\local-sim\sim.ps1 up -FastWaits) y banco de pruebas (cockpit) de la consola, con 15 casos confirmados y «ejecutar todos» |
Implementado (PR #11 y PR #12 a #20, integrados el 2026-11-14) |
Modelo formal TLA+ del ciclo de vida del pago, verificado con TLC (docs/modelo/) |
Verificado, con tres hallazgos: D-134 corregido (PR #7), D-132 y D-135 abiertos (§14) |
De los 32 criterios de aceptación confirmados, 30 siguen vigentes (AC-11 y AC-12 se retiraron con el Modo A) y 28 de esos 30 están cerrados, cada uno con una prueba verde que lleva su identificador. Siguen sin marcar dos: AC-15 y AC-16 (dependen de preguntas a Prisma); AC-14 se cerró el 2026-10-29 midiendo el redondeo en el POS real. AC-06, AC-09 y AC-27 se cerraron el 2026-10-28 con pruebas de punta a punta sobre el árbol integrado. En la primera corrida de pruebas registrada en el ledger (TR-1, 2026-11-15) el ledger midió 30 de los 32 criterios: AC-15 y AC-16 tienen pruebas en verde, pero siguen sin marcar a la espera de Prisma (§14). Lo que falta para salir a producción es externo al código o es verificación (§15).
2. Alcance
Dentro del alcance
El sistema completo desde el inicio (decisión del 2026-10-02, SPEC §3), con los recargos y descuentos activos:
- API del POS v1, compatible con el contrato de GatewayQR:
POST /api/trxid,POST /api/trxpago,POST /api/trxanulacion,GET /api/trxes/{id}. - Flujo de pago con Prisma: crear intención, callback de BINs, intención completa dentro de 27 s.
- Planes de cuotas por medio de pago, configurados en el gateway (consola) por comercio y sucursal. El plan de 1 cuota y el medio 112 (Transferencias 3.0) van siempre. Recargos y descuentos con signo (§7).
- Notificación de pago, consulta de estado y trabajo de conciliación.
- Anulación forzada, devolución forzada y cancelación de la intención (
DELETE /intentions/{id}). - Cashback (solo Visa Débito, v27 p.97).
- Cuotas MiPyME (planes 13 = 3 cuotas y 16 = 6 cuotas) como código de plan.
- Emulador de Prisma para pruebas de punta a punta, con una simulación local y un banco de pruebas (cockpit) para el desarrollo (§12, §13).
- Consola de administración React, con usuarios propios y dos roles: comercios, sucursales, cajas, terminales, establecimientos, planes, simulador de planes, búsqueda de pagos con su rastro, tablero y auditoría (§13).
- Despliegue multinodo activo: dos o más nodos contra la misma base; ningún estado en memoria decide dinero; los trabajos usan leases.
Dependencias fuera de este repositorio
Del lado del POS de los comercios (SPEC §3 punto 10): portar la imputación post-pago de descuentos, sumar el soporte de recargos (filas positivas, comando fiscal, percepciones) y convertir el rechazo silencioso en una falla explícita. Es trabajo de los equipos del POS, detallado en POS-IMPUTACION-QR.md; los riesgos R-04 a R-07 (§16) lo registran.
Estado del trabajo del lado del POS (actualizado el 2026-11-15; los resultados del kit de más abajo son del 2026-11-01 y 2026-11-02, salvo que se indique otra fecha):
- El código fuente del POS de Almacor está ahora en el repositorio privado
tipre/POS_ALMACOR. La línea base es la versión 20261003, intacta enmain. La compilación es reproducible con DOSBox-X y bcc286; la receta está en elBUILD.mdde ese repositorio. - G-01 (la aprobación por consulta pierde los montos, POS-IMPUTACION-QR.md §1.5) está corregido en la rama
fix/g01-consulta-amounts: los montos de la consulta se copian con una verificación de coherencia (importe + recdesc == final, yimporteigual al de la venta). - Decisiones del responsable del 2026-10-31: los recargos terminan en falla explícita (el POS rechaza y pide
trxanulacion); los descuentos se imputan como en la rama del cliente DINO. El trabajo está implementado en la ramafeat/qr-imputationy no está integrado. - Q2 (percepciones con descuento), decidida el 2026-10-31 e implementada: la base de la percepción depende del tipo de cliente (precio de venta o neto, con la regla que ya tiene el motor de Almacor); una percepción que el ticket ya tenía solo se reescala, nunca se anula por el mínimo ni se crea una nueva; cada percepción nueva se calcula una sola vez,
ROUND(base × alícuota); las filas valen el descuento menos la baja de las percepciones, repartidas con la regla del centavo residual, de modo que las filas más las percepciones suman exactamente lo cobrado. Como los recargos siguen sin imputarse, la pregunta de las percepciones con recargo no se aplica por ahora. - Revisión: dos rondas de revisión; no queda ningún hallazgo ALTO abierto de la revisión. Las rondas dejaron dos correcciones:
3017cd1(la promoción clásica del medio de pago se suma al descuento de la billetera en la fila del QR, en lugar de pisarse, y borrar todo el ticket anula el QR también con pago EMV en línea) yabbf58f(el comprobante imprime solo el descuento de la billetera, sin sumarle la promoción clásica). - Estado del PR #1 (2026-11-15): el trabajo está en el PR #1 de
tipre/POS_ALMACOR(ramafeat/qr-imputation), abierto y sin integrar. Conabbf58fla compilación termina sin errores y la prueba de arranque pasó (kit conmemsize36). Comprobante verificado en el kit con una promoción clásica del POS (P, −5 %, −137,50) más un descuento de billetera (D, −10 %) sobre un ticket de 2750,00: original 2612,50, descuento −261,25 y pagado 2351,25; el pago quedó en el gateway con importe 2612,50, ajuste −261,25 y final 2351,25. La anulación y la reimpresión del comprobante en el kit están en prueba. - Compuertas de despliegue abiertas del PR #1: la impresora fiscal no se probó; hay que configurar los perfiles 564 a 567 en cada cliente; y el medio de pago QR necesita un diálogo de carga con los campos Rec/Desc para registrar las promociones clásicas del POS (en los datos originales del kit no los tenía).
- Riesgo fuera de los dos repositorios (R-21): la biblioteca TCP del POS (TITCP,
LIBSP/WATTCPE/titcp.cpp) arma sus plazos con la hora de pared leída como HHMMSS (set_timeoutychk_timeout). Pasada la medianoche local, un cierre de conexión que depende de un plazo espera unos 30 minutos (3000 unidades HHMMSS que el código toma por 3 s). Se confirmó en el kit: la espera se liberó a los 30:00 y la siguiente a los 28:27, porque cruzó un límite de hora; la DLL del kit (suma md5) es igual a la del árbol de fuentes. Mitigación: reiniciar el POS antes de las 00:00. La corrección real es de quien mantiene la biblioteca. - Requisitos de despliegue (
QR-IMPUTACION.mdsección 5 yBUILD.mddel repositorio del POS):- Compilar con la receta de
BUILD.md. - Copiar
REPORTER/NOFISCAL/VO_QR.SCPareporter\NOFISCAL\del POS (el script anterior sigue funcionando, pero imprime solo el importe pagado). - Configurar los perfiles 564 a 567 (EAN, artículo, departamento y número de promoción de las filas del descuento QR): son obligatorios, porque con los valores por defecto esas filas comparten identidad con la promoción global clásica y podrían quitarse o sumarse por error. No se verificó que esos ids estén libres en la tabla de perfiles de cada cliente.
- Perfil 171 (
PermitePromosXMdeP) en 1; con 0 el POS anula el descuento QR. - Antes de habilitar planes con descuento, ejecutar los casos de prueba de la sección 6 de ese documento, en especial los de percepciones.
- Correr la prueba de arranque (
BUILD.md, «Boot probe») después de cada compilación, con los binarios finales y la memoria del despliegue (ver el fallo de arranque, abajo).
- Compilar con la receta de
- Resultados en el kit (DOSBox-X con
memsize36, commitsbfb2e40y743b40b; solo importes de prueba):- Aprobados: regresión; percepción con mínimo 2000 y con mínimo 3000; T-07 (descuento del 10 % con percepción en factura A); descuento del 12 % (filas −329,99, percepción 56,63, total 2476,64); factura B sin percepción; recargo del 10 % anulado; percepción sobre el precio de venta (cliente de tipo 6).
- Familia T-18 (borrado y salida del cobro con el QR autorizado): en
743b40b, QUIT aceptado (T-18b) aprobado: anula el pago, no congela el POS y el ticket queda sin descuento. QUIT rechazado se aprobó en la compilación anterior del mismo arreglo. Sin ejecutar: tecla de borrar medio (T-18), T-18c (necesita una impresora fiscal real) y T-18d (necesita una clave de supervisor). - Filas
DE_*persistidas: sin ejecutar. - Cierre Z: sin ejecutar.
- Caso de congelamiento con el pago en espera (hold): no se reprodujo: 15 de 15 recuperados como aprobados en
bfb2e40, 3 de 3 en la compilación de t12 y 1 de 1 en743b40b. Esto no cierra el defecto. - Ticket en espera y su recuperación: aprobado en
743b40b; vuelve con el ítem real y sin la fila en cero. Las operaciones 2015 y 12000 están deshabilitadas endM_Operaen los datos del kit y se habilitaron a mano solo para esta prueba. El ticket vuelve sin cliente, lo que coincide con el perfil 363 en 0 (lectura del código, sin corrida de control). - Sin ejecutar en ninguna compilación:
RepeatLast, nota de crédito parcial (se dejó afuera por ahora y además necesita un servidor condS_TDeta),Facturacion, T-21 y T-07 en factura B con percepción.
- Congelamiento al aceptar QUIT (corregido en
743b40b).CmosDdfMem::Remove()no hace nada, de modo quePagoQR_RemoveFilasDescuentono terminaba y el POS se congelaba después deQR_REVERSA_OK, 3 de 3 veces. Ahora las filas se dejan en cero en una sola pasada y los lectores las ignoran.DINO_20260902tiene el mismo lazo, sin probar. - Defectos abiertos, tal como se midieron:
- Fallo de arranque.
Fatal error 286.3360de Phar Lap en el primerDosLoadModuleen DOSBox-X, en ventanas de 4 MB dememsizecuya posición depende del diseño de la imagen. Los binarios entregados 20261003 también fallan. ReducirDGROUPde0xFF5Ca0xE1E8no eliminó las ventanas. La causa no está identificada. En una copia de la imagen VirtualBox de producción (sin placa de red y con dos TSR de red quitados),bfb2e40arrancó con los 27 tamaños de RAM probados, de 24 MB a 1 GB, pero ahí nunca se produjo el fallo: esto baja el riesgo y no lo cierra (R-18). DGROUPa 164 bytes del límite. ElDGROUPdePOS_MAIN.EXEtermina 164 bytes por debajo de 64 KB: es un peligro aparte del anterior. AdemásPOS_MPPO_TEXTyPOS_PROM_TEXTestán a menos de 1,9 KB de 64 KB, y el enlazador no avisa si un segmento se envuelve (R-19).- Congelamiento visto una vez (prueba t12). El POS quedó congelado después del timeout de 50 s de
trxpago, con la billetera cobrada y el gateway enAPPROVED. Abierto, severidad ALTA, causa desconocida (R-20).
- Fallo de arranque.
- Para la rama del cliente DINO se entregó el traspaso de G-01 a la sesión que la mantiene.
Fuera del alcance
- Intenciones en USD y tarjetas de beneficio (decisión del 2026-10-02).
- Devoluciones parciales y anulación de una devolución: Prisma las excluye (v27 p.5).
- Alta de QR por API: Prisma solo ofrece la carga masiva por planilla (§6, pregunta 23).
Sin fecha de salida a producción. El plazo de la homologación de Prisma no depende de nosotros (R-01): el sistema se construye y se prueba contra el emulador propio, de modo que solo la corrida de homologación espera a Prisma.
3. Topología y despliegue
flowchart TB
subgraph ORI["Origen de los cobros"]
direction LR
POS1["POS DOS de Almacor<br/>una caja por terminal"]
POS2["POS de otras cadenas"] --> RQ["RouterQR<br/>una por cadena"]
end
subgraph SRV["Servidor central · Windows Server · compartido con GatewayQR"]
direction LR
POSL["Listener POS<br/>IP del lado VPN<br/>HTTP/1.1 plano · solo /api"]
GW["GatewayPrismaQR<br/>Java 25 · servicio NSSM"]
CBL["Listener de callbacks<br/>HTTPS · puerto aparte<br/>apikey · solo /prisma/v1"]
ADL["Listener de administración<br/>loopback por defecto · solo /admin<br/>sesión y CSRF"]
DB[("SQL Server 2022")]
POSL --> GW
CBL --> GW
ADL --> GW
GW --> DB
end
PR["Prisma Gateway QR v0.27<br/>API HTTPS con apikey"]
W["Billetera"]
OP["Operador<br/>consola React"]
POS1 -- "VPN (R-14)" --> POSL
RQ -- "canal privado" --> POSL
OP -- "en el servidor" --> ADL
GW -- "crear intención, intención completa, reversas" --> PR
PR -- "BINs, pago, anulación, devolución" --> CBL
W --> PR
Tres listeners, tres superficies
| Listener | Atiende | Dirección por defecto | Protección |
|---|---|---|---|
| POS | solo /api/** |
127.0.0.1:8090, HTTP plano; en producción, la IP del lado VPN |
Ninguna autenticación propia: el POS DOS no envía cabecera de autenticación ni habla TLS. La protección es la VPN (INV-11, R-14). |
| Callbacks de Prisma | solo /prisma/v1/** |
todas las interfaces, puerto 8443, HTTPS obligatorio |
apikey que emite el gateway (INV-08). |
| Administración | solo /admin/**: los archivos de la consola y /admin/api/v1/** |
loopback, puerto 8091 |
Usuarios propios en la base, sesión con cookie y CSRF (ADR-005). Una dirección que no es loopback exige allow-remote=true y HTTPS. |
Una petición a una ruta que no es del puerto que la recibe (una del POS por el puerto de callbacks, un callback por el puerto del POS, cualquiera de las dos por el de administración) responde 404: el filtro revisa la ruta tal cual llega y tras normalizar .., %2e, ; y //. Así trxanulacion nunca es alcanzable desde internet ni desde la consola, y la consola no depende de la ruta del dinero: ningún pedido del POS ni de Prisma lee una sesión o una tabla de administración (INV-03).
El arranque se rehúsa (el servicio escribe el motivo en el log y termina) cuando: la dirección del POS está vacía, no es un literal IP, es un comodín (0.0.0.0, ::) o no es de loopback ni privada sin el reconocimiento explícito allow-public-address=true; los timeouts del POS están fuera de 1s..10m; los dos puertos coinciden; los callbacks no tienen TLS configurado fuera de los perfiles local y test; el perfil prod convive con local o test; la conexión a la base permite trustServerCertificate fuera de esos perfiles; la dirección de administración no es un literal IP, es un comodín o no es loopback sin allow-remote=true y un paquete SSL; el emulador del catálogo está configurado fuera de local y test; o los relojes encadenados no caben (espera, presupuesto de traspaso y margen contra la lectura del llamador; arrendamientos contra los tiempos de las llamadas a Prisma; ruta absoluta del archivo de marcas; ventana de consulta del POS). Un fallo de configuración se informa completo, no de a uno (RUNBOOK §1 y §3).
Anfitrión
- Servidor central compartido con GatewayQR (que hoy corre un WAR de Java 8 contra SQL Server). GatewayPrismaQR es un servicio aparte, con su propio
JAVA_HOME(Temurin 25), puerto y carpeta de logs. - Servicio de Windows con NSSM, como todos los servicios de Tipre: inicio automático, reinicio ante falla, rotación de logs, dependencia de
MSSQLSERVER.AppStopMethodConsole 130000espera más que el apagado ordenado (hasta 60 s de pedidos del POS en curso, 30 s del buzón, 30 s del trabajo de compensación —los dos se detienen uno después del otro— y 2 s de la espera) para no cortar pagos en curso. La rotación de logs es en línea (AppRotateOnline 1) cada 50 MB. Zona horaria fijada en UTC. - Hilos virtuales en los listeners. La espera acotada del POS (S2b) consulta el estado en la base cada 250 ms, en transacciones de solo lectura, de modo que no retiene hilos de plataforma ni conexiones mientras duerme.
- Multinodo: varios nodos contra una base. No hay estado en memoria que decida dinero; las tareas de fondo se reparten con leases (§9, §11). La única excepción deliberada es la sesión de la consola, que vive en la memoria de un nodo (§13).
Cómo llega el POS
| Comercio | Camino | Estado |
|---|---|---|
| Almacor | El POS llama directo al gateway por VPN. No tiene RouterQR y hoy no tiene ningún QR. Sin RouterQR nadie repite trxanulacion: hay un control diario (§9). |
Cobertura de la VPN a verificar (R-14). |
| Becerra | Por confirmar si usa un RouterQR de cadena o va directo. | R-12. |
| Cadenas con RouterQR | Una RouterQR por cadena, aunque las sucursales pertenezcan a socios distintos. Conectarla es un cambio de configuración (server.routerqr.prisma.url), sin tocar RouterQR ni el POS. |
Resuelto (SPEC §3.0). |
El gateway acepta las dos formas de pedido (POS nativo y reenviado por RouterQR) y siempre devuelve id y mediodepago, porque en la conexión directa nadie más los agrega (§5).
Relojes que se encadenan
| Quién espera | Cuánto | Consecuencia para el gateway |
|---|---|---|
POS Almacor: trxid y cada consulta GET /api/trxes/{id} |
lectura de 5 s (perfil 497), conexión de 3 s (perfil 498) | El gateway contesta dentro de ese tiempo: es una sola lectura. |
POS Almacor: trxpago |
lectura de 50 s (perfil 496: 150 s / 3; 51,7 s medidos en la corrida real del 2026-10-04) | La espera del gateway termina antes, con el perfil 36/12/2 (abajo). |
| POS Almacor: consultas posteriores | GET /api/trxes/{id} cada 10 s durante unos 5,5 minutos; el «Reintenta» del cajero lo puede extender |
Define la ventana de la conciliación (pos-polling-window, §9). |
| RouterQR (valores de desarrollo) | trxid 5 s; timeout-pago 60 s (lectura 59 s) |
Con RouterQR, la espera del gateway debe terminar antes de ≈ 50 s, o su respuesta «denegado» se pierde y el barrido de RouterQR dispara la anulación (R-13). Los valores de producción no están verificados. |
| Prisma: BINs → intención completa | 27 s | Presupuesto del flujo (§6). |
| Gateway → Prisma, llamada «crear intención» | conexión 3 s; intercambio completo 10 s | Pasado el tope, el resultado es desconocido y se compensa (§9). |
Perfil para el POS Almacor directo (36/12/2). Con caller-read-timeout: 50s, la espera del gateway (deadline) es de 36 s, el presupuesto para traspasar el pago a compensación es de 12 s y el margen de seguridad es de 2 s: 36 + 12 + 2 = 50 s. El vencimiento persiste la intención de compensación hasta 48 s después de la llegada y la denegación sale con 2 s de sobra. El cliente dispone de 36 s para aprobar en la app. Los valores por defecto (espera de 45 s, lectura de 59 s) son los de RouterQR. El arranque exige que la espera, el presupuesto y el margen quepan antes de la lectura del llamador, pero no detecta una espera de 45 s con un llamador de 50 s si queda un presupuesto menor que el esperado: el perfil de producción se fija a mano (RUNBOOK §3, D-115).
4. Modelo de comercio
Un comercio por titular legal (CUIT), como en GatewayQR. Una cadena con varios socios se modela como varios comercios: por ejemplo ALMACOR-ESCANUELA (4 sucursales) y ALMACOR-PALPASELLI (5 sucursales). El POS de cada sucursal manda en comercio el nombre de su socio (perfil PAGOQR_COMERCIO). Varios comercios pueden convivir detrás de la misma RouterQR de cadena.
flowchart TB
CH["Cadena (por ejemplo Almacor)<br/>no es una entidad: solo agrupa comercios"]
M1["Comercio ALMACOR-ESCANUELA<br/>CUIT propio · CBU · MCC"]
M2["Comercio ALMACOR-PALPASELLI<br/>CUIT propio"]
CH -.-> M1
CH -.-> M2
M1 --> B1["Sucursal 3<br/>número del POS · branch_code (branch de Prisma)"]
B1 --> C1["Caja 7<br/>número del POS · checkout_code (checkout de Prisma)<br/>un QR fijo registrado en Prisma"]
C1 --> T1["Terminal<br/>8 caracteres · trace_seq · ticket_seq"]
M1 --> E1["Establecimiento<br/>uno por medio de pago"]
M1 --> P1["Medios aceptados<br/>y planes"]
| Entidad | Campos clave | Reglas |
|---|---|---|
| Comercio | name (el comercio del POS), cuit (11 dígitos), cbu (22 dígitos, solo si opera Transferencias 3.0), mcc (obligatorio, 4 dígitos), enabled |
Uno por CUIT. cuit y cbu viajan en cada intención y deben coincidir con el alta del QR en Prisma. |
| Sucursal | number (del POS), branchCode (≤ 25 caracteres, el branch de Prisma) |
number y branchCode únicos por comercio. |
| Caja | number (del POS, es el campo pos de trxid), checkoutCode (≤ 25 caracteres, el checkout de Prisma) |
Un QR fijo por caja, registrado en Prisma fuera de línea. El POS no genera ni muestra ningún QR (§6). |
| Terminal | terminalNumber (8 alfanuméricos), traceSeq, ticketSeq |
Una por caja. Las secuencias avanzan de forma atómica y nunca se reutilizan (INV-05); topes de Prisma: ticket 6 dígitos, trace 10 dígitos. |
| Establecimiento | establishmentId (≤ 67 caracteres) |
Número de establecimiento del adquirente por comercio y medio de pago. |
El MCC se carga a mano en la consola (página Comercios) y solo se valida que tenga exactamente 4 dígitos (MerchantInput). No se valida contra una lista, porque el anexo de Prisma con los MCC válidos no es público (pregunta 20). Decidido el 2026-11-15.
El trxid identifica la caja con la terna pos (caja), sucursal y comercio. Un comercio, sucursal o caja deshabilitados se rechazan con un error no 2xx (AC-01); si se deshabilitan después de emitir el trxid, trxpago responde 404.
5. Contrato con el POS
API v1, compatible con GatewayQR: el POS y RouterQR deciden solo por la cadena estado, que nunca cambia (HANDOFF, reglas duras).
| Endpoint | Función | Estado |
|---|---|---|
POST /api/trxid |
Emite el identificador del pago. Responde 201 {id, pos, sucursal, comercio, mediodepago}. |
Implementado |
POST /api/trxpago |
Inicia el cobro y espera el resultado con un tope por debajo de la lectura del llamador (§3, §9). | Implementado |
GET /api/trxes/{id} |
Misma forma que trxpago, con el estado y el importe actuales (AC-05). |
Implementado |
POST /api/trxanulacion |
Anulación pedida por el POS o por el barrido de RouterQR. Idempotente (AC-23, §9). | Implementado |
GET /api/ping |
Sonda de vida. | Implementado |
Las dos formas de pedido
| Campo | POS nativo (Almacor) | Reenviado por RouterQR |
|---|---|---|
trxpago — importe |
totalitem |
importe (igual a totalitem) |
trxpago — identificador |
id |
id = id del gateway |
trxpago — otros |
totalcashback, nropv, nroticketfiscal |
agrega tipoautorizador: "TECSO" (se ignora) |
trxanulacion |
id = id del pago; trxidoriginal = 0 |
id y trxidoriginal = id del pago |
Regla de normalización: el pago a anular es trxidoriginal si es mayor que 0 y, si no, id. Los importes tienen a lo sumo dos decimales (más finos se rechazan, nunca se redondean), a lo sumo 99.999.999.999,99, y totalitem e importe deben coincidir (AC-02).
La respuesta
Ejemplo de un pago aprobado en 6 cuotas con recargo del 12 % sobre $ 100.000:
{
"id": 1206901,
"estado": "AUTORIZACION_DE_PAGO_APROBADA",
"statuscode": 0,
"importe": 100000.00,
"importe_final": 112000.00,
"importe_recdesc": 12000.00,
"cuotas": 6,
"paymentinstallments": 6,
"payment_method_id": 104,
"payment_method_type": "credit_card",
"autorizadortrxid": "4501873",
"autorizadorintencionid": "784512",
"mensajevarios": "A1B2C3",
"mediodepago": "PRISMA"
}
- INV-04:
importe + importe_recdesc == importe_final, al centavo, en toda respuesta.importe_recdesclleva signo: positivo es recargo y negativo es descuento. La capa de respuesta se niega a emitir un total que no cierre. - Los dos ids de autorizador son cadenas de dígitos, no se cambian a otro tipo: RouterQR los lee como numéricos. Todo lo demás numérico es número JSON.
- El POS lee las cuotas de
paymentinstallments, nunca decuotas: se envían las dos con el mismo valor. - Solo un pago que la billetera pagó (
APPROVED,ANNULLED,REFUNDED) lleva el resultado de la billetera. Un pago traspasado a compensación responde solo la denegación, aunque después se haya guardado un resultado tardío. -
mensajevariosmide a lo sumo 79 bytes de UTF-8 (el POS lo copia a unchar[80]); se corta en un límite de carácter. El motivo de una denegación se guarda, de modo quetrxpago, sus reintentos yGET /api/trxes/{id}dicen exactamente lo mismo. -
Cashback en la respuesta. Un pago aprobado que pidió cashback lleva
totalcashback, que es lo que el cliente retiró (cero si lo rechazó);importe_finalnunca lo incluye. Un pago que no pidió cashback responde sin el campo, y una denegación o una anulación nunca lo llevan.
Traducción del estado interno a estado
| Estado interno | estado que ve el POS |
statuscode |
|---|---|---|
ID_ISSUED |
OBTENCIONIDTRX |
— |
INTENT_SENDING |
INTENCION_DE_PAGO_ENVIADA |
— |
INTENT_CREATED, BINS_RECEIVED, COMPLETE_SENT |
INTENCION_DE_PAGO_RECIBIDA_APROBADA |
0 |
INTENT_FAILED, COMPLETE_FAILED |
INTENCION_DE_PAGO_RECIBIDA_DENEGADA |
1 |
APPROVED |
AUTORIZACION_DE_PAGO_APROBADA |
0 |
REJECTED, CANCELLED, SUPERSEDED, EXPIRED, COMPENSATION_PENDING, COMPENSATED, COMPENSATION_FAILED |
AUTORIZACION_DE_PAGO_DENEGADA |
1 |
ANNULLED, REFUNDED |
AUTORIZACION_DE_ANULACION_APROBADA |
0 |
Esta es la tabla de trxpago. La consulta GET /api/trxes/{id} responde REFUND_DENEGADO (statuscode 1) para todo pago que el gateway decidió de forma irreversible como "sin venta": REJECTED, CANCELLED, SUPERSEDED, EXPIRED, INTENT_FAILED, COMPLETE_FAILED, COMPENSATION_PENDING, COMPENSATED y COMPENSATION_FAILED. El resto del cuerpo es el mismo que el de trxpago, y los demás estados responden igual que en la tabla. El POS Almacor solo deja de consultar con REFUND_DENEGADO o un estado aprobado o anulado (CONVENTIONS §4; AC-05 y ADR-004, enmendados el 2026-10-04).
No existe AUTORIZACION_DE_PAGO_SINRESPUESTA: el switch del traductor no tiene rama por defecto, así que agregar un estado no compila hasta decidir su traducción.
Lo que el POS oyó: marcas de aprobación y aprobación diferida
Un POS puede oír «denegado» en trxpago y después «aprobado» en su consulta. Lo que cuenta para una venta es la última respuesta que el POS oyó (INV-01, enmendada el 2026-10-04): si alguna vez se le dijo «aprobado», es una venta y nunca se compensa como «sin venta». Por eso toda respuesta AUTORIZACION_DE_PAGO_APROBADA, en trxpago o en la consulta, deja dos marcas durables en el pago:
- La intención va primero. Antes de que salga una respuesta aprobada,
pos_approval_intent_atse escribe en su propia transacción corta. Sin intención durable no se dice «aprobado». - La marca de «se le dijo» va después de vaciar la respuesta.
pos_told_approved_atse escribe cuando la respuesta ya se escribió completa hacia el POS: el filtro que la registra está fuera del que fija elContent-Length, porque solo allí unflushBuffer()sin error significa que los bytes salieron. Una respuesta solo armada, solo en el búfer o cuyo vaciado falló no deja marca. Si el registro falla, la respuesta ya enviada no se toca y se emite una alerta al operador (POS_APPROVAL_UNRECORDED). - Cualquiera de las dos marcas significa «el POS pudo oír aprobado»; las dos vacías, que nunca lo oyó. Es lo único que lee la conciliación de §9.
- Aprobación diferida. Si la intención no se puede escribir, el gateway no dice «aprobado»: responde
INTENCION_DE_PAGO_RECIBIDA_APROBADA(statuscode0) sin ninguno de los campos de la aprobación, entrxpagoy en la consulta (alertaPOS_APPROVAL_DEFERRED). Es el estado que el gateway ya devuelve para un pago sin liquidar; el POS Almacor lo lee como «preguntar de nuevo», sigue consultando cada 10 s y la próxima consulta reintenta la intención. Una RouterQR solo aprueba conAUTORIZACION_DE_PAGO_APROBADA: no ve aprobación y su barrido anula, la dirección segura. Además, el gateway deja el marcador durable del nodo (UnpersistedDenials) para ese pago: si la base queda caída durante todo el ciclo de consultas del POS y el cajero cancela, al volver la base la conciliación anula la venta de forma automática cuando ninguna de las dos marcas está puesta y pasó la ventana de consultas; si alguna está puesta, queda para una persona (D-124, RUNBOOK §3). - Vista de anulación (D-118). Un pago aprobado cuya reversa de venta está en curso o terminada se muestra en la consulta y en el reintento de
trxpagocomoAUTORIZACION_DE_ANULACION_APROBADA, nunca como venta; y la intención de aprobación se rechaza mientras la venta se anula (alertaPOS_APPROVAL_WITHHELD). Si la anulación falló o la tarea se rindió, el pago sigue mostrándose aprobado, porque el dinero sigue cobrado.
Cómo habla el POS por el cable
Verificado contra el código del POS y la corrida real de punta a punta (CONVENTIONS §4):
- HTTP/1.1 con cabecera
Host, dos espacios después del método y saltos de línea LF sin CR. Tomcat lo acepta; el peor caso de la familia (HTTP/1.0 sinHost) también está probado. Content-Length, nuncachunked: el POS no sabe interpretar un cuerpo fragmentado. El cuerpo, pequeño, se arma completo antes de enviarlo.Connection: closeen toda respuesta de/api: el POS vuelve a leer una vez más después de la respuesta; con la conexión abierta esa lectura consume sus 1,5 s completos. El servidor cierra de inmediato.- Éxito es HTTP 200 o 201. Todo error bajo
/api, incluida una ruta inexistente (404) o un método incorrecto (405), es{"status": <entero>, "message": "..."}, con mensajes cortos (el POS copia a lo sumo 99 caracteres) y sin detalles internos. - Reintentos (AC-04): el mismo
idcon exactamente los mismos datos devuelve el estado guardado y nunca envía una segunda intención; con datos distintos responde 409. - La respuesta nunca serializa una entidad JPA (INV-09): solo DTO explícitos.
6. Flujo con Prisma (v27)
%%{init: {"sequence": {"wrap": true, "width": 180}}}%%
sequenceDiagram
autonumber
participant POS
participant GW as Gateway
participant PR as Prisma
participant W as Billetera
POS->>GW: POST /api/trxid
GW-->>POS: 201 con id numerico
POS->>GW: POST /api/trxpago (importe)
GW->>PR: POST /largeaccounts/intentions (cuit, branch, checkout, mcc, original_amount, bins_max_quantity 99)
PR-->>GW: 201 con intention_id
Note over GW: el pago queda esperando, con tope menor al timeout de RouterQR
W->>PR: escanea el QR fijo de la caja
PR->>GW: PUT /prisma/v1/intentions/{id} con los BINs
GW-->>PR: 204 en menos de 200 ms (p95)
Note over GW,PR: comienza el reloj de 27 s
GW->>GW: resuelve los planes por BIN y asigna terminal, trace y ticket
GW->>PR: PUT /largeaccounts/intentions/complete (siempre 1 cuota y medio 112)
PR-->>GW: 204
PR->>W: muestra medios y planes
W->>PR: el cliente elige y paga
PR->>GW: POST /prisma/v1/payment (amount, installments, status)
GW-->>PR: 200
GW-->>POS: AUTORIZACION_DE_PAGO_APROBADA con importe_final e importe_recdesc
POS->>POS: imputa la diferencia y cierra el ticket
Diagramas interactivos. El mismo flujo, con un recorrido paso a paso por el teclado: pago-qr-aprobado.html. La anulación del cajero sobre un pago aprobado, también paso a paso: anulacion-cajero-qr.html.
Llamadas salientes y callbacks
| Dirección | Operación | Detalle |
|---|---|---|
| Gateway → Prisma | POST /largeaccounts/intentions |
Lleva integrator_intention_id, cuit, branch, checkout, mcc, intention_type = payment, currency = ARS, original_amount y bins_max_quantity = 99; cbu solo si el comercio opera Transferencias 3.0 (AC-06). |
| Gateway → Prisma | PUT /largeaccounts/intentions/complete |
Por medio de pago y BIN: plan de 1 cuota, planes con TNA y CFT, establecimiento, terminal, trace y ticket. El medio 112 siempre va (AC-08). |
| Gateway → Prisma | DELETE /intentions/{id}, POST /forcedannulments, POST /forcedrefunds, GET /payments/qr, /annulments, /refunds |
Compensación y conciliación (§9). |
| Prisma → Gateway | PUT /prisma/v1/intentions/{id} |
BINs. Responde 204 en el acto; el procesamiento sigue desde el buzón. |
| Prisma → Gateway | POST /prisma/v1/payment |
Notificación del pago. La ruta, la autenticación y la respuesta esperada no están definidas en v27 (pregunta 5): se configuran (payment-path, payment-ack-status, 200 por defecto). |
| Prisma → Gateway | POST /prisma/v1/annulment y POST /prisma/v1/refund |
Resultado de reversas. Responden 202. |
El integrator_intention_id es <prefijo>-<idDePago>-<intento> (por ejemplo GPQR-8-1): único por intento y de a lo sumo 40 caracteres. El prefijo (gateway.intentions.id-prefix) identifica el despliegue y debe ser distinto entre dos gateways que compartan el mismo ambiente de Prisma.
Cómo se clasifica el resultado de «crear intención»
La decisión es de dinero: ¿pudo haberse creado una intención que el cliente pague?
| Respuesta de Prisma | Resultado | Consecuencia |
|---|---|---|
201 con intention_id de 1 a 12 dígitos |
Creada | Se guarda el id y el pago sigue a INTENT_CREATED. |
| 400, 401, 403, 404 y un 422 que es claramente el error de validación de v27 | Rechazo definitivo | No se creó nada: no hay compensación. El pago pasa a INTENT_FAILED con un motivo corto. |
| Timeout, error de E/S, certificado no confiable, 5xx, 3xx, 408, 409, 429, cualquier otro 4xx, cualquier 2xx que no sea 201, un 201 sin id utilizable, una respuesta ilegible o excesiva, un 422 que puede ser un duplicado | Desconocido | La intención puede existir. Se aplica la compensación (§9). El POS recibe «denegado», nunca un 500. |
Todo el intercambio está acotado, cabeceras y cuerpo: pasado el tope de lectura (10 s) se corta la conexión, y un cuerpo se lee con un máximo (1 MiB por defecto). No se sigue ninguna redirección, para que la apikey no salga hacia otro host.
Presupuestos
| Paso | Presupuesto | Fuente |
|---|---|---|
| Respuesta al callback de BINs | menos de 200 ms en el percentil 95 (antes se medía el máximo de 48 muestras; D-106 cerrada el 2026-11-14) | AC-07 |
| Intención completa enviada | menos de 3 s en el percentil 99 (contra el emulador), siempre dentro de 27 s | AC-07, SPEC §3.2 |
| Espera del POS por el resultado | por debajo de los relojes de RouterQR y del POS (§3) | R-13 |
El QR de la caja
Lectura del PDF oficial de Prisma (Integradores Grandes Cuentas QR v0.27, IntegradoresGrandesCuentasQRv27.pdf en la raíz del repositorio):
- La billetera recibe siempre la última intención creada para esa caja (p. 6), y una intención nueva invalida la anterior (p. 7).
- La intención lleva
cuit,branchycheckout, máscbuymcc(p. 11 y 15): esa terna identifica la caja. - El alta de los QR es masiva, con una planilla de Excel que el historial de versiones del PDF menciona (v0.19, p. 4) y que no viene en el PDF; la CBU de la intención debe coincidir con la cargada en el alta del QR (p. 4 y 11).
qr_rawno es obligatorio en la respuesta de la intención (p. 15 y 16).
Lectura: un QR por caja, registrado de antemano (el documento nunca lo llama «estático») y el importe viaja solo en la intención. El POS no genera ni muestra ningún QR. Opción de pinpad: el protocolo F0101 V02/V04 de Fiserv tiene el comando YQ1 («mostrar código QR en pantalla»), que hoy no usa ningún cliente; mostrar el QR en el pinpad exigiría que el gateway exponga qr_raw y que el POS integre YQ1. Cómo se da de alta y se muestra el QR de cada caja es la pregunta 23 a Prisma.
Cashback
Solo con Visa Débito y en 1 pago (AC-17). original_amount es el importe de la venta tal como lo pidió el POS; un cashback mayor que cero viaja como cashback_max_amount con absolute_cashback en true por defecto (gateway.prisma.absolute-cashback), de modo que el cliente retire exactamente lo impreso en el ticket. El ajuste de cuotas nunca se aplica al efectivo. La intención completa de v27 no tiene un campo para ofrecer cashback, así que la regla se aplica sobre lo que vuelve: la notificación con cashback_amount se honra solo si es igual a lo pedido, en Visa Débito y en 1 pago; sin retiro (ausente o cero) la venta sigue; cualquier otra cosa (otro medio, otras cuotas, un monto distinto, un valor ilegible) no se honra y el pago se compensa, de modo que el cliente nunca queda con efectivo retirado que ninguna venta respalda. Qué amount informa Prisma con cashback es una duda abierta (preguntas 21 y 22).
Contrato interno del flujo (S2a y S2b)
Reglas que atan a las dos mitades de S2 (CONVENTIONS §9):
- Toda salida de
trxpagoespera hasta un estado final o traspasa a compensación; no existe una salida que deje el pago esperando. - Si el vencimiento compite con una aprobación tardía, gana el estado final: se responde la aprobación, no una denegación a un cliente ya cobrado.
COMPLETE_SENTy las filas decomplete_snapshotse persisten antes de enviar la intención completa: un corte después de la llamada deja los números que necesita una anulación forzada.- Un callback que todavía no se puede correlacionar (llegó antes de que se guardara el id de Prisma) se guarda sin procesar y un trabajador lo reintenta desde el buzón; jamás se contesta con error por eso.
- Todo resultado de la billetera se aplica por un solo punto (
WalletResults.apply), que ArchUnit protege.
7. Planes, recargos y descuentos
El cliente elige el plan en la billetera; el POS no elige nada. El POS nunca ve la tarjeta: los BINs le llegan al gateway desde Prisma. El POS se entera del medio, de las cuotas y del importe final cuando el pago ya está aprobado, y ahí imputa la diferencia: un descuento o un recargo, los dos de primera clase.
El POS trabaja postpago: manda por QR el importe a cobrar, el cliente elige en la billetera, y después de la aprobación el POS imputa la diferencia al ticket y cierra por lo efectivamente cobrado.
Los planes se configuran en el gateway (consola), por comercio y sucursal.
flowchart TB
B["Planes del gateway<br/>tabla installment_plan<br/>por comercio y sucursal"]
B --> O["OfferedPlans por BIN<br/>más 1 cuota sin ajuste siempre"]
O --> X["Intención completa<br/>más el medio 112 siempre"]
X --> C["El cliente elige<br/>en la billetera"]
C --> N["Notificación<br/>amount e installments"]
N --> R["importe_recdesc = amount - importe<br/>con signo"]
R --> P["El POS imputa postpago<br/>y cierra por lo cobrado"]
Qué plan se ofrece
Cada plan fija un medio de pago y, si quiere, un banco o un rango de BIN, la cantidad de cuotas, el porcentaje con signo, TNA y CFT, la vigencia, los días de la semana, un monto mínimo y una sucursal. Para cada tarjeta y cada cantidad de cuotas el gateway aplica estas reglas (AC-13):
- Se filtran los planes habilitados que valen ese día (en la zona horaria de los comercios), que aplican a ese día de la semana y cuyo mínimo llega al importe; un BIN de un medio que el comercio no acepta no se ofrece.
- Gana el más específico: la sucursal gana sobre el comercio y, dentro del mismo alcance, el rango de BIN gana sobre el banco y el banco sobre el medio.
- Dos planes que empatan son un error de configuración: el motor no ofrece nada y traspasa el pago a compensación, y la consola se niega a guardarlos (§13).
- El ajuste se calcula siempre sobre todo el importe QR.
Reglas comunes: el plan de 1 cuota y el medio 112 van siempre (AC-08); un plan de 1 cuota con descuento reemplaza al implícito y uno con recargo se rechaza; los planes Cuotas MiPyME (13 y 16) llevan su código de plan (AC-16); TNA y CFT se envían cuando hay recargo y valen 0 sin interés o con descuento (AC-15).
Ejemplo numérico
QR de $ 100.000:
| Elección del cliente | Cálculo | importe_final |
importe_recdesc |
|---|---|---|---|
| Visa Galicia, 6 cuotas, plan sin interés | 0 % | 100.000,00 | 0,00 |
| Mastercard Macro, 6 cuotas, +12 % | 100.000 × 12 % = 12.000,00 | 112.000,00 | +12.000,00 |
| Visa Débito Santander, 1 pago, −10 % | 100.000 × −10 % = −10.000,00 | 90.000,00 | −10.000,00 |
El POS cierra un ticket de $ 150.000 pagado con $ 100.000 por QR en 6 cuotas al +12 %: total de productos 150.000 + recargo 12.000 = 162.000; medio QR 112.000; efectivo 50.000. Por el cable no viaja el ticket, solo el importe del QR.
Redondeo igual al del POS (AC-14): mitad alejándose del cero y un solo redondeo, el del motor de promociones por medio de pago del POS: ajuste = redondeo2((redondeo2(importe) × redondeo2(%)) / 100) (el porcentaje se redondea a 2 decimales antes de aplicarse), cuota = redondeo2(total / cuotas). Si no se calcula igual, la misma tarjeta da recargos distintos en el pinpad y en el QR. La explicación completa, la resolución de planes paso a paso, la imputación en el POS y un simulador interactivo están en planes-cuotas.html; el simulador visual de los tres actores está en emulador-qr.html.
Estado y condiciones
- Los planes están implementados (S3). Un plan con recargo sin tasas válidas, o que no deja nada por pagar, se guarda marcado como no ofrecible y conserva su lugar: sigue ganando esas cuotas para las tarjetas que cubre, de modo que un plan menos específico no puede ofrecerles esa cantidad de cuotas a un precio que el comercio no fijó. Solo se omite un plan cuando no se puede leer su tarjeta o su cantidad de cuotas.
- Los recargos y los descuentos están construidos y probados contra el emulador, pero no se habilitan en producción hasta que Prisma conteste la pregunta 10: si no acepta un
total_amountdistinto deoriginal_amount, hasta entonces se ofrecen únicamente planes cuyo total es igual al importe. - Cashback: el ajuste nunca se aplica al efectivo (§6).
- AC-14 se cerró por medición el 2026-10-29: el redondeo es el del POS y se midió en el POS de Almacor, con recargos y descuentos y con los casos de medio centavo. AC-15 y AC-16 siguen abiertos: TNA y CFT se envían y se verifican solo en su estructura (D-S3-10), y el código de plan MiPyME no viaja a Prisma hasta que conteste la pregunta 9 (D-S3-11).
- Depende además del POS: el sistema nunca debe registrar una venta QR por un importe distinto del que cobró la billetera (INV-06). Si el POS no puede imputar, falla en forma explícita y el pago se revierte (R-04).
- El tratamiento impositivo de un recargo financiero (IVA, percepciones) y el comando fiscal del recargo se deciden fuera del gateway (R-05, R-06). Para los descuentos con percepción, la decisión Q2 ya está tomada y se implementó en la rama del POS de Almacor (§2); el recargo sigue sin imputarse en ese POS y termina en falla explícita.
8. Máquina de estados
Un solo estado por pago, con una sola tabla de transiciones: toda transición no declarada es un error, probado para cada par de estados. Hay 17 estados y ningún UNKNOWN: una espera vencida o un resultado desconocido van a compensación (ADR-002).
stateDiagram-v2
[*] --> ID_ISSUED
ID_ISSUED --> Viva: trxpago
ID_ISSUED --> CANCELLED: anulación
ID_ISSUED --> EXPIRED: sin uso
state "Intención viva" as Viva {
[*] --> INTENT_SENDING
INTENT_SENDING --> INTENT_CREATED: creada
INTENT_CREATED --> BINS_RECEIVED: BINs
BINS_RECEIVED --> COMPLETE_SENT: completa
COMPLETE_SENT --> BINS_RECEIVED: otra ronda
}
INTENT_SENDING --> INTENT_FAILED: rechazo
BINS_RECEIVED --> COMPLETE_FAILED: sin enviar
COMPLETE_SENT --> APPROVED: paga
COMPLETE_SENT --> REJECTED: rechaza
Viva --> COMPENSATION_PENDING: vencimiento
Viva --> SUPERSEDED: reemplazo
REJECTED --> COMPENSATION_PENDING: pago tardío
INTENT_FAILED --> COMPENSATION_PENDING: pago tardío
COMPLETE_FAILED --> COMPENSATION_PENDING: pago tardío
SUPERSEDED --> COMPENSATION_PENDING: tardío
APPROVED --> ANNULLED: anulación forzada
APPROVED --> REFUNDED: devolución forzada
COMPENSATION_PENDING --> COMPENSATED: terminada
COMPENSATION_PENDING --> COMPENSATION_FAILED: sin reintentos
COMPENSATED --> COMPENSATION_PENDING: pago tardío
COMPENSATION_FAILED --> COMPENSATION_PENDING: pago tardío
classDef ok fill:#dff1e3,stroke:#1f6b35,color:#142029
classDef bad fill:#f8e0dc,stroke:#9a2f1f,color:#142029
classDef comp fill:#fbe9d2,stroke:#8a4a00,color:#142029
class APPROVED,ANNULLED,REFUNDED,COMPENSATED ok
class REJECTED,INTENT_FAILED,COMPLETE_FAILED,COMPENSATION_FAILED bad
class COMPENSATION_PENDING comp
Las cuatro etapas del recuadro «Intención viva» comparten dos salidas: «vencimiento» o cancelación (hacia COMPENSATION_PENDING) y «reemplazo» (hacia SUPERSEDED). Los rechazos, fallas y reemplazos vuelven a COMPENSATION_PENDING solo ante un pago tardío.
Diagrama interactivo. Los 17 estados y sus transiciones, recorridos por grupos, con lo que ve el POS de cada uno: estados-del-pago.html.
| Estado | Significado |
|---|---|
ID_ISSUED |
Se emitió el trxid; todavía no hay importe. |
INTENT_SENDING |
trxpago aceptado; la llamada «crear intención» está en curso. |
INTENT_CREATED |
Prisma creó la intención; la billetera aún no respondió. |
BINS_RECEIVED |
Llegaron los BINs de la billetera. |
COMPLETE_SENT |
Se envió la intención completa; se espera el resultado. |
APPROVED |
La billetera pagó. |
REJECTED |
La billetera rechazó. |
INTENT_FAILED |
Prisma rechazó definitivamente la creación. |
COMPLETE_FAILED |
La intención completa no llegó a tiempo. |
SUPERSEDED |
Un pago más nuevo empezó en la misma caja. |
CANCELLED |
Cancelado antes de existir una intención (id abandonado, anulación antes del cobro). |
EXPIRED |
Id emitido y nunca usado (lo barre un trabajo de limpieza). |
ANNULLED |
Un pago aprobado, anulado (misma tanda de cierre). |
REFUNDED |
Un pago aprobado, devuelto (tanda anterior). |
COMPENSATION_PENDING |
Al POS se le dijo «sin venta» o el cajero canceló mientras la billetera aún podía cobrar: hay una compensación debida. |
COMPENSATED |
La compensación terminó: se canceló la intención o se devolvió el dinero. |
COMPENSATION_FAILED |
La compensación agotó sus reintentos; hay una alerta para atención manual. |
Los estados que nunca llegaron a la billetera (CANCELLED, EXPIRED) y los de dinero devuelto (ANNULLED, REFUNDED) no tienen salida. COMPENSATED y COMPENSATION_FAILED se reabren solo ante un resultado tardío de la billetera (INV-03).
La intención
Prisma conserva una intención por caja: la más reciente reemplaza a la anterior. El gateway modela la suya con una tabla propia.
stateDiagram-v2
[*] --> INTENT_SENDING
INTENT_SENDING --> INTENT_CREATED: creada
INTENT_SENDING --> INTENT_FAILED: rechazo
INTENT_CREATED --> BINS_RECEIVED: BINs
BINS_RECEIVED --> COMPLETE_SENT: completa
BINS_RECEIVED --> COMPLETE_FAILED: sin enviar
COMPLETE_SENT --> BINS_RECEIVED: otra ronda
COMPLETE_SENT --> APPROVED: pagada
COMPLETE_SENT --> REJECTED: rechazada
INTENT_SENDING --> CANCELLED: compensación
INTENT_CREATED --> CANCELLED: compensación
BINS_RECEIVED --> CANCELLED: compensación
COMPLETE_SENT --> CANCELLED: compensación
INTENT_SENDING --> SUPERSEDED: reemplazo
INTENT_CREATED --> SUPERSEDED: reemplazo
BINS_RECEIVED --> SUPERSEDED: reemplazo
COMPLETE_SENT --> SUPERSEDED: reemplazo
Los estados vivos son INTENT_SENDING, INTENT_CREATED, BINS_RECEIVED y COMPLETE_SENT: aquellos en que la billetera todavía puede pagar o contestar. Un índice único filtrado garantiza a lo sumo una intención viva por caja, incluso entre nodos. Cuando un pago pasa a compensación, su intención sale del conjunto vivo en la misma transacción (CANCELLED, o SUPERSEDED si lo reemplazó otro pago), de modo que la caja queda libre al instante; la intención conserva el id de Prisma porque la tarea todavía le debe el DELETE. CANCELLED significa «cancelada por nosotros», no «ya borrada en Prisma».
9. Vencimiento = cancelación y compensación automática
Política (ADR-002): cuando la espera del POS vence sin un resultado final, el pago se trata como cancelado. El gateway cancela la intención en Prisma y responde al POS «denegado». Si la billetera aprueba después, el gateway anula automáticamente el cobro. Es el estilo de GatewayMP, pero con una cola durable en la base y con estados terminales y alertas.
| GatewayMP | GatewayQR | GatewayPrismaQR | |
|---|---|---|---|
| Ante un vencimiento | Cancela o devuelve con un barredor | Responde SINRESPUESTA al POS |
Cancela la intención y responde «denegado» |
| Aprobación tardía | Se compensa | Se rechaza con 504: el cliente puede quedar cobrado sin venta | Siempre se acepta y se aplica (INV-03) |
| Cola de compensación | En memoria, un solo nodo, reintenta sin fin | No hay | Tabla en la base, con lease, reintentos acotados y estado terminal |
Comparación de la arquitectura de reversas (verificada el 2026-10-31)
La tabla anterior resume la política. Esta compara cómo está construida la reversa en los tres sistemas, leída en el código de cada uno:
| GatewayQR | GatewayMP-JH8 | GatewayPrismaQR | |
|---|---|---|---|
| Dónde ocurre la anulación | Sin maquinaria de reversa. La anulación es síncrona dentro del pedido (hasta 60 s). | Marca CANCELAR en la base antes de cobrar; un barredor @Scheduled relee el estado en el proveedor en cada vuelta y reintenta (// TODO: Forever ? en CancelacionesService). |
La compensación se persiste en la misma transacción, antes de cualquier respuesta «sin venta»; la ejecuta una tarea con lease. |
| Qué se guarda | Nada. La espera es un mapa en memoria. | La marca en la base, pero la cola de trabajo está en memoria de cada nodo y solo se recarga al arrancar. | Tarea, reversa y cobro en la base; ningún estado en memoria decide dinero. |
| Varios nodos | No aplica | Sin lease ni alertas: cada nodo trabaja su propia cola. | Lease por tarea, tomado en hora de la base. |
| Reintentos | Ninguno | Para siempre | Con espera creciente y límite; al agotarse, estado terminal y alerta. |
| Antes de reenviar | — | Relee el estado en el proveedor | Consulta a Prisma (GET /annulments o /refunds) antes de reenviar. |
| Alertas y estados manuales | No | No | Marcas de alerta y estados manuales (COMPENSATION_FAILED). |
| Un pago que llega tarde | Se rechaza con 504; el cliente queda cobrado | Se compensa | Siempre se acepta y se aplica (INV-03). |
| Una sola reversa por cobro | No aplica | No se verificó | A lo sumo una reversa activa por cobro, impuesto por índices únicos. |
Idea tomada y diferida: D-136. El barredor de GatewayMP-JH8 tiene algo que a este gateway le falta: seguir mirando una reversa de la que el trabajo ya se rindió. Se propone un barrido de baja frecuencia, con lease, que solo consulta a Prisma las reversas rendidas y liquida las que Prisma ya resolvió, sin reenviar nunca la operación. Queda diferido (D-136); hoy esas reversas se cierran solo cuando llega la notificación tardía de Prisma (INV-03).
Línea de tiempo de un cobro que vence y luego se paga
%%{init: {"sequence": {"wrap": true, "width": 180}}}%%
sequenceDiagram
autonumber
participant POS
participant GW as Gateway
participant PR as Prisma
participant W as Billetera
POS->>GW: POST /api/trxpago
GW->>PR: crear intención
Note over GW: la billetera no responde dentro del tope de espera
Note over GW: una sola transacción en la base: pago a COMPENSATION_PENDING, intención a CANCELLED y tarea de compensación
GW-->>POS: AUTORIZACION_DE_PAGO_DENEGADA y nunca SINRESPUESTA
GW->>PR: DELETE /intentions/{id} desde la tarea con lease
W->>PR: el cliente paga igual
PR->>GW: POST /prisma/v1/payment (notificación tardía)
Note over GW: se guarda y se aplica sin rechazarla (INV-03)
GW->>PR: GET /annulments para consultar antes de reenviar
GW->>PR: POST /forcedannulments
PR->>GW: POST /prisma/v1/annulment
Note over GW: pago a COMPENSATED y reversa COMPLETED
El orden importa y es lo que cumple INV-01 e INV-02: la intención de compensación se escribe en la base antes de que el POS oiga «sin venta», y las tres escrituras (pago, intención, tarea) forman una sola transacción. Si alguna falla, no se prometió nada. Si el nodo muere entre una cosa y otra, otro nodo termina el trabajo porque nada depende de memoria.
Diagrama interactivo. Vencimiento, cancelación del cajero, pago tardío, reintentos y la brecha de la pregunta 24, paso a paso: vencimiento-compensacion.html.
Qué acción corresponde
flowchart TB
T["Tarea de compensación<br/>con lease y reintentos acotados"] --> Q{"¿La billetera ya cobró?"}
Q -- "no" --> D["DELETE /intentions/id"]
Q -- "sí" --> F{"¿La anulación sigue siendo posible?"}
F -- "sí" --> A["Anulación forzada<br/>devuelve también el cashback"]
F -- "no" --> R["Devolución forzada<br/>no devuelve el cashback"]
D --> OK["COMPENSATED"]
A --> OK
R --> OK
A -. "reintentos agotados" .-> X["COMPENSATION_FAILED<br/>y alerta para atención manual"]
R -. "reintentos agotados" .-> X
D -. "reintentos agotados" .-> X
Se prefiere la anulación forzada porque también devuelve el cashback; la devolución forzada solo cuando la anulación ya no es posible (R-10). Antes de reenviar una operación forzada se consulta GET /annulments o GET /refunds, porque Prisma no documenta idempotencia. Los reintentos son acotados y con espera creciente: nunca se reintenta para siempre.
Reglas completas de ADR-002
- Resultado desconocido al crear (D-46). Un timeout, un 5xx o un error de E/S al crear la intención se trata como un vencimiento: en una transacción el pago pasa a
COMPENSATION_PENDING, la intención sale del conjunto vivo y se persiste la tarea; el POS recibe «denegado». Un 2xx que no es 201 es desconocido pero conserva el id de intención que nombró; tras un 201 el id no se pierde salvo que otra intención ya lo tenga. Sin id de Prisma la compensación se apoya en la pregunta 4b o en que «una intención nueva invalida la anterior». - Una reversa por cobro de la billetera (D-79). Las reversas y las tareas se identifican por el cobro (
wallet_charge, elpayment_idde Prisma), no por nuestro pago. El cobro que llevó el pago aAPPROVED, el que el POS vio aprobado, es la venta; todo otro cobro de la misma intención se anula siempre. Cuando la última respuesta que oyó el POS fue «sin venta», se anulan todos los cobros, cada uno con su reversa. La intención de cada reversa se persiste en la misma transacción que registra su cobro (INV-02). - Tarea con lease. Un trabajo en cada nodo toma las tareas vencidas de a una con una sola sentencia (
UPDATE ... OUTPUTconUPDLOCK, READPAST) en hora de la base: una tarea está vencida si estáPENDINGcon su próximo intento cumplido oIN_PROGRESScon el lease expirado (un trabajador muerto). Cada cierre exige ser el dueño del lease; un trabajador que perdió el suyo deshace todo su cierre. Ninguna llamada a Prisma ocurre dentro de una transacción y todas quedan en el registro de cables. - Anulación forzada antes que devolución. Se pregunta a Prisma primero (
GET /annulmentso/refunds) y solo si no la conoce se envía la operación forzada; después se consulta su resultado, y la notificación de Prisma lo cierra antes. v27 identifica la operación forzada por los números del cobro (intención, medio, establecimiento, trace y ticket), no por el id de pago de Prisma: por eso esos números se guardan con el cobro. La devolución forzada se programa solo cuando Prisma dice que la anulación ya no es posible; un rechazo de la devolución o los reintentos agotados terminan enCOMPENSATION_FAILEDcon alerta. - Resultados tardíos de la billetera. Se registran siempre en el pago (id de pago de la billetera, importes, cuotas, medio, código de autorización) sin cambiar lo que ve el POS. Un resultado que no es la aprobación esperada de un pago en
COMPLETE_SENTlleva el pago a compensación, y uno ya cobrado recibe una anulación forzada. Un rechazo nunca aprueba, nunca reclama un id de pago y nunca programa una anulación de dinero que no se cobró. - El dinero de un cobro vuelve a lo sumo una vez. Hay a lo sumo una reversa en curso y a lo sumo una que devuelva dinero por cobro, y dos índices únicos filtrados lo imponen. Una reversa que Prisma completa después de que la marcamos
FAILEDquedaCOMPLETED_LATEy cuenta como la devolución del cobro; si una devolución ya había devuelto el dinero, quedaLATE_AFTER_REFUNDy dispara una alerta para atención manual. trxanulaciones idempotente (AC-23). El POS, el barrido de RouterQR (reintenta cada 5 s hasta recibir 2xx) y la tarea del gateway convergen en una reversa por cobro. La llamada toma primero el bloqueo del pago, así que dos llamadas que se superponen hacen turno y la segunda lee la reversa que la primera confirmó. Responde 2xx (AUTORIZACION_DE_ANULACION_APROBADA) solo cuando la anulación quedó debida de forma durable, escrita en la misma transacción que la decide (INV-02), también para pagos nunca aprobados. Nunca responde ese estado por una anulación que el gateway no puede respaldar (una venta sin cobro registrado, una anulación fallida o una reversa de la que la tarea se rindió sin saber qué hizo Prisma): es un 409 con alerta. Un id que el gateway nunca emitió es un 404.- Cancelación del cajero con el cobro en espera (AC-31). El pago pasa a
COMPENSATION_PENDINGcon el motivo de la cancelación, la intención aCANCELLEDy se persiste la tarea; eltrxpagoabierto termina con esa denegación y una aprobación que llegue después se compensa. - Anulación del cajero de un pago aprobado (AC-24). El gateway siempre intenta la anulación forzada (misma tanda de cierre) y programa la devolución forzada (tanda anterior) solo cuando Prisma dice que la anulación ya no es posible, algo que no se sabe cuando el cajero pide. Por eso responde al POS siempre
AUTORIZACION_DE_ANULACION_APROBADA, el único estado de anulación que el POS toma en este camino. El responsable aceptó esta lectura el 2026-10-28. - Pago tardío de una intención que nunca recibió la intención completa (brecha conocida, pregunta 24). Si la intención se cancela (o se reemplaza) antes de enviar la intención completa, el gateway nunca le asignó
terminal_number,trace_numberniticket_number. Si la billetera la paga igual, el cobro no se puede nombrar a Prisma: la anulación forzada exige método, establecimiento, terminal, traza y ticket (ForcedReversalRequest,WalletCharge.canBeNamed), la tarea de reversa falla y, agotados los reintentos, el pago termina enCOMPENSATION_FAILEDcon alerta, para atención manual (R-22). Qué trae de verdad la notificación de ese pago lo debe decir Prisma. - Reemplazo (AC-32). Un pago nuevo en la misma caja con otro pendiente deja al anterior
SUPERSEDED, entregado a compensación en la misma transacción que abre el nuevo; si la billetera ya lo había cobrado, se anula solo. Un pago que el POS oyó aprobado nunca se reemplaza: ya no tiene una intención viva. Una billetera que paga el QR reemplazado produce un resultado tardío: se registra, se compensa y no se aprueba nunca.
Efecto de cada resultado tardío de la billetera
| Efecto | Cuándo ocurre | Qué hace el sistema |
|---|---|---|
APPROVED |
Es la aprobación esperada de un pago en COMPLETE_SENT |
Guarda el resultado y liquida el pago |
COMPENSATE |
Cualquier otro caso de pago aprobado (importe distinto, estado equivocado, hechos insuficientes) | Guarda los hechos y garantiza la tarea de compensación |
DUPLICATE |
Mismo id de pago de la billetera que el guardado | No cambia nada ni reabre una compensación terminada (AC-10) |
SECOND_WALLET_PAYMENT |
Otro id de pago distinto sobre el mismo pago | Se registra como otro cobro de la billetera y se anula (una reversa por cobro) |
REJECTED / REJECTION_RECORDED |
Rechazo de la billetera | Ver arriba |
WRONG_STATE |
El pago nunca llegó a la billetera | No toma el resultado |
Conciliaciones y controles
- Barredor de esperas huérfanas (D-81). Cada nodo busca pagos que esperan a la billetera cuyo vencimiento pasó hace más de
reaper-gracey los entrega a compensación; es idempotente entre barridas y nodos, y la gracia nunca compite con el nodo que sostiene la espera.
Conciliación de la denegación no persistida (excepción de INV-02) y de la última respuesta del POS (INV-01). Cuando la espera responde «sin venta» sin haber persistido el traspaso, el nodo anota el id en un archivo local durable (uno por nodo, ruta absoluta en producción), porque lo que está caído es la base. La conciliación decide por las marcas de §5:
flowchart TB
A["Pago APPROVED con una denegación<br/>sin intención persistida"] --> B{"¿pos_told_approved_at<br/>está marcada?"}
B -- "sí" --> V["Es una venta:<br/>no se anula"]
B -- "no" --> C{"¿pos_approval_intent_at<br/>está marcada?"}
C -- "sí" --> P["La respuesta pudo salir:<br/>alerta INV02_RECONCILIATION<br/>y revisión humana del diario del POS"]
C -- "no" --> D{"¿Pasaron el vencimiento<br/>más pos-polling-window?"}
D -- "no" --> W["Se espera a la próxima barrida"]
D -- "sí" --> N["Anulación forzada del cobro:<br/>el POS oyó «sin venta»"]
La conciliación solo lee las marcas; las escribe el camino de respuesta al POS. Solo anula cuando las dos están vacías y la ventana de consulta del POS ya pasó (pos-polling-window, unos 5,5 minutos con los perfiles de Almacor; el arranque exige al menos el doble de la lectura de trxpago).
- Control diario de las anulaciones del POS directo (D-S4-11, aceptado el 2026-10-28). Si una
trxanulacionnunca se confirmó en la base (el nodo cayó, o se cortó la conexión antes del commit) el pago quedaAPPROVEDsin nada debido. RouterQR repite el pedido y lo cura; el POS Almacor directo no: tras un timeout consulta, lee un estado aprobado como «anulado por consulta» y cierra la anulación mientras el cliente sigue cobrado. El gateway no puede distinguirlo de una venta que nadie anuló. El procedimiento es una vez por día comparar el diario de anulaciones del POS de cada caja directa con las filas dereversaly reenviartrxanulacionpor cada anulación sin reversa (RUNBOOK §9); además se pidió al equipo del POS repetirtrxanulacionen lugar de confiar en la consulta (R-07). - Alertas que el operador debe cablear:
INV02_UNPERSISTED_DENIAL,INV02_RECONCILIATION,POS_APPROVAL_UNRECORDED,POS_APPROVAL_DEFERRED,POS_APPROVAL_DEFERRED_UNNOTED,POS_APPROVAL_WITHHELD,REVERSAL_LATE_AFTER_REFUND,ANNULMENT_NOT_POSSIBLE,ORPHAN_WAIT_NO_INTENTION,STATUS_OF_ANOTHER_INTENTIONySTATUS_OF_ANOTHER_CHECKOUT, además de toda tarea enCOMPENSATION_FAILED(RUNBOOK §3 y §9). Cada líneaERRORdel código empieza con un marcador estable y tiene su entrada en el RUNBOOK; una prueba (ErrorMarkersDocumentedTest) lo verifica.
10. Seguridad
Invariantes
La CONSTITUTION fija reglas que ninguna ADR, especificación o implementación puede violar: una violación es un hallazgo BLOCKER, nunca un compromiso.
| Invariante | Resumen |
|---|---|
| INV-01 | Si al POS se le dijo «no se hizo» o el POS canceló, el cliente no queda cobrado: compensación automática. Cuenta la última respuesta que el POS oyó: si alguna vez se le dijo «aprobado» (en trxpago o en la consulta) es una venta y nunca se compensa como «sin venta»; el gateway lo registra de forma durable (pos_told_approved_at). |
| INV-02 | La intención de compensación se persiste antes de la respuesta «sin venta» y sobrevive a reinicios. Excepción (2026-10-04): si la base no se alcanza desde el nodo durante todo el tiempo que queda antes de la lectura del llamador, ese nodo puede responder «sin venta» sin intención persistida. A cambio, pasado el vencimiento una aprobación nunca aprueba (se registra y se compensa), y una aprobación confirmada antes por otro nodo la encuentra la conciliación de S4, que la compensa solo si el POS nunca oyó «aprobado»; cada caso dispara una alerta que nombra el pago. |
| INV-03 | Una notificación tardía de Prisma siempre se acepta y se aplica. |
| INV-04 | importe + importe_recdesc == importe_final al centavo. |
| INV-05 | trace_number y ticket_number únicos y sin huecos por terminal, también bajo concurrencia y con varios nodos. |
| INV-06 | El POS nunca registra una venta QR por un importe distinto del cobrado; si no puede imputar, falla y se revierte (el código vive en los repositorios del POS). |
| INV-07 | Secretos y números completos de tarjeta nunca se registran ni se versionan. |
| INV-08 | Los callbacks fallan cerrados: apikey ausente o incorrecta se rechaza, con comparación en tiempo constante. |
| INV-09 | Ninguna entidad JPA se serializa en un endpoint: solo DTO explícitos. |
| INV-10 | El TLS saliente siempre se valida; no hay certificados de confianza total. |
| INV-11 | La API del POS escucha solo en la dirección del lado VPN. |
Mecanismos
- Apikey de callbacks (INV-08, AC-09). Un filtro cubre todo lo que cuelga del prefijo, de modo que un callback nuevo nace protegido. Acepta una lista de claves para rotar sin cortes. La clave recibida y las configuradas se reducen con SHA-256 y se comparan con
MessageDigest.isEqual(tiempo constante, sin filtrar el largo), todas, sin detenerse en la primera coincidencia. Una clave ausente, vacía o incorrecta, o ninguna clave configurada, responde403 {"message":"Invalid authentication credentials"}; el arranque ni siquiera procede sin clave en producción. SoloGET <prefijo>/pingqueda abierto. Un callback rechazado no se guarda, para que nadie pueda llenar la base. El arranque rechaza una clave débil (menos de 32 caracteres, con espacios en los bordes o caracteres de control) y el mensaje nombra la propiedad, nunca el valor. - Rotación de la clave de callbacks: (1) configurar
api-keys: <actual>,<siguiente>y reiniciar; (2) entregar a Prisma la clave siguiente; (3) cuando Prisma la usa, dejarapi-keys: <siguiente>y reiniciar. Entre los pasos se aceptan las dos. - Buzón de notificaciones y huella HMAC. El cuerpo se lee una sola vez, tal como llegó, y se guarda enmascarado antes de responder (INV-03).
body_hashes un HMAC-SHA256 con un secreto del servidor: el cuerpo guardado está enmascarado, y un SHA-256 simple permitiría a quien tenga la tabla confirmar una conjetura del original. Un cuerpo duplicado se almacena ya terminado conoutcome = DUPLICATEy solo queda una fila sin procesar por callback distinto, incluso con diez entregas simultáneas. - Enmascarado antes de insertar (INV-07, AC-27). Aplica a
wire_log,inbound_notificationybins_snapshot. Uncard_numberopanconserva sus últimos cuatro caracteres; unaapikey,authorization,password,secretotokenpasa a***; cualquier racha de 13 o más dígitos se oculta, también si está agrupada. Un cuerpo que no es JSON se enmascara como texto. Las cabeceras nunca forman parte de un registro, así que laapikeyno puede guardarse. - TLS saliente siempre validado (INV-10). No existe ningún gestor de confianza ni verificador de nombre de host propio, y una regla ArchUnit falla si aparece uno (también
System.setProperty, que podría apagar la verificación de toda la JVM). El arranque rechaza una JVM iniciada conjdk.internal.httpclient.disableHostnameVerification, y el RUNBOOK trae la verificación de los parámetros del servicio. El TLS hacia la base es una guarda invertida: salvo enlocalytest, se rechazatrustServerCertificateverdadero y unencrypten falso. - Sin entidades en el cable (INV-09). Los DTO se arman a mano y una regla de arquitectura lo exige.
- Sin estado en memoria que decida dinero. Y cada operación a Prisma queda en el registro de cables, con el id del pago.
Canal del POS
El DOS POS no autentica ni cifra. Si la VPN falta para alguna sucursal, o el puerto del POS se expone a internet, quien lo alcance podría invocar trxanulacion y forzar una anulación (pagar, llevarse la mercadería y anular desde afuera): R-14, ALTO hasta verificar. Mitigaciones: listener del POS atado solo al lado VPN y con guardas de arranque; callbacks en un listener público aparte; lista de IP de origen por comercio dentro de la VPN (opcional, ADR-004); alertas ante anulaciones inusuales.
Reglas de arquitectura (ArchUnit)
El dominio no depende de Spring, JPA ni Jackson; el dominio y la aplicación nunca leen el reloj del sistema (usan un Clock inyectado); application no depende de los adaptadores ni de ningún framework web; los adaptadores de entrada no dependen de los de salida, no tocan el almacenamiento y no exponen entidades JPA ni el registro que lleva un hash de contraseña; los resultados de la billetera y los cobros se escriben solo por WalletResults; no existen gestores de TLS de confianza total; cada invariante tiene al menos una prueba que lo nombra.
11. Datos
El esquema completo se escribió de una vez (V1__baseline.sql, 19 tablas), de modo que cada slice agrega comportamiento y no tablas. Primero la configuración (comercio, sucursal, caja, terminal, planes):
erDiagram
merchant ||--o{ branch : "tiene"
branch ||--o{ checkout : "tiene"
checkout ||--|| terminal : "una"
merchant ||--o{ establishment : "por medio"
merchant ||--o{ merchant_payment_method : "acepta"
merchant ||--o{ installment_plan : "planes"
branch ||--o{ installment_plan : "plan propio"
merchant {
bigint id PK
string name UK
string cuit UK
string cbu
string mcc
}
branch {
bigint id PK
bigint merchant_id FK
int number
string branch_code
}
checkout {
bigint id PK
bigint branch_id FK
int number
string checkout_code
}
terminal {
bigint id PK
bigint checkout_id FK
string terminal_number UK
bigint trace_seq
bigint ticket_seq
}
establishment {
bigint id PK
bigint merchant_id FK
int payment_method_id
string establishment_id
}
installment_plan {
bigint id PK
bigint merchant_id FK
bigint branch_id FK
int payment_method_id
int quantity
decimal adjustment_pct
}
Después el flujo de pago, donde está el dinero:
erDiagram
checkout ||--o{ payment : "recibe"
terminal ||--o{ complete_snapshot_method : "numeros"
payment ||--o{ intention : "intenta"
payment ||--o{ wallet_charge : "cobros"
intention ||--o{ wallet_charge : "cobros"
intention ||--o{ bins_snapshot : "BINs recibidos"
intention ||--o{ complete_snapshot : "rondas"
complete_snapshot ||--o{ complete_snapshot_method : "medio y BIN"
payment {
bigint id PK
bigint checkout_id FK
string state
decimal amount
decimal adjustment_amount
decimal final_amount
datetime wait_deadline_at
datetime pos_approval_intent_at
datetime pos_told_approved_at
bigint version
}
intention {
bigint id PK
bigint payment_id FK
bigint prisma_intention_id UK
string integrator_intention_id UK
string state
}
wallet_charge {
bigint id PK
bigint payment_id FK
bigint intention_id FK
bigint prisma_payment_id
bit sale
bigint trace_number
bigint ticket_number
}
bins_snapshot {
bigint id PK
bigint intention_id FK
string wallet
}
complete_snapshot {
bigint id PK
bigint intention_id FK
int round
}
complete_snapshot_method {
bigint id PK
int payment_method_id
string bin
bigint trace_number
bigint ticket_number
}
Lo que sirve para auditar y recuperar. Una reversa pertenece a un cobro de la billetera y una tarea trabaja una reversa o cancela una intención:
erDiagram
payment ||--o{ reversal : "reversas"
wallet_charge ||--o{ reversal : "devuelve"
reversal ||--o| compensation_task : "la trabaja"
payment ||--o{ compensation_task : "compensacion"
payment ||--o{ inbound_notification : "callbacks"
payment ||--o{ wire_log : "llamadas"
reversal {
bigint id PK
bigint payment_id FK
bigint charge_id FK
string type
string triggered_by
string state
}
compensation_task {
bigint id PK
bigint payment_id FK
bigint reversal_id FK
string kind
string state
string lease_owner
datetime lease_until
int attempts
}
inbound_notification {
bigint id PK
string type
string body_hash
datetime processed_at
string outcome
}
wire_log {
bigint id PK
bigint payment_id FK
string operation
string direction
}
Y lo que usa la consola, sin relación con el flujo del dinero:
erDiagram
admin_user {
bigint id PK
string username UK
string password_hash
string role
bit enabled
int failed_attempts
datetime locked_until
}
admin_audit {
bigint id PK
datetime occurred_at
string actor
string action
string entity_type
string before_state
string after_state
}
La base impone en el motor las reglas que el dominio también aplica:
| Restricción | Qué garantiza |
|---|---|
ux_intention_one_live_per_checkout |
A lo sumo una intención viva por caja, aun con varios nodos. |
ux_intention_prisma_id |
Un id de Prisma no puede pertenecer a dos intenciones. |
uq_wallet_charge y ux_wallet_charge_one_sale_per_payment |
Un cobro de la billetera se registra una vez por intención y, de todos los de un pago, a lo sumo uno es la venta. |
ux_reversal_one_active_per_charge |
A lo sumo una reversa en curso por cobro: POS, RouterQR y la tarea convergen. |
ux_reversal_one_money_returning_per_charge |
A lo sumo una anulación o devolución que devuelva dinero por cobro: el dinero vuelve una vez. |
ux_compensation_task_one_active_cancel_per_payment y ux_compensation_task_one_active_per_reversal |
A lo sumo una cancelación activa por pago y una tarea activa por reversa. |
ck_compensation_task_lease |
Una tarea está IN_PROGRESS exactamente cuando tiene dueño y vencimiento de lease. |
ck_payment_amounts |
amount + adjustment_amount = final_amount (INV-04). |
ck_payment_settled_needs_result |
Un pago aprobado, anulado o devuelto siempre tiene importe final, medio y cuotas. |
uq_complete_snapshot_method_trace y _ticket |
Una terminal nunca emite dos veces el mismo trace o ticket (INV-05); topes de 10 y 6 dígitos. |
uq_admin_user_username y ck_admin_user_role |
Un usuario de la consola por nombre y solo los roles ADMIN y OPERATOR. |
Convenciones: dinero en DECIMAL(13,2) y porcentajes en DECIMAL(7,4), nunca punto flotante; marcas de tiempo DATETIME2(3) en UTC; documentos JSON en NVARCHAR(MAX) con ISJSON; columnas version para el bloqueo optimista; la tabla de notificaciones no tiene ninguna restricción de tipo, porque nunca puede rechazar una escritura. Hay un orden de bloqueo único: pago, luego intención, luego cobro, reversa y tarea; una transacción elegida víctima de un deadlock se repite hasta tres veces.
V1__baseline.sql es editable hasta el primer despliegue fuera de desarrollo; desde la primera versión liberada queda congelada y los cambios van en V2 en adelante (PLAN.md, RUNBOOK §6).
12. Emulador de Prisma
El módulo prisma-emulator reproduce la API de Prisma v27 y su billetera. Es una biblioteca para las pruebas del gateway (se inicia en proceso) y una aplicación ejecutable (el jar -exec). No debe confundirse con emulador-qr.html, el simulador visual de los tres actores.
flowchart LR
T["Pruebas del gateway<br/>en proceso"] --> E
H["Desarrollador<br/>jar ejecutable, puerto 9090"] --> E
E["prisma-emulator<br/>API de Prisma v27 · billetera simulada<br/>inyector de fallas · API de control /emulator"]
G["GatewayPrismaQR"]
G -- "llamadas salientes" --> E
E -- "callbacks con la apikey del gateway" --> G
Lado Prisma: aplica las reglas de v27 — campos obligatorios, bins_max_quantity = 99, 201 con intention_id y qr_raw, errores 400 y 403 con su forma — en POST /largeaccounts/intentions, PUT /largeaccounts/intentions/complete (204; 404 si la intención no está creada, la billetera no envió BINs o pasaron los 27 s; exige 1 cuota y el medio 112), DELETE /intentions/{id}, GET /payments/qr, /annulments, /refunds, POST /forcedannulments y /forcedrefunds. La apikey se verifica con 403. Donde v27 calla, el emulador elige el comportamiento más seguro y es configurable.
Lado billetera: POST /emulator/scenarios escanea la última intención de una caja, llama al callback de BINs, espera la intención completa, elige un plan, paga y notifica.
| Escenario | Qué hace la billetera |
|---|---|
APPROVED |
BINs, intención completa, pago aprobado y una notificación |
REJECTED |
Pago rechazado por el autorizador y una notificación |
MISSING_BINS |
Escanea, pero nunca envía los BINs |
MISSING_NOTIFICATION |
Paga y nunca notifica: el gateway debe preguntar con GET /payments/qr |
DUPLICATE_NOTIFICATION |
Envía la notificación dos veces |
LATE_NOTIFICATION |
Notifica con retraso |
LATE_PAYMENT_AFTER_CANCEL |
Paga una intención que el gateway ya canceló: el cobro tardío que INV-01 compensa |
APPROVED_AMOUNT_MISMATCH |
Paga el plan que eligió, pero un centavo más que el total ofrecido: el gateway no debe aprobarlo |
APPROVED_UNOFFERED_PLAN |
Paga en una cantidad de cuotas que la intención completa nunca ofreció |
DOUBLE_CHARGE |
Cobra una segunda vez una intención ya pagada, con los mismos números de trace y ticket |
DOUBLE_CHARGE_OWN_NUMBERS |
El mismo segundo cobro, pero con números de trace y ticket propios |
La anulación y la devolución forzadas las termina el propio emulador tras un retardo y las notifica (POST /emulator/reversals/{intención}/{tipo} las termina a mano, también rechazadas). GET /emulator/catalog lista, solo de lectura, cada escenario, operación y modo de falla con su descripción; la consola lo muestra únicamente en una máquina de desarrollo (§13).
Inyección de fallas (POST /emulator/faults, por operación y con un contador): STATUS (5xx; con executeAnyway la intención se crea y solo se pierde la respuesta, el resultado desconocido de ADR-002), CONFLICT (409), DELAY, TIMEOUT, GARBAGE_ID, y tres fallas de transporte que ejecutan la operación primero: STALL_AFTER_HEADERS (cabeceras de inmediato y cuerpo tarde), RESET_AFTER_REQUEST (cuerpo anunciado y cortado) y HUGE_BODY (una respuesta válida de 2 MiB).
Brecha conocida del emulador. El escenario LATE_PAYMENT_AFTER_CANCEL con la intención cancelada antes de la intención completa notifica el pago sin terminal_number, trace_number ni ticket_number (sí envía payment_method_id y un establishment_id por defecto). El gateway no puede armar la anulación forzada, que los exige (ForcedReversalRequest), y el pago termina en COMPENSATION_FAILED (§9). La prueba s4_theLatePaymentOfAnIntentionThatNeverGotItsPlansHasNoNumbersToCarry fija este comportamiento y el caso del banco de pruebas no afirma la compensación final. Si el gateway ya había enviado su intención completa, el cobro tardío sí lleva los números del plan elegido. Qué hace Prisma de verdad es la pregunta 24.
Reglas de fidelidad: los BINs se marcan como reenviados antes de llamar al gateway; una billetera no paga una intención cancelada o reemplazada (salvo el escenario explícito de pago tardío); GET /payments/qr informa annulled o refunded solo cuando la reversa terminó. Modos estrictos opcionales (reject-duplicate-integrator-id, alphanumeric-codes-only, dashed-cuit-only) cubren los puntos donde v27 es ambigua.
Cómo ejecutarlo
mvn -q -pl prisma-emulator package -DskipTests
java -jar prisma-emulator/target/prisma-emulator-<versión>-exec.jar --emulator.api-key=<clave>
Escucha en el loopback, puerto 9090 (--server.port= lo cambia; --server.ssl.* activa HTTPS). Para manejar el gateway a mano:
- Apuntar el gateway al emulador:
gateway.prisma.base-url=http://localhost:9090ygateway.prisma.api-key=<clave>, con el perfillocal. - Decirle a la billetera dónde están los callbacks:
PUT http://localhost:9090/emulator/gateway {"callbacksUrl":"http://localhost:8443/prisma/v1","apiKey":"<clave de callbacks>"}. - Tras un
trxpagoque creó la intención:POST /emulator/scenarios {"cuit":"..","branch":"..","checkout":"..","outcome":"APPROVED"}. GET /emulator/scenarios/{id}devuelve el rastro del escenario yGET /emulator/requestslo que recibió Prisma.
Simulación local y banco de pruebas
Para no armar todo a mano, tools\local-sim\sim.ps1 up -FastWaits levanta el gateway (perfil local) y el emulador en el loopback, sin tráfico saliente, con la base descartable GatewayPrismaQR_SIM que se recrea en cada corrida, y deja al emulador apuntando a los callbacks del gateway. -FastWaits acorta las esperas del gateway (la espera del POS pasa de 45 s a 15 s y la lectura del llamador de 59 s a 25 s) para que los casos que esperan el vencimiento terminen en unos 15 s. La simulación llegó con el PR #11 y -FastWaits con el PR #13. El banco de pruebas de la consola (§13) trabaja sobre esta simulación. Detalle en tools/local-sim/README.md y guía visual en emulador-qr.html.
13. Consola de administración
La consola es una aplicación React de una sola página (console/) más una API (/admin/api/v1), servidas por el tercer listener del gateway (§3). Es la única superficie para configurar comercios, planes y usuarios, y para ver lo que pasó con un pago. El camino del dinero no depende de ella: ningún pedido del POS ni de Prisma lee una sesión ni una tabla de administración (ADR-005, INV-03).
flowchart TB
R["Petición a /admin"] --> L{"Filtro de separación<br/>por puerto"}
L -- "otra ruta" --> N404["404"]
L -- "/admin" --> A{"¿Origen loopback, o allow-remote<br/>con HTTPS?"}
A -- "no" --> F403["403"]
A -- "sí" --> S{"¿Sesión válida?<br/>el usuario se relee en cada pedido"}
S -- "no" --> U401["401"]
S -- "sí" --> C{"Si cambia estado:<br/>¿cabecera CSRF igual a la cookie?"}
C -- "no" --> C403["403"]
C -- "sí" --> RL{"Rol del endpoint"}
RL -- "OPERATOR en una escritura" --> R403["403"]
RL -- "permitido" --> OK["Se atiende<br/>y toda escritura se audita<br/>en la misma transacción"]
Usuarios y acceso
- Usuarios propios en la base (
admin_user), con hash adaptativo: BCrypt con costo 12, guardado con el prefijo del algoritmo, de modo que se puede cambiar de algoritmo o de costo sin migración y cada usuario se rehashea en su próximo ingreso. Argon2id queda diferido porque exige una librería nueva (D-S5-4). La política pide entre 12 y 72 bytes y rechaza una clave igual al usuario. - No hay usuario ni clave por defecto. El primer
ADMINsale de un comando de un solo uso (clave desde una variable de entorno del proceso o un aviso en terminal, nunca un parámetro) que se niega a correr si ya existe unADMINhabilitado (RUNBOOK §12). - Sesión: un login JSON abre una sesión HTTP con cookie
HttpOnly,SameSite=Strict,Securesobre HTTPS, vencimiento a los 30 minutos de inactividad y cambio de identificador al ingresar. En cada pedido se relee el usuario: uno deshabilitado queda afuera al siguiente clic y un rol cambiado rige al instante. - CSRF con cookie más cabecera en todo pedido que cambia estado, el login incluido.
- Bloqueo: 5 claves erróneas seguidas bloquean al usuario 15 minutos, juzgado con la hora de la base; un usuario desconocido, una clave errónea, un usuario deshabilitado y uno bloqueado reciben el mismo error. A lo sumo 4 claves se hashean a la vez: el resto recibe un 503 antes de poder arruinar el camino del dinero.
- Dirección: loopback por defecto. Una dirección que no es loopback se rechaza al arrancar salvo
allow-remote=truey HTTPS; un proxy inverso en el mismo servidor pasaría el control de origen, así que no se debe poner uno delante (D-S5-8).
Roles
| Rol | Puede |
|---|---|
ADMIN |
Todo: la configuración (comercios, sucursales, cajas, terminales, establecimientos, medios aceptados), los planes (crear, editar, deshabilitar, borrar) y el simulador, los usuarios, la búsqueda de pagos con su rastro, el tablero, la auditoría y, en una máquina de desarrollo, el catálogo del emulador. |
OPERATOR |
Solo lectura: la búsqueda de pagos con su rastro, el tablero, los planes y el simulador, y su propia sesión y clave. |
El servidor aplica el rol en cada endpoint, sea lo que sea que muestre la consola; una prueba recorre todos los endpoints y verifica el acceso anónimo, de OPERATOR y de ADMIN.
Qué ofrece
- Tablero (ambos roles): pagos del día comercial por comercio y estado (la zona de los comercios, no el día UTC), tareas de compensación pendientes y fallidas (y de ellas las que devuelven dinero a un cliente), buzón sin procesar o abandonado, pagos vencidos sin traspaso (la señal que la base puede mostrar de la excepción de INV-02), llamadas a Prisma de la última hora con sus fallas, y la tasa de aprobación (pagos que la billetera cobró sobre los que terminaron en un sí o en un no; con nada contestado muestra un guion, nunca 0 %).
- Búsqueda de pagos y rastro: filtros por comercio, sucursal, caja, estado y días; el rastro muestra los cobros de la billetera (con el que el POS vio aprobado marcado como venta), cada reversa con el cobro que devuelve, las tareas con su clase, las notificaciones y el registro de cables (los 500 más nuevos de cada lista, enmascarados).
- Configuración: alta, edición y baja de comercios (el MCC se carga a mano y solo se valida que tenga 4 dígitos, §4), sucursales, cajas, terminales (cuyos contadores de trace y ticket son de solo lectura), establecimientos y medios aceptados. Lo que tiene dependientes se deshabilita en lugar de borrarse. Un terminal que ya numeró una oferta no se renombra ni se borra (INV-05). El CUIT de un comercio, el código de una sucursal y el de una caja no se cambian (409) mientras algún pago suyo no haya terminado o tenga una reversión o una tarea de compensación abierta, porque las notificaciones y las anulaciones se correlacionan con esos valores (D-126).
- Planes (ambos leen,
ADMINescribe): el ABM de los planes del comercio. Cada alta o cambio usa las mismas reglas del motor (un recargo de una cuota, tasas incoherentes, un descuento del 100 %, un código MiPyME con cuotas equivocadas), con el mensaje en castellano y el campo del formulario. La consola rechaza dos planes que empatan (AC-13) con un 409 que nombra el plan en conflicto; la comprobación y la escritura ocurren bajo un bloqueo del comercio, de modo que dos altas simultáneas no pasan las dos. Es más estricta que el motor en un caso: rechaza también un empate que otro plan más específico dejaría sin efecto, para que el conjunto guardado nunca pueda hacer fallar una oferta. - Simulador de planes (ambos roles, solo lectura): dado un comercio, un BIN y un importe (y, si se quiere, sucursal, medio, banco y fecha) muestra lo que la billetera recibiría y por qué cada plan se ofrece o no (
OFFERED,NOT_OFFERABLE,OUTRANKED,TIE, fuera de vigencia, otro día, bajo el mínimo, otra sucursal, etcétera). No es una copia del motor: arma la oferta con las mismas clases que el trabajador de BINs, y una prueba compara, plan por plan y al centavo, su resultado con la intención completa que recibió la billetera emulada. - Auditoría (solo
ADMIN): lectura filtrada y paginada deadmin_audit. Toda escritura de la consola se audita en la misma transacción que la escritura (quién, qué, cuándo, antes y después en JSON); también los ingresos, los bloqueos, los cambios de clave y el alta del primerADMIN. La auditoría nunca guarda una clave, un hash ni una apikey (INV-07). - Emulador (solo
ADMIN, solo en desarrollo): lista el catálogo del emulador de §12. Está apagado salvo que haya una dirección configurada, y el arranque se rehúsa si esa dirección aparece fuera de los perfileslocalytest. - Banco de pruebas (cockpit), solo en desarrollo (PR #12 a #20, integrados el 2026-11-14): una página de la consola que maneja la simulación local de §12. Muestra el estado de las vías (POS, emulador y gateway), tiene un panel manual del POS y un banco de 15 casos confirmados (aprobado, rechazado, notificación perdida, cancelación del cajero durante la espera, pago tardío tras una cancelación, notificación duplicada, cobro doble, falla al crear la intención y otros) con «ejecutar todos» y un veredicto por afirmación. Se sirve solo con el servidor de desarrollo de Vite de
console\, y una guarda hace fallar la compilación si algo del cockpit llega a producción. Capturas en cockpit-screens/; guía en emulador-qr.html.
Límites conocidos
- La sesión vive en la memoria de un nodo (D-S5-7): con dos nodos, el operador se queda en el que lo ingresó.
- El bloqueo es por usuario, no por origen (D-S5-3, D-S5-12); la defensa es la dirección loopback y el cortafuegos.
- La consola se sirve desde un directorio (
gateway.admin.console-dir) y su compilación es un paso aparte: la CI y la publicación todavía no la construyen ni la incluyen (D-S5-6). - La auditoría no tiene regla de retención (D-S5-5) y la consola no inicia escenarios del emulador (D-S5-13).
14. Calidad y metodología
Lo medido
Solo hechos medidos o leídos de un documento; lo que no se midió sobre el árbol integrado dice «ver CI» o «pendiente». Las cifras de pruebas, cobertura y lectura de preparación son de la corrida TR-1 del 2026-11-15; la mutación (PIT) es la del 2026-10-29.
| Medida | Resultado | Fuente |
|---|---|---|
| Criterios de aceptación cerrados | 28 de 30 aplicables (AC-11 y AC-12 retirados con el Modo A); sin marcar: AC-15 y AC-16, que tienen pruebas en verde y esperan a Prisma. El ledger mide 30 de 32 | ACCEPTANCE.md, QA-LEDGER.json |
| Pruebas automatizadas (unitarias e integración contra SQL Server) | 4149 en verde, sin fallas ni omitidas: gateway 3226 unitarias y 799 de integración, emulador 124 (corrida TR-1 del ledger, 2026-11-15, commit 563f136) |
QA-LEDGER.json; mvn -q -DskipITs=false verify |
| Cobertura (gateway y emulador) | 94,58 % en la corrida TR-1 (compuertas: 90 % en el dominio, 80 % en el resto) | JaCoCo en verify; QA-LEDGER.json |
| Lectura de preparación del ledger | 95,8, READY tras la corrida TR-1 (antes: 45,1, NOT READY, porque los informes no nacían de una corrida registrada) | QA-LEDGER.json |
| Mutación del dominio (PIT) | 90,0 % (893 de 992 mutantes muertos; compuerta 80 %), corrida del 2026-10-29 | QA-LEDGER.json, RUNBOOK §7 |
| Hallazgos BLOCKER, CRITICAL o HIGH abiertos | ninguno en los slices convergidos | ledger |
Entradas de ISSUES-DEFERRED.md |
189: D-01 a D-136 y las de cada slice (D-S3: 19, D-S4: 13, D-S5: 21); las cerradas siguen en el archivo y llevan «Closed» en la fila | ISSUES-DEFERRED.md |
| Tablas de la base | 19 | V1__baseline.sql |
| Slices convergidos e integrados | S0, S1, S2a, S2b, S3, S4 y S5 | PLAN.md |
| Modelo formal del ciclo de vida del pago (2026-10-31) | 6 invariantes, 2 propiedades de vivacidad y ausencia de bloqueo, comprobados de forma exhaustiva; antes de la corrección se rompían 3 (D-134, D-132, D-135); con el PR #7 se cumple la de D-134 | docs/modelo/ |
Cambios de medición y de CI desde el 2026-10-28
- AC-07 (2026-11-14, PR #22). El callback de BINs responde en menos de 200 ms en el percentil 95 (antes se afirmaba sobre el máximo de las 48 muestras, que mide a la máquina tanto como al código). Con 48 muestras el p99 es igual al máximo, por eso se eligió el p95; la prueba sigue imprimiendo el máximo. Cambió en
ACCEPTANCE.md,SPEC.mdyCompleteIntentionIT; D-106 queda cerrada. - CI recuperada en
main(PR #21 a #24). Las seis corridas demaindesde el PR #19 terminaron en verde. Las causas de las fallas intermitentes: (1)SeedDevITdejabaSET NOCOUNT ONySET XACT_ABORT ONen conexiones del pool, y las pruebas siguientes veían −1 filas actualizadas (PR #21); (2) AC-07 se medía con el máximo de 48 muestras (PR #22); (3) las pruebas leían las solicitudes que el emulador registra después de responder, así que ahora esperan ese registro antes de afirmar (PR #23 y #24).
Verificación formal
Qué es. Un modelo TLA+ del ciclo de vida de un pago, comprobado con TLC, que recorre de forma exhaustiva todos los caminos posibles: una intención, un cobro de la billetera, dos nodos, dos consultas del POS, dos intentos de compensación y un vencimiento de lease. Cada acción del modelo remite en un comentario a la clase de Java que representa. Se hizo con el skill statechart del repositorio pstack (licencia MIT). Los archivos, las corridas y la forma de repetirlas están en modelo/README.md.
Para qué. Las pruebas ejecutan los caminos que alguien pensó. Los errores de dinero de un sistema con dos nodos, leases y un POS que consulta suelen estar en un entrelazado que nadie pensó. El modelo los busca todos dentro de su alcance.
Qué se cumple.
- A lo sumo una reversa por cobro llega a Prisma, también cuando otro nodo toma el lease.
- No hay bloqueo.
- INV-02, vivacidad: un cobro que no es una venta vuelve a la billetera o una persona recibe una alerta. No es trivial: una mutación que quitó la nota local de D-124 rompió la propiedad.
- INV-01, reglas de programación (el código no programa como «sin venta» la anulación de una venta marcada, y ninguna aprobación sale sin la intención escrita): se cumplen, pero reflejan en buena parte los bloqueos del código.
Qué encontró.
| Hallazgo | Qué pasa | Estado |
|---|---|---|
| D-134 (INV-01, dinero) | La escritura de la intención de aprobación falla y el POS oye «aprobación diferida». El reconciliador programa la anulación, el trabajo se rinde con la reversa en IN_PROGRESS y una consulta tardía escribe la intención, porque recordApprovalIntent solo bloqueaba IN_FLIGHT y DONE (saleReversal informaba FAILED). Prisma la completa más tarde y settleMoneyBack anula una venta que el POS oyó como aprobada. Necesitaba una falla de escritura en la base, Prisma en silencio unos 20 minutos y el cajero reintentando entre 30 y 40 minutos después. Regla integrada: JdbcPosApprovals.recordApprovalIntent rechaza la intención mientras la venta tenga una reversa de la que el trabajo se rindió (SaleReversal.GAVE_UP), pero solo si la intención todavía no estaba registrada. Con la intención ya registrada, el POS sigue oyendo lo que oyó, porque esa reversa solo puede ser la del cajero. |
Corregido en el PR #7 (9c5f619) |
| D-132 | Depende de la pregunta 17g a Prisma: ¿puede una billetera pagar una intención después del DELETE? Si Prisma lo rechaza, el modelo se cumple. |
Abierto, a la espera de Prisma |
| D-135 | Se pierde la respuesta aprobada y no queda ninguna línea de alerta (PosApprovalMarkerFilter). Es la variante sin caída de proceso de D-124. |
Diferido |
Qué no cubre. La anulación del cajero (trxanulacion), la cadena rechazo → devolución, el resultado desconocido al crear la intención, el reemplazo, las fallas al cancelar, PurchaseCheck en UNKNOWN, la caída de un nodo, un segundo cobro, las notificaciones perdidas, el desfase de relojes, las duraciones reales e INV-06 (que es del lado del POS).
Verificación de la corrección. La especificación modela la regla integrada y la corrida 8 comprueba que MarkedSaleKeepsItsMoney se cumple; las corridas 5 a 7 son previas a la corrección y se conservan como evidencia del hallazgo. Con la corrección queda abierto D-135 (diferido) y, si Prisma deja pagar tras el DELETE, D-132.
Cómo se usa. Un camino contraejemplo se reproduce contra el código. Si no se reproduce, es un error del modelo. Cuando cambia el código que una acción representa, se actualiza la especificación y se repiten las corridas.
La vara de calidad (SPEC §3.2)
| Dimensión | Umbral |
|---|---|
| Cobertura de líneas | ≥ 90 % en el dominio (estados, planes, importes, compensación); ≥ 80 % en el resto. Las dos compuertas de JaCoCo hacen fallar la compilación. |
| Mutación (PIT) | ≥ 80 % en el dominio; falla también si no encuentra mutaciones. |
| Arquitectura | ArchUnit en verde: el dominio no depende de Spring, JPA ni Jackson. |
| Hallazgos de revisión | Cero BLOCKER, CRITICAL o HIGH abiertos para integrar. |
| Invariantes | Cada invariante de la CONSTITUTION tiene al menos una prueba que lo nombra. |
| Punta a punta | Un escenario por flujo contra el emulador: pago, vencimiento, cancelación, anulación, devolución, compensación y planes. |
| Rendimiento | Callback de BINs en menos de 200 ms en el percentil 95 e intención completa enviada en menos de 3 s en el percentil 99, contra el emulador. |
Las pruebas de integración corren contra una base separada, GatewayPrismaQR_IT, que se borra en cada corrida; la preparación se niega a limpiar cualquier base cuyo nombre no termine en _IT. No se usa Docker en la máquina de desarrollo. En la integración continua, SQL Server corre en un contenedor con una clave aleatoria por corrida.
La metodología de desarrollo
Especificación primero, ciclos de QA con revisores independientes y un ledger de evidencias medidas:
flowchart TB
S["Especificación<br/>ADR y criterios de aceptación<br/>confirmados por el responsable"] --> I["Implementación<br/>TDD estricto, un slice vertical"]
I --> G["Compuertas medidas<br/>pruebas · cobertura · mutación · ArchUnit"]
G --> R["Revisión independiente<br/>tres miradas en contexto limpio"]
R --> V{"¿Hay hallazgos<br/>BLOCKER, CRITICAL o HIGH?"}
V -- "sí" --> X["Corrección<br/>y nuevo ciclo, máximo 5"]
X --> G
V -- "no" --> D["Lo restante se registra en<br/>ISSUES-DEFERRED con su slice"]
D --> M["Compuerta de integración<br/>aprobación humana"]
- Especificación primero. Cada criterio de aceptación lo propone el agente y lo confirma el responsable; ningún criterio cierra sin una prueba verde que lleve su identificador en el nombre (
ac07_...). Las decisiones de diseño viven en ADR numeradas. - TDD estricto. Ninguna conducta de dinero se escribe sin una prueba que falle primero.
- Slices verticales, cada uno con su rama y su revisión.
- Ciclos de QA. Cada ciclo combina tres miradas independientes y sin contexto compartido: una revisión de código, una revisión adversarial ciega de dos jueces, y una auditoría de mejoras. Un slice converge cuando un ciclo ya no trae hallazgos por encima del umbral; el máximo es de 5 ciclos por slice. Cada slice convergió dentro de ese máximo.
- Compuerta de severidad. BLOCKER, CRITICAL y HIGH bloquean. Todo lo demás se registra en
ISSUES-DEFERRED.md(189 entradas), cada una con el slice que debe cerrarla. - Ledger de evidencias.
QA-LEDGER.jsonregistra cada paso: ciclos, hallazgos, correcciones, mediciones y la lectura de preparación. Los números de esta página salen de mediciones, no de estimaciones. - Nada se publica sin aprobación del responsable.
Operabilidad
Perfil de riesgo C (núcleo de pagos): además de las compuertas, hay una compuerta de operabilidad (flujos de integración continua y de publicación, RUNBOOK y semilla). La publicación solo corre si la integración continua del commit etiquetado pasa completa, incluida la mutación.
15. Estado por slice y hoja de ruta
flowchart TB
subgraph HECHO["Convergidos e integrados"]
direction LR
S0["S0<br/>Esqueleto"] --> S1["S1<br/>Contrato POS"] --> S2a["S2a<br/>Adaptador Prisma<br/>y emulador"] --> S2b["S2b<br/>BINs y respuesta<br/>al POS"] --> S3["S3<br/>Planes"] --> S4["S4<br/>Compensación<br/>y reversas"] --> S5["S5<br/>Consola"]
end
subgraph PEND["Pendiente"]
direction LR
E["Corrida real<br/>con el POS Almacor"] --> A["AC-15<br/>y AC-16"] --> X["Externos<br/>Prisma, VPN, POS"]
end
HECHO --> PEND
classDef done fill:#dff1e3,stroke:#1f6b35,color:#142029
classDef todo fill:#eef1f4,stroke:#55636e,color:#142029
class S0,S1,S2a,S2b,S3,S4,S5 done
class Q,E,A,X todo
| Slice | Contenido | Criterios | Estado |
|---|---|---|---|
| S0 Esqueleto | Proyecto Maven, paquetes hexagonales con ArchUnit, esquema Flyway completo, listeners, JaCoCo y PIT, CI y publicación, semilla, RUNBOOK | AC-28 | Integrado |
| S1 Contrato POS | Normalizador de pedidos (las dos formas), trxid, mapeo de estado, máquina de estados del pago, consulta de estado |
AC-01, AC-02, AC-05 | Integrado |
| S2a Adaptador de Prisma y emulador | Llamada «crear intención» con clasificación del resultado, callbacks con apikey, buzón con duplicados y HMAC, registro de cables con enmascarado, traspaso a compensación, emulador | cierra con S2b | Integrado |
| S2b Flujo completo | BINs → intención completa, notificación → respuesta al POS, espera acotada, marcas de aprobación, trabajador del buzón | AC-03, AC-04, AC-06 a AC-10, AC-27 | Integrado |
| S3 Planes | Planes del gateway, calce de BINs, redondeo del POS, TNA y CFT, MiPyME, cashback | AC-11 a AC-18 (sin marcar: AC-14, AC-15, AC-16) | Integrado |
| S4 Vencimiento, compensación y reversas | Tarea con lease, DELETE, anulación y devolución forzadas, reversa por cobro, trxanulacion idempotente, resultados tardíos, reemplazo, cancelación del cajero, numeración atómica, conciliaciones, caída de nodo |
AC-19 a AC-26, AC-31, AC-32 | Integrado |
| S5 Consola y escenarios | Consola React (usuarios y roles, ABM, planes y simulador, búsqueda de pagos, tablero, auditoría) y catálogo de escenarios del emulador | AC-29, AC-30 | Integrado |
| Posterior a S5: banco de pruebas | Simulación local (tools\local-sim, -FastWaits) y cockpit de la consola con 15 casos confirmados (PR #11 a #20) |
— | Integrado |
Un criterio se marca solo cuando existe una prueba verde que lleva su identificador.
Lo que falta
- Corrida real de punta a punta con el POS Almacor sobre el árbol integrado. La del 2026-10-04 fue sobre S2b y no ejercitó la anulación (el cajero de prueba no la tenía habilitada).
- AC-15 y AC-16: verificar la coherencia de TNA y CFT y esperar la respuesta de Prisma sobre el código MiPyME.
- Imputación del lado del POS: el PR #1 de
tipre/POS_ALMACORestá abierto y sin integrar; faltan las compuertas de despliegue (impresora fiscal sin probar, perfiles 564 a 567, diálogo de carga del medio QR con Rec/Desc) y las pruebas de anulación y reimpresión, que están en prueba (§2). - Prueba de arranque y de espera prolongada del POS en las dos plataformas en uso (§2, R-18 y R-20), y reiniciar el POS antes de las 00:00 mientras la biblioteca TCP no se corrija (R-21).
- Externos (siguiente tabla).
Decisiones y entradas que condicionan la salida a producción
| Qué | Dueño o plazo |
|---|---|
| Respuestas de Prisma a las preguntas abiertas (§17), en especial la 10, y homologación (R-01). Se suman la 23 (alta y forma de mostrar el QR de cada caja) y la 24 (pago tardío de una intención sin intención completa) | Responsable del proyecto (contacto comercial con Prisma) |
| Cobertura de la VPN para cada sucursal (R-14) | Responsable del proyecto |
Versión del POS con imputación de recargos y descuentos (R-04 a R-07). Al 2026-11-15: G-01 corregido en tipre/POS_ALMACOR (rama fix/g01-consulta-amounts); la imputación (recargo = falla explícita, descuento como en DINO, percepciones según Q2) está en el PR #1 (rama feat/qr-imputation), abierto y sin integrar, con resultados en el kit, defectos abiertos y compuertas de despliegue (§2) |
Responsable del proyecto (equipo del POS) |
| Prueba de arranque y de espera prolongada («hold») del POS en las dos plataformas en uso: la imagen VirtualBox de producción con red real y el POS físico, para los tamaños de RAM de las tiendas (R-18, R-20). T-18c necesita una impresora fiscal real | Responsable del proyecto (equipo del POS) |
| Respuesta de Prisma a la pregunta 17g (D-132) | Responsable del proyecto (contacto con Prisma) |
| Mitigar el reloj de la biblioteca TCP del POS: reiniciar el POS antes de las 00:00 (R-21). La corrección real está fuera de este repositorio y del repositorio del POS | Operación (mitigación) y dueño de la biblioteca |
| Nombre público y certificado para los callbacks (R-15) | Responsable del proyecto |
Exportación de dM_Banda y dM_TarPl de cada comercio para cargar sus planes en la consola (R-08) |
Responsable del proyecto (equipo del POS) |
| Tráfico real del POS contra GatewayQR para detectar variantes de contenido (R-11) | Responsable del proyecto |
| Fijar en producción el perfil 36/12/2 y la ventana de consulta según el perfil del POS (RUNBOOK §3) | Operación |
| Cablear las alertas de §9 y ejecutar el control diario de anulaciones del POS directo (D-S4-11) | Operación |
Construir y desplegar la consola, y crear el primer ADMIN (D-S5-6, RUNBOOK §12) |
Antes de la primera versión |
16. Riesgos abiertos
| ID | Riesgo | Nivel | Mitigación |
|---|---|---|---|
| R-01 | La homologación de Prisma (ambiente, URL, apikeys, billeteras de prueba) no está documentada en v27 y no la controlamos. | ALTO | Enviar las preguntas ya; construir y probar contra el emulador propio. |
| R-03 | v27 dice que los servicios están «sujetos a modificación» (p.5). | MEDIO | Adaptador aislado tras un puerto; pruebas de contrato por cada payload. |
| R-04 | El POS descarta en silencio un importe_recdesc positivo (recargo) y registra la venta por el importe original, mientras la billetera cobró más (inferido del código). |
ALTO | Falla explícita más reversa antes de habilitar recargos. Ver POS-IMPUTACION-QR.md §3.2. |
| R-05 | Impresora fiscal: el comando de descuento por QR nunca se validó y el de recargo no existe. | ALTO para ajustes | Validar con el equipo fiscal antes de habilitar ajustes. |
| R-06 | Tratamiento impositivo de un recargo financiero (IVA, percepciones). Para los descuentos con percepción, Q2 se decidió el 2026-10-31 (§2); para el recargo sigue abierto. | MEDIO | Decisión del asesor del comercio. |
| R-07 | Los ajustes (recargos y descuentos) exigen una versión nueva del POS (imputación y recargos). Es una dependencia. Al 2026-11-15 el port a Almacor está en el PR #1 de tipre/POS_ALMACOR (rama feat/qr-imputation), abierto y sin integrar (§2). |
ALTO | Planificar el trabajo del POS en paralelo; probar el gateway con el emulador y un simulador de POS. |
| R-08 | Rangos del POS de más de 8 dígitos no se pueden decidir con el BIN de Prisma; el largo del PAN no está disponible. | BAJO | Relevar las tablas reales; registrar los rangos indecidibles. |
| R-09 | Cliente cobrado sin venta si la billetera aprueba tras un vencimiento, cancelación o «denegado». | ALTO | Compensación automática y durable (§9); control diario de las anulaciones del POS directo (D-S4-11). |
| R-10 | Compensar con una devolución forzada no devuelve el cashback. | MEDIO | Preferir la anulación forzada; confirmar la ventana con Prisma (pregunta 15). |
| R-11 | No hay un corpus de tráfico real POS ↔ gateway; el contrato se valida contra GatewayQR local. | MEDIO | Sumar el traffic.log de producción antes de salir a producción. |
| R-12 | RouterQR tiene dos slots fijos y ningún ruteo por comercio. Resuelto para Almacor; falta confirmar Becerra. | BAJO | Confirmar la topología de Becerra. |
| R-13 | Cadena de timeouts del llamador → gateway: si el gateway espera más que la lectura de quien llama, su respuesta se pierde (con RouterQR, su barrido dispara la anulación). | MEDIO | Espera del gateway menor que esa lectura: con el POS Almacor directo, perfil 36/12/2 sobre una lectura de 50 s; verificar los valores de producción de RouterQR. |
| R-14 | La VPN entre sucursales y servidor central está por verificar; el POS DOS no tiene TLS ni autenticación. | ALTO hasta verificar | Verificar cada sucursal; listener atado al lado VPN; lista de IP de origen; alertas. |
| R-15 | Los callbacks necesitan un nombre público y un certificado TLS en el servidor central; no están definidos. | MEDIO | Definirlos antes de pasar del emulador a Prisma real. |
| R-16 | D-134 (hallado por el modelo formal, §14): una reversa que el trabajo dio por rendida podía completarla Prisma más tarde y anular una venta que el POS oyó aprobada. La ventana está cerrada desde el PR #7 (9c5f619): recordApprovalIntent rechaza la intención mientras haya una reversa rendida y la intención no esté registrada. El residuo es D-136: ninguna tarea vuelve a consultar una reversa rendida, que solo se cierra con la notificación tardía de Prisma o con una persona. |
BAJO | Barrido de baja frecuencia que solo consulta a Prisma las reversas rendidas y liquida las resueltas, sin reenviar nunca (D-136, diferido); la alerta de COMPENSATION_FAILED ya avisa a una persona. |
| R-17 | D-135: se pierde la respuesta aprobada y no queda ninguna línea de alerta (PosApprovalMarkerFilter). |
MEDIO | Diferido; ver §14. |
| R-18 | Fallo de arranque del POS que depende del tamaño de memoria: Fatal error 286.3360 de Phar Lap en el primer DosLoadModule en el kit DOSBox-X, también con los binarios entregados 20261003; causa no identificada. En una copia de la imagen VirtualBox de producción no se produjo (§2). |
MEDIO | Prueba de arranque (BUILD.md del POS) con los binarios finales y la memoria del despliegue; prueba de arranque y de espera en la imagen VirtualBox de producción con red real y en el POS físico antes de salir (§15). |
| R-19 | El DGROUP de POS_MAIN.EXE termina 164 bytes por debajo de 64 KB y dos segmentos de código están a menos de 1,9 KB; el enlazador no avisa si un segmento se envuelve. |
BAJO | Revisar POS_MAIN.MAP (_BSSEND y los segmentos) después de cada cambio; todo texto nuevo como static char _far. |
| R-20 | Congelamiento del POS visto una vez (prueba t12): quedó congelado después del timeout de 50 s de trxpago, con la billetera cobrada y el gateway en APPROVED. Causa desconocida. |
ALTO | Abierto: reproducir y encontrar la causa; la prueba de espera prolongada en las dos plataformas es requisito de salida (§15). |
| R-21 | Reloj de la biblioteca TCP del POS (TITCP, fuera de los dos repositorios): set_timeout y chk_timeout usan la hora de pared como HHMMSS, y pasada la medianoche local un cierre de conexión espera unos 30 minutos. Confirmado en el kit (liberado a los 30:00 y a los 28:27). Es compatible con el congelamiento de R-20 (arranque a las 23:30, congelado a las 00:08), sin que esté confirmado que sea su causa. |
MEDIO | Reiniciar el POS antes de las 00:00; la corrección real (segundos desde la medianoche con control del cambio de día) es del dueño de la biblioteca (§2). |
| R-22 | Un pago tardío de una intención cancelada o reemplazada antes de la intención completa no tiene terminal, traza ni ticket para la anulación forzada: el pago queda en COMPENSATION_FAILED (cliente cobrado sin venta, a resolver a mano). Qué trae de verdad la notificación de ese pago lo dice la pregunta 24. |
MEDIO | Alerta de COMPENSATION_FAILED y atención manual; preguntar a Prisma (pregunta 24); el emulador y la prueba s4_... fijan el comportamiento actual (§9, §12). |
17. Preguntas a Prisma
La lista consolidada tiene 24 preguntas numeradas (41 con sus subpreguntas) y está en PRISMA-PREGUNTAS.md, que es la única lista y al final dice por qué importa cada respuesta. Las que más condicionan el diseño son la 10 (habilita los recargos y descuentos en producción), la 1, la 3, la 4 y 4b, la 5, la 14, la 15 y la 18. Las dos últimas agregadas son la 23 (cómo se da de alta y se muestra el QR de cada caja, impreso o en el pinpad) y la 24 (el pago tardío de una intención que nunca recibió la intención completa, sin terminal, traza ni ticket para la anulación forzada). La 20 incluye los anexos que faltan, entre ellos la lista de MCC válidos.
18. Mapa de documentos
| Documento | Para qué sirve |
|---|---|
| SISTEMA.md / sistema.html | Este documento: el sistema hoy. |
| planes-cuotas.html | Planes, BINs, recargos y descuentos, con simulador. |
| emulador-qr.html | Simulador visual de POS, gateway y Prisma con la billetera, y guía del emulador, la simulación local y el cockpit. |
| system-deck.html | Presentación en dos vías, comercial y técnica, con las métricas del ledger. |
| diagrams/ | Cuatro diagramas interactivos paso a paso (cobro aprobado, vencimiento y compensación, estados del pago, anulación del cajero); las fuentes están en docs/diagrams/ y se regeneran con build.mjs. |
| cockpit-screens/ | Once capturas del cockpit y de la consola. |
| tools/local-sim/README.md | Simulación local de gateway y emulador (sim.ps1, -FastWaits). |
| SPEC.md | Alcance, hechos del POS y RouterQR, compensación, vara de calidad. |
| CONSTITUTION.md | Invariantes INV-01 a INV-11. |
| ACCEPTANCE.md | Criterios AC-01 a AC-32. |
| DOMAIN-MODEL.md | Entidades y reglas. |
| PLAN.md | Slices S0 a S5. |
| RISKS.md | Riesgos con dueño y mitigación. |
| ISSUES-DEFERRED.md | Hallazgos bajo el umbral y su slice. |
| ADR-001 · ADR-002 · ADR-003 · ADR-004 · ADR-005 | Pila, compensación, planes, conexión del POS, consola de administración. |
| CONVENTIONS.md | Convenciones técnicas, contrato del flujo S2, planes, emulador, compensación y consola. |
| RUNBOOK.md | Instalación, configuración, operación, pruebas, CI. |
| PRISMA-PREGUNTAS.md | Preguntas abiertas a Prisma. |
| modelo/README.md | Modelo formal TLA+ del ciclo de vida del pago: alcance, reglas, resultados y cómo correrlo. |
| POS-IMPUTACION-QR.md / pos-imputacion-qr.html | Traspaso para el equipo del POS: cómo imputar el recargo o descuento después del pago. |