Skip to content

ADR-008: Carta e identificación bloquean el pago — el resto de los documentos, no ​

Date: 2026-09-12 Status: Accepted — implementado 2026-09-12. Actualizado el 2026-10-06 (G2.1: la excepción de quien pagó; G2.2: el rechazo del multi-PDV sin PDV activo, §1 y el final de este documento; G5.7: la procedencia de los documentos previos, al final) Supersedes in part: R3 de Pago con documentos §0.4

Context ​

R3 fijó, como la decisión más importante del paquete de Pago con documentos: "el pago nunca se bloquea por documentos faltantes". La razón que lo sostiene es física — cuando el operador llega al paso de subir escaneos, la plata ya salió del cajón; frenar el registro en ese punto no evita nada, convierte un trámite pendiente en un descuadre de caja.

Carlos pidió invertir el orden (2026-09-12): antes de poder confirmar el pago, el operador tiene que haber subido la Carta de Soterex y la identificación del beneficiario (anverso y reverso). Sin esos tres documentos, el botón "Confirmar pago" queda bloqueado.

Esto no contradice la razón original de R3 — la sostiene. R3 protege la operación de un frenazo después de que la plata salió del cajón. Carta + identificación son, en cambio, exactamente lo que el operador tiene que cotejar antes de entregar la plata (§1.1 del flujo del pago: "Coteja carta contra identificación y rostro"), y hoy ese cotejo ocurre fuera de la app, sin dejar rastro hasta que alguien sube el escaneo — a veces mucho después, o nunca. Exigir el escaneo antes de pagar no le agrega fricción a un paso que ya existe en el mostrador: lo hace verificable.

Los demás documentos siguen sin bloquear, y por una razón que no es solo de alcance sino física: la Papeleta firmada no puede existir antes del pago — es el comprobante que el cliente firma después de recibir la plata. Exigirla antes sería pedir algo que todavía no puede existir. La selfie sigue opcional (R5) y los cuatro documentos de transferencia siguen atados al medio de pago, que tampoco es obligatorio cargar antes de pagar.

El problema de fondo que esto expone ​

Los documentos son PII sensible (R7) y su acceso se acota siempre por PDV (TransactionDocumentController::authorizeScope, backend/app/Http/Controllers/TransactionDocumentController.php:129-147), sobre la premisa escrita en el propio código de que "los documentos existen solo sobre transacciones ya resueltas". Una transacción ACCEPTED no tiene station_id todavía — es bolsa compartida por país (doc/plans/2026-07-25-fix-pdv-asignacion-transacciones.md), y se le asigna recién al resolverla en pay()/cancel().

Si ahora hay que subir documentos antes de resolver la transacción, esa premisa deja de ser cierta, y hay que decidir de qué PDV son esos tres documentos mientras la transacción sigue siendo de todo el país.

Decision ​

1. El primer documento subido sobre una ACCEPTED le asigna el PDV ​

Se reutiliza la misma resolución que ya usa pay() (TransactionController::resolveStationForResolution(), backend/app/Http/Controllers/TransactionController.php:445-454): al primer POST de un documento sobre una transacción ACCEPTED sin station_id, se le asigna el PDV resuelto para ese usuario (su PDV activo si tiene uno configurado, o el único PDV de su alcance). Un usuario con más de un PDV asignado y sin PDV activo no puede ser el primero en subir — mismo criterio que ya aplica hoy para pagar.

Desde ese momento, esa transacción deja de ser bolsa compartida para efectos de documentos: los tres escaneos son del PDV que los subió, con el mismo acotamiento de siempre. La transacción en sí sigue siendo ACCEPTED y sigue apareciendo en el listado general sin filtrar por PDV — el PDV asignado por el upload no la saca de la bolsa compartida de transacciones, solo fija el dueño de los documentos que ya existen.

