ADR-004 — POS connection: direct over VPN, dual request shape, two listeners¶
Status¶
Accepted (human, 2026-10-02, Q8–Q10). The VPN is a risk to verify (R-14).
Context¶
- One central multi-merchant gateway on the GatewayQR server (Q8).
- Almacor has no RouterQR; its POS calls the gateway directly through a VPN (Q9, Q10).
- The DOS POS speaks plain HTTP/1.1 (Host header, two spaces after the method, bare LF line ends) to
PAGOQR_SERVER_IP:PORT, with no TLS and no auth header; it cannot parse chunked bodies and waits for its read timeout unless the server closes the connection. (Corrected 2026-10-02, SD-002; the first version said HTTP/1.0 without Host.) - Other chains (e.g. DINO) reach gateways through a per-chain RouterQR, which rewrites the request (
importe,tipoautorizador,id = trxidoriginal) and addsid/mediodepagoto responses. - Merchant = legal owner (CUIT); chain partners are separate merchants (Q7).
Decision¶
- Accept both request shapes: POS-native (
totalitem,trxanulacionwithtrxidoriginalpossibly 0) and RouterQR-forwarded. Always returnidandmediodepago. - Keep GatewayQR
estadonames and numeric ids exactly, with one exception (amended 2026-10-04, human-approved, after the real Almacor POS E2E): the consultaGET /api/trxes/{id}of a payment irreversibly decided as no sale answersREFUND_DENEGADO, because the POS treatsAUTORIZACION_DE_PAGO_DENEGADAas "keep polling".trxpagoanswers keep GatewayQR's estados, with one addition (2026-10-28, INV-01): when the gateway cannot durably record its intent to answer approved, it answersINTENCION_DE_PAGO_RECIBIDA_APROBADA(statuscode 0, the estado of a payment not settled yet) instead of approved, ontrxpagoand on the consulta (D-105). - Every
/apianswer, errors included, carriesContent-LengthandConnection: closein the{status, message}shape for errors. - Two listeners: the POS API binds only to the VPN-side address; the Prisma callbacks bind to a separate public HTTPS port with the apikey we issue.
trxanulacionis never reachable from the internet. - Amended 2026-10-04: a third connector serves the admin console and its API, loopback by default; see ADR-005. (origin: agent, confirmed: 2026-10-05)
- Optional per-merchant source-IP allowlist inside the VPN.
Consequences¶
- A RouterQR can be placed in front of any merchant later without gateway changes.
- Security of the POS channel depends on the VPN (R-14).
Implementation Plan¶
- Two Spring Boot connectors (management of a second port) with path-based security per connector.
PosRequestNormalizermapping both shapes to one command.- Golden tests for both shapes, using the real POS E2E log (
DINI\E2E_QR\paranoia\evidence\E2E_V1_log.txt) as corpus.
Verification¶
- [ ] AC-01..AC-05 and AC-28 green.
- [ ] A request to a POS endpoint on the public port is refused.