GatewayQR / Billetera Municipal - Presentación del sistema

Documentación del sistema - 2026-11-18

Billetera Municipal en el POS de CYRE

Un gateway de pagos que permite a los terminales de punto de venta de CYRE, en los comercios adheridos al programa municipal de Villa Allende, aceptar la billetera municipal como una tarjeta más.

Cliente

Cordiez / CYRE S.A.

Integrador

Tipre S.A.

Corrida del ledger

20261116-220858

actualizada el 2026-11-18 17:56 UTC

Puesta en producción

Sin fecha definida. No se ha comprometido ninguna fecha (SPEC).

Utilice el selector Comercial / Técnica de la parte superior. Las flechas del teclado permiten avanzar entre diapositivas y la tecla Esc abre el índice.

Comercial 1

Qué hace

La Municipalidad está reemplazando el vale en papel por una billetera digital. Este sistema permite que la caja existente de un comercio acepte esa billetera sin una segunda aplicación de teléfono y sin conciliación manual.

1. La caja muestra un QR

Al momento del pago, el POS de CYRE muestra un código QR por el importe exacto de la venta.

2. El empleado paga

Un empleado municipal lo escanea con la aplicación de billetera de la Municipalidad. Esa aplicación no forma parte de este desarrollo.

3. La caja recibe el resultado

El POS toma conocimiento de que el pago fue aprobado, venció o fue cancelado, y la venta se cierra como con cualquier otro medio de pago.

4. Todo queda registrado

Cada operación se almacena para poder verificarse luego. Una consola web de administración muestra los intentos, las alertas y la configuración de los comercios.

Un pago puede cancelarse desde la caja. Una venta nunca se cancela. Las credenciales municipales del comercio permanecen en el gateway y nunca llegan a la caja.

Comercial 2

Cómo funciona una venta, en términos simples

El cajero iniciael pago QR La caja muestrael QR El empleado escaneay paga La caja confirma,la venta se cierra

Comercial 3

Valor y estado

Terminado y verificado

  • Flujo de pago, manejo de fallas y reglas de tiempos (AC-01 a AC-18, AC-23, AC-25 a AC-30 y AC-33 tildados)
  • Cinco cambios en el POS de CYRE, verificados sobre el binario real del POS en un banco de pruebas, 2026-11-18
  • Runbook (manual de operación) para la instalación, el despliegue y las operaciones

En curso / aún sin tildar

  • Criterios de aceptación de la consola de administración (AC-19, 20, 21)
  • Panel de pruebas de extremo a extremo (AC-22)
  • Pantalla de conciliación diaria (AC-24), condicionada a datos municipales reales
  • Manejo de diferencias de importe e intentos retenidos (AC-31, AC-32)

Fuente: casillas de ACCEPTANCE.md, 26 de 33 tildadas.

Postura frente a los riesgos

  • Todavía no se capturó tráfico municipal real; el comportamiento se apoya en el documento de la API (R-01, Alto)
  • Un pago QR ya abonado no puede revertirse desde la caja; la Municipalidad no ofrece una API de devolución (R-02, Alto)
  • Un reinicio de la caja durante el cierre fiscal puede perder una línea de pago QR abonada (R-09, Alto, POS de CYRE)
  • Una falla en el decodificador Base64 del entorno de ejecución de Java (R-10, Alto, mitigada con un parámetro de arranque hasta instalar el JDK corregido)

Aún no se probó contra el sandbox municipal real ni contra un POS de CYRE real en un comercio. Toda la evidencia del POS proviene de un banco de pruebas en DOSBox-X.

Comercial 4

Calidad de un vistazo

91,4 RELEASE CANDIDATE

Puntaje de preparación de la última medición registrada en el ledger (2026-11-18 02:51 UTC), tomada cuando contabilizaba 29 de 33 criterios; ACCEPTANCE.md tilda 26 a la fecha. Verde es 80 o más. El motivo del tope no se recalculó para esta presentación.

614

pruebas automatizadas, todas aprobadas

Última ejecución registrada, 2026-11-18. 0 fallas, 0 errores, 0 omitidas.