Corrección (2026-10-06) — resuelta el mismo día por G2.2. La frase «no puede ser el primero en subir» decía lo que se quiso y no lo que hacía el código: el store() de documentos no rechazaba a ese usuario, resolveStationForResolution() devolvía null (por dos razones distintas, más de un PDV sin PDV activo y un alcance sin acotar como el del Admin) y el upload guardaba station_id = null y subía igual. Desde la entrega G4a el código cumple la frase, con un predicado más angosto que ella: dos o más PDV acotados, ningún PDV activo y ninguna caja abierta de la persona en el país (con módulo Caja, el PDV de esa caja es el PDV de la transacción) responden 422 ACTIVE_STATION_REQUIRED; un alcance sin acotar (Admin) sigue subiendo sin PDV, como siempre. Es la misma regla que rige al pagar. Detalle y alternativas en ADR-020.

Consecuencia que hay que cerrar en el mismo cambio: si otro operador (de otro PDV) termina pagando esa misma transacción, pay() hoy pisa station_id incondicionalmente ($locked->station_id = $resolvedStationId, línea 250). Con documentos ya asignados a un PDV distinto, ese pisado dejaría los tres escaneos huérfanos — subidos por un PDV, visibles después solo para otro. pay() pasa a no reasignar station_id si la transacción ya lo tiene ($locked->station_id ??= $resolvedStationId): quien sube el primer documento se queda como dueño del PDV aunque otro operador resuelva el pago. Es una ventana angosta (competencia real por la misma transacción, entre que se suben los documentos y se paga) pero es plata y PII a la vez; no se deja sin resolver.

Actualización (2026-10-06). Que pay() no reasigne el PDV deja pendiente una pregunta que este ADR no contestaba: qué ve quien termina pagando una transacción cuyo PDV fijó otro operador (o que quedó sin PDV). Se contesta en «Actualización — G2.1», al final de este documento: quien pagó entra a esa transacción aunque su PDV no coincida. El resto de este §1 no cambia.

2. El endpoint de documentos deja de asumir "transacción ya resuelta" ​

TransactionDocumentController::authorizeScope() acota siempre por PDV bajo la premisa de que todo documento cuelga de una transacción ya resuelta. Pasa a distinguir:

  • Transacción ya resuelta (PAID/CANCELLED): sin cambios — se acota por station_id como hoy.
  • Transacción ACCEPTED sin station_id todavía: cualquier usuario con permiso de escritura sobre el país puede subir (mismo criterio de bolsa compartida que ya usa TransactionController::authorizeScope para ACCEPTED — no es un mecanismo nuevo, es extender uno que ya existe a este controller).
  • Transacción ACCEPTED con station_id ya asignado (por un upload anterior): se acota por ese PDV — es exactamente la misma regla que rige para PAID/CANCELLED, aplicada un paso antes.

3. pay() exige los tres documentos antes de resolver ​

Dentro de la transacción de base de datos de pay(), después del re-chequeo de estado ($locked->status !== 'ACCEPTED') y antes de tocar caja o prefondeo: si falta CARTA, IDENTIFICACION_ANVERSO o IDENTIFICACION_REVERSO, se corta con 422 y un código nuevo, MISSING_REQUIRED_DOCUMENTS, con la lista de los que faltan — mismo patrón que INSUFFICIENT_PREFUNDING (422, no 409: no es un conflicto de concurrencia, es una precondición que no se cumple).

Se valida dentro de la transacción con lock, no antes: dos operadores pueden estar completando documentos a la vez sobre la misma ACCEPTED (es bolsa compartida), y el que efectivamente confirma el pago tiene que ver el estado real en ese instante, no uno leído al abrir la pantalla.

TransactionDocument gana una constante nueva, REQUERIDOS_ANTES_DE_PAGAR = ['CARTA', 'IDENTIFICACION_ANVERSO', 'IDENTIFICACION_REVERSO'] — subconjunto de REQUERIDOS_SIEMPRE que excluye PAPELETA_FIRMADA (que, como se explicó arriba, no puede existir todavía). Transaction gana faltanDocumentosPrePago(): array, misma forma que faltanDocumentos() pero contra ese subconjunto.

4. El frontend pide los tres documentos en la pantalla Pago, antes del botón de confirmar ​

PagoView.vue muestra una sección de documentos antes del bloque de acciones (hoy el botón "Confirmar pago" es lo primero que aparece tras encontrar una ACCEPTED), con los tres tipos bloqueantes únicamente — no los nueve. "Confirmar pago" queda deshabilitado con un texto tipo "Faltan: Carta de Soterex, Identificación (reverso)" hasta que estén los tres.

