Saltar a contenido

Domain model — GatewayQR-MunicVAllende

Entities

Entity Meaning Key fields
Merchant (Comercio) Merchant adhered to the municipal program. One CUIT per merchant. POS comercio code (unique), CUIT (unique), API key (encrypted at rest, never logged), environment (SANDBOX / PRODUCTION), active
Branch (Sucursal) A merchant location; identified by the POS comercio + sucursal pair. merchant, branch number, active
Payment attempt (Intento de pago) One QR charge attempt requested by a POS. Core aggregate of the gateway. branch, POS number (pos, not registered), trxid (gateway id, unique), nropv and nroticketfiscal (reference only), amount, referenciaExterna; municipal data: idCobro, codigo, expira, idTransaccion, fechaPago, pagadoPorLegajo; local status
Alert (Alerta) Something a human must look at: PAID_UNCONFIRMED, municipal 401 (MUNI_UNAUTHORIZED), AMOUNT_MISMATCH (paid amount differs, C1), MUNI_STUCK (12 consecutive municipal refusals; a final query still answering PENDIENTE does not reset the count), ENVIRONMENT_MISMATCH (merchant environment changed mid-flight, C6). At most one open alert per attempt and type. Shown in the cockpit alert panel (K4). attempt (trxid), type, raised at, resolved at, resolved by (admin user, V3), resolution note; resolving appends an attempt event ALERT_RESOLVED:<type> (source COCKPIT). (origin: agent, confirmed: 2026-11-16)
Admin audit (Auditoría) Insert-only record of every cockpit write (V4). No secrets: a key rotation is recorded as apiKeyRotated=true. admin user, action, target, timestamp, details
Event (Evento) Append-only record of each status change of an attempt. attempt, from status, to status, source (POS / POLLER / COCKPIT), timestamp, municipal error code

Relationships

  • Merchant 1 — N Branch
  • Branch 1 — N Payment attempt
  • Payment attempt 1 — N Event

Model decisions

  • D1 — The idempotency key is the gateway trxid (replaces "N attempts per ticket", 2026-11-16). The POS requests a new trxid for every payment attempt (pos_ctoq.cpp:3636), so referenciaExterna = {branch}-{pos}-{trxid}: retries of trxpago with the same id are idempotent, a new attempt gets a new charge, and the municipal idempotency never returns an expired charge. nroticketfiscal is NOT a key: it is a predicted number (pos_mppo.cpp:3599-3602) and repeats across CAE and CAEA invoicing (operator, 2026-11-16). The POS's unique nroticket is not sent in the PAGOQR contract. (origin: agent, confirmed: 2026-11-16)
  • D2 — Local status is a superset of the municipal one: CREATING → PENDING → PAID | EXPIRED | CANCELLED, plus UNCERTAIN when the outcome is unknown (timeout on create or cancel). The gateway keeps querying until it is resolved and never reports "rejected" to the POS while uncertain. ADR-003 adds PAID_UNCONFIRMED (paid in the municipal API after the POS abandoned the attempt). (origin: agent, confirmed: 2026-11-16) Added during slice 1: ISSUED (a trxid was handed out, no trxpago yet) and REJECTED (municipal rejection on create, E2, or cashback, E3). POS mapping: ISSUED → PAGO_ENVIADO, REJECTED → REFUND_DENEGADO (PosEstadoMapper). The PAGOQR contract is unchanged. (origin: agent, confirmed: 2026-11-16)
  • D3 — The payer's employee number (pagadoPorLegajo) IS stored on the payment attempt (human decision). It is personal data (Ley 25.326): persisted in the database only, never written to application logs.
  • D4 — Branches are configured, terminals are not (K2′). The gateway resolves the merchant (CUIT, API key) from the POS comercio + sucursal; a trxid from an unconfigured branch is rejected with "Sucursal no configurada". The POS number is stored on each attempt and used in referenciaExterna (D1). (origin: agent, confirmed: 2026-11-16)
  • D5 — The environment is pinned on the attempt at claim (V3). Query and cancel refuse, with no municipal call, when the merchant's current environment differs, and raise ENVIRONMENT_MISMATCH (CONSTITUTION C6). Added in slice 2a from the improve review. (origin: agent, confirmed: 2026-11-17)
  • D6 — Amount mismatch is a final status, denied to the POS. A PAGADO whose amount differs from the attempt amount (or cannot be read) ends AMOUNT_MISMATCH with an alert; the POS receives REFUND_DENEGADO with a "do not charge again" message. The money has moved, so the admin settles it from the alert. (human decision, 2026-11-17)
  • D7 — A held or stuck attempt is closed by an admin, never automatically. After expira + grace an admin may close it (current password + note) to the final status CLOSED_BY_ADMIN; the POS receives REFUND_DENEGADO "NO cobrar de nuevo, verificar con la Muni". While it stays held or stuck, its alert is raised once and is not raised again after a resolve. (human decision, 2026-11-17)