95,98 %

cobertura de código

2.318 cubiertas, 97 no cubiertas (JaCoCo). Umbral: 90 % en dominio, 80 % global.

100+

revisiones independientes

Revisión de código, revisión adversarial por dos jueces ciegos y relevamientos de mejora, registrados en el ledger al 2026-11-18.

0

escalamientos a una persona

El ledger no registra escalamientos abiertos, hallazgos de producción ni solicitudes de cambio de especificación.

Las revisiones se cuentan a partir del ledger; los conteos por herramienta de problemas encontrados y corregidos no se registran en una forma que esta presentación pudiera utilizar.

Comercial 5

Decisiones y dependencias

TemaPor qué importaResponsable
Credenciales de sandbox y muestras de tráfico real (R-01)El gateway se construyó a partir de los ejemplos del documento de la API. Las muestras reales lo confirman.Operador, junto con la oficina de modernización municipal
API de devolución para pagos abonados (R-02)Hoy un pago QR abonado solo puede revertirse manualmente con la Municipalidad.Operador, consultar a la Muni
Notificaciones en tiempo real (R-07)La v1 consulta cada 5 segundos; el aviso instantáneo es parte de la v2 y su interfaz no está especificada.Muni
Reinicio de la caja durante el cierre fiscal (R-09)Posible doble cobro tras una caída entre la aprobación del QR y el fin del cierre fiscal.CYRE (POS)
Actualización del entorno de ejecución de Java (R-10)El servicio se ejecuta con un parámetro que evita el código Base64 defectuoso hasta instalar el JDK corregido; el CPU del servidor determina si la falla puede activarse.Operador, consultar a CYRE el modelo de CPU
Parámetros de despliegue en cada caja (R-08)Una caja con la configuración por defecto abandona cobros QR que aún podían pagarse.Operador, mediante la lista de verificación del runbook

Técnica 1

Arquitectura

POS de CYRE MS-DOS, C++ cambios 1 a 5 (repositorio aparte) gateway (Spring Boot 4.1.1, Java 25) adapter.in.posREST de PAGOQR adapter.in.adminAPI del cockpit + inicio de sesión application + domainciclo de vida del cobro, poller (hilos virtuales)puertos: AttemptStore, MunicipalApi, ... adapter.out.municliente HTTP, X-Api-Key adapter.out.persistenceJDBC, Flyway, registro de mensajes cockpit: React 19 + Vite 8, servido por el gateway bajo /admin API municipalAPI de Cobro v1sandbox / producción SQL Server 2022intentos, eventos, auditoría muni-emulatorsolo banco de desarrollo, jar propionunca se instala en CYRE Navegador de administración (cockpit) - lista de orígenes permitidos obligatoria en producción VPN/MPLS

Técnica 2

Contratos y puntos de integración clave

POS hacia gateway (contrato PAGOQR existente, ADR-001, sin autenticación por diseño en una VPN privada)

OperaciónComportamiento
POST /api/trxidAsigna el identificador local del intento para un comercio + sucursal configurados. Sucursal desconocida: 404 "Sucursal no configurada".
POST /api/trxpagoCrea el cobro municipal y devuelve de inmediato PAGO_ENVIADO junto con el nuevo campo qrdata. Idempotente por id (C4).
GET /api/trxes/{id}Estado actual mapeado al estado de PAGOQR; incluye qrdata mientras el cobro todavía pueda pagarse.
POST /api/trxanulacionCancela un cobro pendiente. Si ya fue abonado, se deniega (no existe API municipal de devolución).

Mapeo de estados que ve el POS

Estado localestado devuelto
CREATING / PENDING / UNCERTAIN / ISSUEDPAGO_ENVIADO (sigue esperando)
PAID, PAID_UNCONFIRMEDPAGO_APROBADO
EXPIRED, CANCELLED, REJECTEDREFUND_DENEGADO con el motivo en mensajevarios
AMOUNT_MISMATCH, CLOSED_BY_ADMINREFUND_DENEGADO "NO cobrar de nuevo"

REFUND_DENEGADO es deuda heredada: es la única cadena de denegación que el POS respeta hoy.