No se reutiliza DocumentacionPago.vue tal cual. Ese componente already-existente sirve una lista de nueve tipos, no bloqueante, para una transacción ya pagada — mezclar ahí un modo "tres tipos, bloqueante, pre-pago" le agrega una rama condicional a un componente cuyo comentario de cabecera dice explícitamente "nunca hay un paso bloqueado (R3)", que dejaría de ser cierto para uno de sus modos. Se extrae un componente nuevo y más chico, DocumentacionPrePago.vue, que comparte el servicio (transactionDocumentsApi) y la lógica de preview (blob + Bearer) pero no el componente visual. Después de pagar, la transacción sigue mostrando el stepper de nueve existente —sin cambios— y ya aparece con esos tres marcados, porque son los mismos documentos.

Alternatives Considered ​

  • Reutilizar DocumentacionPago.vue con un prop de modo (bloqueante: boolean / tiposRequeridos: DocumentType[]). Menos código nuevo, pero convierte al único componente cuyo contrato hoy es "nunca bloquea" en uno que a veces sí — cualquiera que lo toque después tiene que leer las dos ramas para saber si un cambio es seguro. El componente nuevo es chico (tres tipos, sin badge de completitud de nueve, sin selfie) y no repite la parte sensible (preview) porque la comparte vía el mismo service.
  • No asignar PDV al primer upload; dejar los documentos pre-pago sin acotar por PDV mientras la transacción sea ACCEPTED. Es la alternativa que se descartó explícitamente al decidir esto (opción presentada y no elegida): más simple —ni siquiera hace falta tocar station_id— pero dos identificaciones de personas distintas quedarían visibles para cualquier operador del país mientras nadie pague, debilitando exactamente el pilar que R7 protege (acotamiento por PDV de PII sensible). Se prefiere la asignación temprana aunque cueste la ventana de reasignación del punto 1.
  • Validar los documentos completos (los nueve) antes de pagar, no solo los tres de identificación. Es físicamente imposible para la Papeleta firmada (no existe hasta después del pago) y no tiene sentido para los cuatro de transferencia (el medio de pago mismo no es obligatorio antes de pagar). Descartado por la misma razón que motivó R3 en primer lugar: no confundir "verificar antes de entregar la plata" con "frenar el registro después de entregarla".
  • Agregar el bloqueo como una validación de UI únicamente (deshabilitar el botón en el frontend), sin tocar pay() en el backend. Descartado: cualquier cliente que le pegue directo a la API (o un bug futuro en el frontend) confirmaría pagos sin identificación verificada — la regla de negocio tiene que vivir donde se puede hacer cumplir, no solo donde se muestra.

Consequences ​

  • Positive: la verificación de identidad que hoy ocurre en el mostrador, sin dejar rastro hasta que (si acaso) alguien sube el escaneo, pasa a ser una precondición real y auditada del pago. Cierra el hueco que R9/R7 dejaban abierto: hoy una transacción puede estar PAID hace semanas sin que nadie haya verificado nunca la identidad de quien cobró.
  • Negative: el flujo de pago se vuelve más largo en el caso más común (cliente presente, con carta e identificación en la mano) — tres subidas de archivo antes de poder confirmar, donde antes había un solo click. Es el costo directo y aceptado de esta decisión.
  • Negative: introduce la primera excepción a R3 desde que se escribió — el próximo lector de R3/R4 tiene que leer también este ADR para entender que "el pago nunca se bloquea" ya no es literalmente cierto para estos tres tipos. Se corrige actualizando R3/R4 y §1.1/§1.4/§1.5/§2.2 del Análisis Funcional de Pago con documentos en el mismo cambio que implemente esto, no después.
  • Negative: pay() pasa a depender de transaction_documents, una tabla de otro dominio (hasta ahora pay() solo tocaba transactions, caja y prefondeo). Es el mismo tipo de acoplamiento que ya aceptó R4 al derivar documentacion_completa de esa tabla — no es un patrón nuevo, es extender uno ya aceptado a un momento más temprano del flujo.
  • Neutral: no cambia nada de la Papeleta, la selfie, los datos de datosPago(), ni los cuatro documentos de transferencia — siguen exactamente como R3/R4/R5 los dejaron.

