GatewayPrismaQR · documentación del sistema · 2026-11-15 · rama main

GatewayPrismaQR

Gateway de cobro QR entre el POS de Tipre y Prisma Gateway QR, como Sistema Propio / Integrador Grande Cuenta (v0.27). Este documento describe el sistema integrado tal como está hoy y distingue lo implementado de lo pendiente.

Presupuesto crítico
27 s BINs → intención completa
Criterios de aceptación
28 de 30 aplicables cerrados
Pruebas y cobertura
4149 pruebas en verde · cobertura 94,58 % · mutación (PIT) 90,0 % en el dominio
Slices integrados
S0 a S5 · QA de integración cerrada (2026-10-28)

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:

  1. El POS pide un identificador de transacción (trxid) y después el cobro (trxpago) por el importe a pagar con QR.
  2. El gateway crea la intención de pago en Prisma. El cliente escanea el QR fijo de la caja con su billetera.
  3. 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.
  4. El cliente elige el plan en la billetera y paga. Prisma notifica el resultado.
  5. 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:

  1. API del POS v1, compatible con el contrato de GatewayQR: POST /api/trxid, POST /api/trxpago, POST /api/trxanulacion, GET /api/trxes/{id}.
  2. Flujo de pago con Prisma: crear intención, callback de BINs, intención completa dentro de 27 s.
  3. 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).
  4. Notificación de pago, consulta de estado y trabajo de conciliación.
  5. Anulación forzada, devolución forzada y cancelación de la intención (DELETE /intentions/{id}).
  6. Cashback (solo Visa Débito, v27 p.97).
  7. Cuotas MiPyME (planes 13 = 3 cuotas y 16 = 6 cuotas) como código de plan.
  8. 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).
  9. 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).
  10. 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):

Fuera del alcance

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

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"
}

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:

  1. La intención va primero. Antes de que salga una respuesta aprobada, pos_approval_intent_at se escribe en su propia transacción corta. Sin intención durable no se dice «aprobado».
  2. La marca de «se le dijo» va después de vaciar la respuesta. pos_told_approved_at se escribe cuando la respuesta ya se escribió completa hacia el POS: el filtro que la registra está fuera del que fija el Content-Length, porque solo allí un flushBuffer() 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).
  3. 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.
  4. Aprobación diferida. Si la intención no se puede escribir, el gateway no dice «aprobado»: responde INTENCION_DE_PAGO_RECIBIDA_APROBADA (statuscode 0) sin ninguno de los campos de la aprobación, en trxpago y en la consulta (alerta POS_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 con AUTORIZACION_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).
  5. 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 trxpago como AUTORIZACION_DE_ANULACION_APROBADA, nunca como venta; y la intención de aprobación se rechaza mientras la venta se anula (alerta POS_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):


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):

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):

  1. Toda salida de trxpago espera hasta un estado final o traspasa a compensación; no existe una salida que deje el pago esperando.
  2. 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.
  3. COMPLETE_SENT y las filas de complete_snapshot se 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.
  4. 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.
  5. 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):

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


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

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

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).


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

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:

  1. Apuntar el gateway al emulador: gateway.prisma.base-url=http://localhost:9090 y gateway.prisma.api-key=<clave>, con el perfil local.
  2. 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>"}.
  3. Tras un trxpago que creó la intención: POST /emulator/scenarios {"cuit":"..","branch":"..","checkout":"..","outcome":"APPROVED"}.
  4. GET /emulator/scenarios/{id} devuelve el rastro del escenario y GET /emulator/requests lo 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

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

Límites conocidos


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

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.

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"]
  1. 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.
  2. TDD estricto. Ninguna conducta de dinero se escribe sin una prueba que falle primero.
  3. Slices verticales, cada uno con su rama y su revisión.
  4. 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.
  5. 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.
  6. Ledger de evidencias. QA-LEDGER.json registra 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.
  7. 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

  1. 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).
  2. AC-15 y AC-16: verificar la coherencia de TNA y CFT y esperar la respuesta de Prisma sobre el código MiPyME.
  3. Imputación del lado del POS: el PR #1 de tipre/POS_ALMACOR está 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).
  4. 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).
  5. 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.