Gateway hacia la API municipal

Crear, consultar y cancelar con el encabezado X-Api-Key. La clave de idempotencia referenciaExterna = {branch}-{pos}-{trxid} (D1). El entorno (sandbox / producción) se fija por intento y se verifica antes de cada llamada (C6, D5).

Técnica 3

Modelo de estados y tiempos (ADR-003)

ISSUED CREATING PENDING UNCERTAIN PAID EXPIRED CANCELLED PAID_UNCONFIRMED REJECTED (E2/E3) AMOUNT_MISMATCH CLOSED_BY_ADMIN

Simplificado. Los intentos retenidos y los trabados (diferencia de comercio, MUNI_STUCK) solo terminan mediante un cierre por parte del administrador (D7). Los estados finales nunca se reabren.

ReglaValorFuente
Vigencia del cobro (muni.charge-ttl-seconds)120 s (máximo de la API: 600 s)ADR-003
Consulta municipal periódica (muni.poll-interval-seconds)5 sADR-003
Consulta final tras el vencimiento (gracia)10 s; si sigue PENDIENTE, se cancela antes de cualquier denegaciónADR-003, AC-30
Abandono del POS (pos.abandon-after-seconds)20 s sin consulta del POS cancelan el cobroADR-003, AC-13
TIMEOUT_RX del POS (tecla 496)al menos 210, se recomienda 240RUNBOOK sección 6

Técnica 4

Comportamiento ante fallas y reglas inviolables

Casos de falla

  • E1 tiempo de espera al crear: UNCERTAIN, se reintenta con la misma referenciaExterna, el POS ve PAGO_ENVIADO.
  • E2 400/401 municipal: el intento termina, la primera consulta recibe REFUND_DENEGADO con el mensaje municipal; un 401 genera una alerta en el cockpit.
  • E3 se rechaza un cashback > 0.
  • E4 el saldo insuficiente es invisible para el gateway (R-04).
  • Carrera Esc contra el pagador: la cancelación devuelve 409, el intento queda PAID, la consulta final del POS recibe PAGO_APROBADO (AC-23).

Constitución (su incumplimiento es bloqueante)

  • C1 importes al centavo, DECIMAL(12,2)
  • C2 la clave de API nunca sale del gateway ni se registra en logs
  • C3 el número de empleado del pagador nunca se registra en logs
  • C4 nunca un segundo cobro para un mismo trxid
  • C5 nunca denegar mientras el resultado sea incierto
  • C6 nunca mezclar entornos
  • C7 los eventos son de solo incorporación (append-only)
  • C8 sin credenciales por defecto en el cockpit, BCrypt

Valores operativos por defecto

  • Bloqueo del administrador: 5 contraseñas incorrectas, 15 minutos
  • MUNI_STUCK tras 12 rechazos consecutivos, luego se consulta cada 300 s
  • Retención del registro de mensajes: 90 días, depuración cada hora
  • Alertas: PAID_UNCONFIRMED, MUNI_UNAUTHORIZED, AMOUNT_MISMATCH, MUNI_STUCK, ENVIRONMENT_MISMATCH

Técnica 5

Resultados de QA

91,4 RELEASE CANDIDATE

Bloque measured del ledger, 2026-11-18 02:51 UTC. Fase pr-ready, 16 ciclos, sin estancamiento. Motivo del tope: no recalculado para esta presentación (solo captura del ledger).

MétricaValorFuente
Pruebas (última captura 2026-11-18 13:54 UTC)614 en total, 614 aprobadas, 0 fallidas, 0 errores, 0 omitidascaptura del ledger, TR-28 PASSED
Pruebas en la primera captura317 (2026-11-17 02:13 UTC)captura del ledger
Cobertura (JaCoCo, gateway + emulador)95,98 % (2.318 cubiertas, 97 no cubiertas); primera captura 94,15 %captura del ledger
Tamaño11.330 LOC de producción en 267 archivos; 18.454 LOC de pruebas en 134 archivoscaptura del ledger
Pruebas por kLOC (derivado)aproximadamente 54 (614 / 11,33)calculado a partir de las dos filas anteriores
Ejecuciones de pruebas registradas28, todas PASSED (mvn -q -DskipITs=false verify)test_runs del ledger
Revisiones registradasmás de 100 (revisiones de código, judgment-day y mejora)reviews del ledger, 2026-11-18
Controles estáticos6 registrados, el último gate:operabilitysteps del ledger
Escalamientos0ledger
Criterios de aceptación26 de 33 tildados en ACCEPTANCE.mdACCEPTANCE.md