Implementación (2026-09-12) ​

Diseño llevado a código tal cual, con dos precisiones que no estaban en el diseño técnico original:

  • La lógica compartida entre DocumentacionPago.vue (post-pago) y el nuevo DocumentacionPrePago.vue —el preview blob+Bearer y los guards contra respuestas fuera de orden cuando el operador cambia de transacción sin recargar— se extrajo a un composable (frontend/src/composables/useTransactionDocuments.ts) en vez de duplicarse. Ninguno de los dos componentes comparte template ni contrato de bloqueo, solo esa mecánica.
  • Ventana de carrera aceptada, no cerrada con lock: el primer upload sobre una ACCEPTED sin PDV lee station_id === null y lo asigna sin lockForUpdate() (a diferencia de pay(), que sí lockea). Dos operadores de PDVs distintos subiendo el primer documento de la misma transacción casi al mismo tiempo podrían, en teoría, asignarle el PDV del que gane la escritura en vez de un "primero en llegar" estricto. Se acepta sin lock porque no hay plata en juego en ese paso (a diferencia de pay()/cancel(), que si lockean) — el peor caso es una ambigüedad de PDV sobre documentos, no un descuadre de caja.

Actualización — G2.1 (2026-10-06): quien pagó recupera el acceso a lo suyo aunque el PDV sea otro ​

El §1 fija el PDV de una ACCEPTED con el primer documento que sube cualquier operador, y pay() no lo reasigna. Eso deja una pregunta que el ADR no contestaba: qué ve quien termina pagando una transacción cuyo PDV fijó otro. El alcance por PDV (TransactionDocumentController::authorizeScope() y PermissionService::inTransactionScope()) le daba 404 en sus propios soportes, en su papeleta y en el datos_pago de la búsqueda de Pago: no podía imprimir la papeleta del pago que acababa de hacer ni subir la firmada, y el cierre de caja le quedaba bloqueado por PENDING_PAYMENT_DOCUMENTS sin forma de destrabarlo (RV3-14, decisión D3-2 a del plan de ajustes v3).

Decisión. Quien tiene resolved_by_user_id igual a su id y el permiso por país (transacciones:{acción}) queda dentro del alcance de esa transacción aunque su PDV no coincida con el de la tx. Se evalúa siempre después del permiso por país, así que quien pagó y hoy no lo tiene (o lo tiene en otro país) no entra. Una sola definición, PermissionService::isResolverOf(), que usan el alcance de operar y de ver (canOperateTransaction, canViewTransaction: papeleta y datos_pago), el de los soportes (authorizeScope(): listar, descargar y subir) y la regla de quién puede subir después de resolver (canManageTransactionDocuments, que ya hacía esta excepción para subir y ahora comparte la definición). El aviso «Tenés N pagos con documentación pendiente» de Pago (PagoController::pendientes) aplica la misma idea en SQL para un Supervisor acotado a un PDV: lista también lo que él mismo pagó fuera de su PDV o sin PDV, que es lo que le frena el cierre de caja.

Lo que NO cambia (y está probado por API en PagadorOtroPdvApiTest):

  • Nadie más gana acceso: ni el resto del PDV donde quedó la tx, ni quien subió los documentos, ni el resto del país. Un compañero del PDV de la tx la sigue viendo y no puede subir (403 CANNOT_MANAGE_DOCUMENTS); un tercero de otro PDV sigue recibiendo 404.
  • El pagador no gana las demás transacciones del PDV ajeno: la excepción es por transacción, no por PDV.
  • No se toca el alcance del listado ni del detalle general de Transacciones, tampoco para el pagador (probado con un Supervisor acotado a un PDV, que entra a los soportes y a la papeleta de lo que pagó en otro PDV y no lo ve en Transacciones, y con el Cajero acotado a lo propio). Admin y Supervisor no ganan nada sobre las transacciones que no resolvieron; si pagaron o cancelaron una, rige la misma excepción que para el Cajero.
  • La subida antes de pagar (ACCEPTED con PDV ya fijado) sigue acotada por ese PDV: la excepción empieza cuando la tx tiene resolved_by_user_id, o sea después del pago o la cancelación.

