Saltar a contenido

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 adds id/mediodepago to responses.
  • Merchant = legal owner (CUIT); chain partners are separate merchants (Q7).

Decision

  • Accept both request shapes: POS-native (totalitem, trxanulacion with trxidoriginal possibly 0) and RouterQR-forwarded. Always return id and mediodepago.
  • Keep GatewayQR estado names and numeric ids exactly, with one exception (amended 2026-10-04, human-approved, after the real Almacor POS E2E): the consulta GET /api/trxes/{id} of a payment irreversibly decided as no sale answers REFUND_DENEGADO, because the POS treats AUTORIZACION_DE_PAGO_DENEGADA as "keep polling". trxpago answers keep GatewayQR's estados, with one addition (2026-10-28, INV-01): when the gateway cannot durably record its intent to answer approved, it answers INTENCION_DE_PAGO_RECIBIDA_APROBADA (statuscode 0, the estado of a payment not settled yet) instead of approved, on trxpago and on the consulta (D-105).
  • Every /api answer, errors included, carries Content-Length and Connection: close in 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. trxanulacion is 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.
  • PosRequestNormalizer mapping 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.