No registrados como números: cobertura de la capa de dominio (el umbral es 90 %, impuesto por una regla de compilación de JaCoCo) y los conteos por herramienta de reportados / corregidos / diferidos / suprimidos.

Técnica 6

Evidencia de extremo a extremo del POS (AC-29, AC-33)

El POS de CYRE es un programa de MS-DOS que ninguna prueba del repositorio puede manejar. Estos criterios se cerraron con ejecuciones registradas del binario real del POS bajo DOSBox-X contra el gateway y el emulador, con la compilación del POS c3ef254 (repositorio S4 del POS). Evidencia: docs/evidence/2026-11-18/.

CasoObservado
QR a partir de qrdata (cambio 1)Se muestra en la pantalla del POS.
Intervalo de consulta desde la tecla 564 (cambio 2)Consultas separadas por 6,4 s con la tecla 564 = 3; por 5,4 s con 564 = 2.
Esc cancela (cambio 3)trxanulacion aprobada, cobro cancelado, intentos en CANCELLED.
Respuesta de trxpago perdida (cambio 5)Primera consulta 11,2 s después del trxpago que traía el QR; pagado. Dos ejecuciones.
Gateway caído al enviar trxpago (cambio 4)El POS reenvió el mismo trxpago; QR; pagado. Tres ejecuciones, un cobro por referencia.
No ejercitadoEl límite de 3 reenvíos.

Compilación: toda la salida de co.bat (POS_MAIN.EXE y cada POS_*.DLL), con hashes en pos_build.txt; fuentes idénticas al commit c3ef254. Se debe entregar el conjunto completo: el cambio 1 desplaza los ordinales de exportación del EXE y las DLL importan por ordinal. El emulador devuelve un cobro existente ante una referencia repetida, por lo que los archivos del emulador por sí solos no pueden mostrar una segunda creación; "nunca un segundo cobro" se apoya en las pruebas de AC-06.

Técnica 7

Riesgos abiertos, expuestos con claridad

R-09 Alto - el reinicio del POS durante el cierre fiscal pierde una línea de pago QR abonada

Observado en el banco de pruebas del POS, 2026-11-18. Se aprobó un pago QR; el POS se reinició durante su cierre fiscal (unos 23 a 25 s en el banco cuando el servicio CAE no está disponible). El ticket restaurado conservó el artículo pero perdió la línea de pago PAGO QR abonada, y el importe se cobró nuevamente.

En producción la ventana se ubica entre la aprobación del QR y el cierre fiscal. La Muni le cobra al pagador mientras el POS vuelve a solicitar el dinero. El gateway mantiene el intento en PAID y el cockpit lo muestra, pero nada impide el segundo cobro en la caja.

Comportamiento preexistente del POS de CYRE, ajeno al gateway. Regla provisoria: tras un reinicio que restaura un ticket con una línea de PAGO QR, verificar en el cockpit si existe un intento PAID antes de volver a cobrar. Próximo paso: reproducir en un POS real y decidir si un ticket restaurado debe releer su estado de PAGO QR. Responsable: CYRE (POS). Sin mitigar.

Presupuesto de abandono de 20 s (RUNBOOK sección 6)

El gateway cancela un cobro pendiente sin consulta del POS durante 20 s; el corte se produce entre los 20 y unos 26 s. Con la tecla 564 = 2, los intervalos medidos o calculados entre consultas son:

  • respuesta perdida: 13 s
  • solicitud perdida tras conectar: 18,4 s
  • falla la conexión: 18,4 s cuando la siguiente conexión es rápida; las conexiones fallidas tardaron de 7 a 11 s en el banco y una conexión a un gateway en arranque tardó 6 s, de modo que un par lento excede el presupuesto
  • dos consultas perdidas seguidas, o una respuesta de trxpago perdida seguida de una primera consulta perdida: unos 24 s, fuera del presupuesto con cualquier configuración