Alternativas descartadas (D3-2): abrir la lectura de soportes y papeleta a todo el país con transacciones:write (expone identificaciones de otros PDV, que es justo lo que este ADR protege) y no tocar el alcance y solo mejorar los mensajes (deja el ciclo pagar, imprimir, firmar, subir y cerrar sin salida).

La incoherencia del §1 sobre el usuario con más de un PDV y sin PDV activo —el texto decía que «no puede ser el primero en subir» y el código guardaba station_id = null sin rechazar— no la resolvió G2.1: la resolvió G2.2 en la entrega G4a (422 ACTIVE_STATION_REQUIRED, ver la corrección del §1 y ADR-020), porque tenía que decidir mirando la caja abierta y esa lógica nace con G4.1.

Tres consecuencias de la excepción que conviene tener escritas (no son cambios, es lo que queda):

  • La excepción vale desde el pago: antes de pagar, una ACCEPTED ya reclamada por el PDV A sigue acotada a ese PDV, y quien opera desde un PDV B acotado no ve sus documentos previos (404). La pantalla de Pago no puede mostrarle los tres documentos y mantiene deshabilitado Pagar (desde L2, más abajo, los documentos se ven recién al tocar Iniciar pago), aunque el backend, en pay(), solo mire que los tres existan. No es nuevo ni lo cambia G2.1 (resolved_by_user_id recién existe al pagar), y queda como pregunta para Carlos: aceptar que la ACCEPTED queda «reclamada» por el PDV de quien subió el primer documento (y que la paga ese PDV, un Supervisor con alcance o el Admin) o abrir la lectura de esos tres documentos. Ver el plan de pruebas de G2, caso 4.
  • La excepción también cubre a quien canceló (resolved_by_user_id se llena en cancel() igual que en pay()), con el mismo permiso por país: es la misma definición, isResolverOf(). Probado por API con un Admin acotado a un PDV que cancela una tx de otro.
  • Pagar es la puerta de entrada a la PII de otro PDV. pay() solo exige que los tres documentos previos existan (faltanDocumentosPrePago), no que estén dentro del alcance de quien paga, y una ACCEPTED es bolsa compartida del país. Entonces un Cajero del país con pago:write y una caja abierta con saldo puede, por API, pagar una ACCEPTED que el PDV A ya reclamó y, desde ese momento, leer sus soportes (incluida la identificación del beneficiario) y su papeleta; cada lectura queda auditada (TRANSACTION_DOCUMENT_VIEWED, PAPELETA_GENERATED). Es consecuencia directa de D3-2 (a), no un defecto de la implementación, y no se cambió el código: se acepta porque el pago es real, deja un movimiento en una caja con su dueño y se audita quién lo hizo y qué leyó después. Se resuelve junto con la pregunta de arriba (si la ACCEPTED reclamada la puede pagar solo el PDV que la reclamó), y es lo que la revisión de seguridad del MVP1 (E6) tiene que mirar con conocimiento.

Actualización — G5.7 (2026-10-06): los documentos previos se mantienen, con su procedencia ​

Qué pasaba. El §1 y el §3 guardan los tres documentos previos contra la transacción desde la primera subida, aunque quien los subió no llegue a pagar, y la tarjeta los trae al montarse. Al volver a buscar una transacción que alguien dejó a medias, el operador se encontraba con una Carta y una identificación que no cargó él, sin ninguna señal de que eran de otro intento. El cliente de Guatemala lo marcó ("Si se busca una tx y no se la paga, la herramienta no debería traerme cargados los documentos", RV3-11), y la frase admite dos lecturas: (a) no ver los de un intento anterior, o (b) no mostrar la sección mientras solo se consulta.