Fuera del presupuesto, una venta cancelada se deniega y el cajero reintenta. Si el pagador ya había pagado, la cancelación se rechaza, el intento termina en PAID_UNCONFIRMED con una alerta en el cockpit, y la siguiente consulta devuelve PAGO_APROBADO. El costo de ciclo de 3,4 s se midió en DOSBox-X; debe medirse nuevamente en el primer POS real.

R-10 Alto - falla de Base64 en el JDK (CVE-2026-114938, "Java4Shell")

Afecta a Temurin 25 en CPU con AVX-512 VBMI. La exposición es baja: el gateway decodifica Base64 solo para sus propias claves, aunque no puede descartarse una biblioteca que decodifique datos provistos por un atacante. Mitigado: el servicio arranca con -XX:-UseBASE64Intrinsics (RUNBOOK 4.3). Siguiente paso: verificar el CPU del servidor e instalar el JDK corregido.

R-01 Alto - sin corpus municipal real

Todos los payloads provienen de los ejemplos del documento de la API. 19 comportamientos son supuestos provisorios marcados como ASSUMPTION (RISKS R-06) en el código y se verificarán contra el sandbox cuando exista.

R-02 Alto - sin API de devolución

Un pago QR abonado no puede cancelarse desde el POS. Se gestiona manualmente con la Muni hasta que exista una API.

Medio / Bajo

  • R-04 el saldo insuficiente es invisible para el gateway
  • R-06 comportamientos indefinidos de la API municipal
  • R-08 cada POS necesita un TIMEOUT_RX de 210 o más y la tecla de consulta configurada
  • R-07 notificación en tiempo real sin especificar (fuera del alcance de la v1)

Atendidos o cerrados

R-03 (tiempo de espera local menor que el vencimiento del servidor) está atendido por ADR-003 y el cambio 3 del POS. R-05 (QR fijo o dinámico) se resolvió el 2026-11-17: QR dinámico.

Técnica 8

Temas diferidos (ISSUES-DEFERRED.md)

Los hallazgos por debajo del umbral de severidad (BLOCKER, CRITICAL, HIGH) no bloquean el ciclo de QA; se registran, no se ocultan.

Técnica 9

Lista de verificación de humo (RUNBOOK sección 5)

Después de cada instalación y actualización, únicamente contra un comercio de SANDBOX. Nunca probar con una clave de producción.

  1. Inicio de sesión en el cockpit desde una dirección permitida; una dirección no permitida recibe 403.
  2. Crear un comercio y una sucursal de sandbox; la clave de API se muestra una sola vez y nunca más.
  3. Contrato del POS contra el sandbox: trxid, trxpago (QR en qrdata), iniciar el bucle de consulta de inmediato, pagar, esperar PAGO_APROBADO.
  4. Cancelar un segundo intento sin pagar dentro de los 20 s de su trxpago: AUTORIZACION_DE_ANULACION_APROBADA.
  5. La sección "Intentos" del cockpit lista ambos intentos con una línea de tiempo de eventos; "Alertas" está vacía.
  6. Una sucursal desconocida responde 404 "Sucursal no configurada".
  7. Desactivar el comercio de prueba o mantenerlo en SANDBOX.
  8. Verificación del gestor de contraseñas en la puesta en producción: nunca debe ofrecer la clave de API del comercio ni la contraseña de otro usuario.

Despliegue del POS, por terminal (sección 6)

Tecla 543 = 1 (cancelación con Esc); tecla 496 al menos 210, se recomienda 240; tecla 497 = 10; tecla 498 = 5; tecla 564 = 2 (o 1); compilación del POS con los cambios 1 a 5 (commit S4 c3ef254 o posterior); cashback deshabilitado para este medio de pago; un pago de prueba más una cancelación con Esc en un comercio de SANDBOX.

Índice de diapositivas