Qué se decidió (D3-10, opción 1; QC-3 sigue sin respuesta). Se mantienen y se les agrega procedencia, porque sirve en las dos lecturas y no rompe lo que este ADR protege: el cotejo sigue siendo contra algo guardado, y el Supervisor que revisa después ve lo que había. La tarjeta Documentos para poder pagar muestra, debajo de cada archivo, «Subido por mail el dd/mm» (con el año si es de otro) y, sobre la lista, un aviso de una línea: «Estos documentos ya estaban cargados desde el dd/mm. Verificá que correspondan a quien tenés enfrente.» («Este documento… corresponda…» si es uno solo). «De un intento anterior» es lo que ya estaba cuando se abrió la tarjeta para esa transacción: la pantalla toma una foto de los ids en la primera carga de cada transacción; lo que se sube después en la misma pantalla no lleva el aviso, y reemplazar el último documento previo lo hace desaparecer. «Desde» es la fecha del más antiguo.

Qué no cambia. Nada del backend de este ADR: pay() sigue exigiendo que existan los tres, el alcance por PDV es el mismo, y no hay campo ni migración nuevos (uploaded_by y created_at ya viajaban en la lista; la respuesta de la subida se alineó con ellos). Solo viaja el mail de quien subió, nunca algo del beneficiario. Es una pista para el cotejo, no un bloqueo: el botón Iniciar pago no mira el aviso.

Si QC-3 responde (b) (no mostrar la sección hasta tocar Iniciar pago), el cambio es de pantalla: cuándo se pide y se muestra la lista, sin tocar el backend. Alternativa descartada (opción 3 del plan): no traer los documentos de un intento anterior, o descartarlos al buscar de nuevo. Es lo más caro y rompe el cotejo posterior del Supervisor, que necesita ver qué se había cargado.

Actualización — L2 (2026-10-19): los documentos se ven al tocar «Iniciar pago»; confirmar sigue exigiéndolos ​

El cliente contestó el 2026-10-14 la pregunta que la actualización anterior dejó abierta (QC-3): la lectura (b). «La sección de documentos aparece recién al tocar "Iniciar pago"», y «seguramente habrá que incluir un botón adicional para PAGAR y continuar con el proceso». Es el cambio de pantalla que esa nota anticipaba.

Qué cambió (solo PagoView.vue y MatchResultCard.vue).

  • Al consultar una transacción disponible ya no se muestra ni se pide la lista de documentos: se ven los datos de Soterex y el formulario de datos del pago. Los documentos de una visita anterior no aparecen hasta el siguiente paso.
  • «Iniciar pago» ya no abre la confirmación: despliega la tarjeta Documentos para poder pagar y un botón «Pagar» debajo de ella. «Pagar» abre la ventana de confirmación de siempre (medio de pago y Confirmar pago).
  • Por eso la condición se parte en dos. Iniciar exige lo que hoy exigía pagar menos los documentos: datos del pago completos y guardados, sin formato inválido, sin la caja ni el MTCN vencidos. Exigir los documentos en ese botón sería un círculo: nadie podría subirlos. Pagar exige eso más los tres documentos, con el motivo escrito bajo el botón («Faltan documentos: …»). El motivo bajo «Iniciar pago» ya no los nombra.
  • El estado pagoIniciado se reinicia al cambiar de resultado y hay un enlace «← Volver a la consulta» que oculta la tarjeta sin perder lo guardado. Al volver a iniciar, «Pagar» espera a que se vuelvan a traer los documentos.

Qué no cambia. Nada de lo que este ADR decide: pay() sigue exigiendo la Carta y la Identificación (anverso y reverso) y responde MISSING_REQUIRED_DOCUMENTS si faltan; el alcance por PDV, la procedencia de los documentos previos y el resto de los documentos (que nunca bloquean) son los mismos. No es una reversión: los documentos siguen bloqueando confirmar el pago; cambió cuándo se ven.

Alcance (D5-2). Solo la pantalla Pago. TransaccionDetalleView.vue (el detalle del Reporte individual, que usa los mismos componentes para el Admin) no cambia: el ítem del cliente es de la hoja Pago.

Consecuencia a tener en cuenta. Quien consulta una transacción sin permiso para pagarla (pago:write) no ve el botón «Iniciar pago» y, por lo tanto, tampoco la tarjeta de documentos de una disponible. Es la misma lectura: los documentos de una disponible son parte de pagar, no de consultar.

Documentación viva — se actualiza junto con el código, no es un anexo aparte.