ADR-011: Los datos del pago son obligatorios antes de pagar
Date: 2026-09-28 Status: Accepted — implementado 2026-09-28 Extends: ADR-008 (misma lógica, un paso más adelante)
Context
A1 (doc/plans/2026-09-28-ajustes-v1-cliente-gt.md) dejó DatosPagoForm inmutable con PAID (D4), pero no resolvió el problema de fondo que esa inmutabilidad expone: hoy no hay ninguna pantalla donde cargar esos datos antes de pagar. El formulario solo aparece con la transacción ya PAID (PagoView.vue, sección condicionada a resultadoActual.status === 'PAID'), así que en la práctica nadie puede completarlo — la A1 lo dejó anotado como advertencia en el PR ("no desplegar A1 sin A3").
El cliente pidió, sobre esa misma pantalla: una sola vista con todo lo que manda Soterex (solo lectura) y, debajo, lo que completa el operador (editable); "Confirmar pago" deshabilitado hasta completar todo; el medio de pago se elige recién al confirmar.
Decision
1. Los datos se cargan sobre ACCEPTED, no después de pagar
PagoView.vue, con una transacción ACCEPTED, muestra en este orden: (a) un bloque de solo lectura con lo que manda Soterex — nombre, teléfono, email, nacionalidad, fecha de nacimiento, remitente, país y moneda de origen, monto, alien number, viaja con menores / nombre del menor —, (b) DatosPagoForm editable, sin los campos de medio de pago (ver punto 3), y (c) DocumentacionPrePago (ADR-008, sin cambios). Los data-tour existentes de esta pantalla (ADR-009) se reubican sobre los controles reales; ninguno queda apuntando a un elemento que se movió sin actualizar su paso.
Gap cerrado de paso: transactions no tenía columnas para "viaja con menores" / "nombre del menor" (openapi.yaml SendRequestBody.beneficiary_traveling_with_minors / full_name_of_minor) — nunca se habían agregado pese a estar en el payload de Soterex desde el Análisis Funcional original. Se suman traveling_with_minors (boolean, nullable) y minor_full_name (string, nullable) en la misma migración que toca transactions para esta entrega, y se completan en DemoTransactionSeeder para que el dato sea visible en QA. M5 (la ingesta real desde SendRequest) todavía no existe como controller — cuando se construya, tiene que poblar estas dos columnas igual que ya puebla nationality/birth_date.
2. Todos los campos son obligatorios salvo Notas (D3)
Actualizado el 2026-10-05 (G3):
delivery_typesolo puede ser efectivo ybank_accountya no es obligatorio con ningún medio (la rama deTRANSFERENCIAse sacó). Lo vigente está en la Actualización — G3 del final.
beneficiary_address, beneficiary_city, beneficiary_state, identification_type, identification_country, identification_number, phone_2, email_2 y delivery_type son obligatorios para poder pagar. bank_account es obligatorio únicamente si delivery_type === 'TRANSFERENCIA'. notes sigue siendo el único campo opcional. La validación vive en el backend (punto 3) — el frontend solo la refleja deshabilitando el botón con el motivo, igual que ya hace services/transactionDocuments.ts con MISSING_REQUIRED_DOCUMENTS.
3. Medio de pago se elige al confirmar, y pay() guarda y paga en una sola llamada
Actualizado el 2026-10-05 (G3): el medio de pago es solo efectivo y el backend rechaza otro. Lo que dice este punto sobre
delivery_type/bank_accountvale para el diseño de ese día; lo vigente está en la Actualización — G3 del final.
Decisión de diseño explícitamente recomendada por el plan (A3.5), elegida acá: en vez de dos llamadas (datosPago() para guardar, después pay() para pagar, con el riesgo de confirmar con datos sin guardar si el operador saltea el primer paso), pay() pasa a recibir el estado completo actual del formulario — los mismos campos de CAMPOS_DEL_PAGO que ya acepta datosPago(), más delivery_type/bank_account que hasta ahora solo vivían ahí — y hace guardado + validación D3 + transición de estado en la misma transacción de base de datos, con el mismo lockForUpdate() que ya usa. Si falta un campo obligatorio, corta con 422 MISSING_PAYMENT_DATA y la lista de campos faltantes, mismo patrón que MISSING_REQUIRED_DOCUMENTS (ADR-008) e INSUFFICIENT_PREFUNDING.
datosPago() no se elimina: sigue existiendo como guardado explícito ("Guardar datos") mientras la transacción es ACCEPTED, para que el operador no pierda lo tipeado si se distrae antes de confirmar — pero deja de exigir todos los campos (sigue aceptando parciales, como hoy) y dejan de pasar por ahí delivery_type/bank_account desde la pantalla de datos: esos dos se piden recién en el modal de confirmación (ConfirmActionModal) y se mandan únicamente en el pay() final, que siempre reescribe la fila completa con lo que el operador tenga en pantalla en ese momento — independientemente de si clickeó "Guardar" antes o no. Esto hace innecesaria cualquier lógica de "merge con lo ya guardado": el frontend siempre manda el estado completo del formulario al confirmar.
DatosPagoForm dentro de ACCEPTED deja de mostrar los campos "Medio de pago"/"Cuenta bancaria" (A3.2) — se piden en el modal en su lugar. Con PAID/CANCELLED (solo lectura) los sigue mostrando, porque ahí son informativos: cómo se pagó realmente.
4. Permisos de soportes documentales después de resolver (A3.6, D5)
Mientras la transacción sigue ACCEPTED — con station_id todavía sin asignar, o ya asignado por el primer upload (ADR-008) — sigue rigiendo la regla de bolsa compartida: cualquiera con transacciones:write y alcance sobre el país puede subir cualquiera de los tres documentos, en cualquier orden. station_id se asigna al primer upload para saber de qué PDV son esos documentos más adelante (ADR-008), no para decidir quién puede seguir subiendo el segundo o el tercero mientras nadie resolvió todavía — resolved_by_user_id sigue siendo null en todo este tramo, así que la restricción de abajo no tiene a quién aplicarle "es quien pagó". (Una primera versión de esta regla condicionaba la bolsa compartida a station_id === null, lo que le bloqueaba a un Backoffice común su propio segundo documento apenas el primero le asignaba PDV — corregido en code review antes de mergear.)
Recién al resolverse (PAID/CANCELLED), subir pasa a exigir una de tres cosas: ser resolved_by_user_id, o Admin, o un usuario con transacciones:write sobre el PDV de la transacción que además tenga alcance no acotado por PDV o fondeo_caja:read sobre ese país.
Por qué fondeo_caja:read y no comparar contra un nombre de rol: el plan es explícito en que esto se decide por permiso/capacidad (PermissionService), nunca por nombre de rol — y después de A5.1, Backoffice también va a tener transacciones:read (D10), así que ese permiso deja de servir como señal de "es Supervisor". fondeo_caja:read es la MISMA señal que el propio plan ya usa para distinguir "opera una caja puntual" de "supervisa varias" en A5.3 (GET /caja/disponibles oculta saldos ajenos salvo para quien tiene fondeo_caja read) — hoy exactamente Supervisor y Admin. Reusar esa señal en vez de inventar una nueva evita depender de qué rol se llame cómo si la matriz cambia (A2, todavía en espera, podría agregar un perfil Tesorería con esta misma capacidad, y seguiría funcionando sin tocar este código). PermissionService::canManageTransactionDocuments(User, Transaction): bool centraliza la regla — no se repite en el controller.
Actualizado por G5 (2026-10-06): «subir lo que falta» y «reemplazar uno ya cargado» pasan a ser dos permisos distintos, y «supervisa» se evalúa dentro de una asignación. Ver la actualización G5 al final de este ADR.
5. documentoDe() toma el último documento del tipo, no el primero que encuentra (A3.7)
useTransactionDocuments.ts usaba find() sin orden garantizado; con un documento resubido (tipo repetido), podía mostrar uno viejo. Se ordena por created_at descendente antes de buscar — el más reciente gana.
Alternatives Considered
- Dos llamadas separadas (
datosPago()+pay()), conpay()solo verificando que ya esté guardado. Es lo que el plan describe como alternativa no recomendada: deja una ventana donde "Confirmar pago" está habilitado (todos los campos llenos en pantalla) pero el guardado real todavía no ocurrió, y confirmar fallaría o, peor, pagaría con lo último persistido en vez de lo que el operador ve en pantalla si hay una carrera entre el auto-guardado y el click de confirmar. Descartada por la razón que el propio plan da: una sola llamada atómica elimina la carrera de raíz en vez de mitigarla con más código. - Restringir subida de soportes post-pago solo al
resolved_by_user_idy Admin, sin el caso "Supervisor con alcance". Más simple, pero contradice D5 explícitamente ("cualquier Supervisor con alcance sobre el PDV" puede subir) — un Supervisor necesita poder completar un soporte que el cajero originalmente no subió, sin tener que pedirle a un Admin. - Nueva columna/flag "es supervisor" en la asignación, en vez de reusar
fondeo_caja:read. Correcto en abstracto, pero es una migración y un concepto nuevos para expresar algo que el sistema ya sabe distinguir con un permiso existente — se prefiere no crear una segunda fuente de verdad para la misma pregunta ("esta asignación es de alcance amplio o acotado a un PDV puntual") queallowedStationIds()/fondeo_cajaya contestan.
Consequences
- Positive: cierra el gap que A1 dejó documentado — con A3,
DatosPagoFormtiene una pantalla real donde cargarse antes de pagar, no solo después. - Positive: una sola llamada atómica en
pay()es más simple de razonar que dos llamadas con una carrera entre ellas, y reduce el round-trip en el caso común (operador completa todo y confirma). - Negative:
pay()crece en responsabilidad (ahora también guardaCAMPOS_DEL_PAGO, antes solo cambiaba estado y tocaba caja/prefondeo) — mismo tipo de acoplamiento que ADR-008 ya aceptó al hacer dependerpay()detransaction_documents. - Negative:
PermissionService::canManageTransactionDocumentsacopla la regla de subida de soportes afondeo_caja, un permiso de otro módulo. Es un acoplamiento deliberado (ver Alternatives) pero el próximo que lea ese método tiene que entender por qué, no asumir que es un error — el docblock lo explica. - Neutral: no cambia nada de Transacciones/Caja (A5) ni de documentos pendientes post-pago (A6) — quedan exactamente donde A3 los encuentra.
Adenda — B1.4 (2026-10-01): "lo que está en pantalla" es lo último guardado
La Decision §3 y la primera alternativa descartada hablan de "lo que el operador tenga en pantalla en ese momento". En la implementación pay() recibe datosPago, que es lo último guardado con "Guardar datos" (más el medio de pago del modal): lo tipeado y no guardado no viaja. La carrera que describe la alternativa descartada —pagar con lo último persistido en vez de lo que el operador ve— volvía a existir en ese caso: el botón se habilitaba con lo guardado y un cambio sin guardar quedaba afuera del pago sin avisar.
B1.4 (doc/plans/2026-10-01-ajustes-v2-cliente-gt.md) lo cierra del lado de la pantalla, sin tocar la decisión: DatosPagoForm avisa si hay cambios sin guardar (evento sinGuardar) y "Iniciar pago" (Pago) y "Cambiar a PAID" (ficha de la transacción) quedan deshabilitados mientras los haya, con un texto que manda a guardar. pay() sigue siendo una sola llamada atómica que reescribe la fila completa, y el backend sigue siendo quien valida (422 MISSING_PAYMENT_DATA).
Actualización — B4.0 (2026-10-02): fecha de nacimiento y nacionalidad pasan a ser datos del pago
Qué cambia. birth_date y nationality entran a Transaction::CAMPOS_DEL_PAGO y, por lo tanto, a los obligatorios de la Decision §2 (todos salvo notes; el backend los deriva de la constante, no hay una segunda lista). Los carga el cajero en DatosPagoForm, con asterisco, y salen del bloque de solo lectura "Datos enviados por Soterex" (§1), que dejaba de decir la verdad: Soterex no las manda.
Por qué. Decisión de Carlos del 2026-10-02 (P12 del plan doc/plans/2026-10-01-ajustes-v2-cliente-gt.md). Las columnas 3 y 4 del reporte de Cumplimiento (B4) las piden, y la API de Soterex no las manda: SendRequest no define ninguna de las dos (openapi.yaml). El §1 de este ADR las listaba entre los datos de Soterex porque las columnas existen en transactions desde M1 y E5a, pero nadie las escribía ni en la ingesta ni en ninguna pantalla — el seeder de demo era lo único que las llenaba. Sin esta actualización, el reporte habría salido con esas dos columnas vacías para siempre.
Cómo queda.
- Sin migración de esquema.
birth_dateya esdateynationalityya esstringnullable. - Validación en
datosPago()y enpay()(paymentDataRules()):birth_dateesY-m-dy anterior a hoy enAmerica/Guatemala(ni hoy ni futura), sin edad mínima ni máxima — una cota de edad sería una regla de negocio que nadie pidió.nationalityes texto libre de hasta 80 caracteres (un combo de países sería un cambio chico si el cliente lo pide). Si faltan,pay()corta con 422MISSING_PAYMENT_DATAy los nombra enfaltan, como a cualquier otro campo. - Inmutables con
PAID/CANCELLED(409PAYMENT_DATA_LOCKED), igual que el resto de los datos del pago (D4). - Mismo gate de PII que
datos_pago: viajan solo para quien puede operar la transacción (PagoSearchResource). Dejaron de viajar endatos_soterex. - La fecha viaja como
AAAA-MM-DD, sin hora ni zona. El cast pasó adate:Y-m-dyTransaction::datosDelPago()la formatea: con el cast anterior la API devolvía un instante en UTC (1990-05-12T06:00:00Z), un día distinto para quien la leyera al este de Greenwich, y el input de fecha del formulario no la entendía. - Ni los valores ni la fecha formateada van a la auditoría ni a los logs.
TRANSACTION_PAYMENT_DATA_UPDATEDguarda los nombres de los campos que cambiaron, como siempre. Para esodatosDelPago()también alimenta la comparación antes/después: la fecha es un objetoCarbony dosCarbonnunca son!==entre sí, así que sin normalizarla cada guardado la habría registrado como modificada. - El C2P entrante no se toca.
C2PControllerni lee ni escribe estas columnas, yopenapi.yamlno las define: no hay nada que Soterex mande hoy que quede guardado ahí. Si algún día las mandara y la ingesta las guardara, el formulario ya las muestra precargadas y el cajero las confirma o las corrige.
Qué implica para las ACCEPTED en vuelo. Las transacciones que ya esperan en staging no tienen estos dos datos. Con la regla nueva piden ambos antes de pagarse: la pantalla de Pago nombra "Fecha de nacimiento" y "Nacionalidad" en el motivo por el que "Iniciar pago" no se habilita (B1.4), y pay() las rechaza con 422 si llegan sin ellos. Es lo esperado, no un error. No hay migración de datos ni relleno: no se inventa la fecha de nacimiento de nadie. En los pagos hechos antes de B4.0 las dos columnas quedan vacías — el reporte de Cumplimiento las lleva en blanco solo para esos casos, y PAID es inmutable, así que no hay forma de completarlas después.
Actualización — B6 (2026-10-02): la predicción del §4 sobre un perfil Tesorería quedó refutada
El §4 dice que un perfil Tesorería con fondeo_caja:read «seguiría funcionando sin tocar este código». No fue así: cuando B6 creó el perfil (ADR-014), Tesorería recibió fondeo_caja L·E y, con la señal tal como estaba, habría pasado a ver todas las transacciones del país y a subir soportes de lo que resolvió otro. Hubo que separar la pregunta en dos —«¿ve el saldo de todas las cajas?» (canSeeAllCashBoxes) y «¿supervisa transacciones?» (isSupervisorTier: fondeo_caja:read ytransacciones:read en la misma asignación)—. Lo decidido en el §4 sigue en pie (se decide por permiso, no por el nombre del rol); lo que cambió es que fondeo_caja:read ya no alcanza solo. Ver ADR-014, punto 6.
Actualización — G3 (2026-10-05): el medio de pago es solo efectivo
El §2 pide delivery_type y, con TRANSFERENCIA, bank_account; el §3 lo elige el operador al confirmar. El cliente pidió sacar la transferencia de los medios de pago (RV3-12) o, si no, que no afectara el saldo del PDV (RV3-13), y Carlos ya había dejado dicho que el medio de pago es siempre efectivo (C13 del plan de ajustes v2, 2026-09-30). La entrega G3 del plan de ajustes v3 lo resolvió así (D3-4 b y D3-5 a, de Carlos, 2026-10-05):
- El backend solo acepta efectivo al escribir.
Transaction::DELIVERY_TYPES_ACEPTADOS = [EFECTIVO]es lo que validapaymentDataRules, y rige parapay()ydatosPago(): conTRANSFERENCIA(o cualquier otro valor) responden 422 conerrors.delivery_type(«El medio de pago solo puede ser efectivo.») antes de tomar ningún lock ni tocar la caja o el prefondeo. El §2 sigue valiendo para lo demás:delivery_typees obligatorio para pagar, así quepay()sin medio sigue siendoMISSING_PAYMENT_DATAconfaltan: ['delivery_type'].datosPago()acepta el valor onull(el borrador sin medio). - Se acepta menos de lo que existe en los datos.
DELIVERY_TRANSFERENCIAse queda: es lo que se lee (TransactionDocument::requeridosParay el mapa de medios de las columnas 16 y 17 de Cumplimiento comparan contra ella).DELIVERY_TYPEStambién se conserva, pero como registro de qué valores puede traer una fila: ninguna lógica recorre esa lista hoy. Los datos de pago de unaPAIDson inmutables (D4), así que las filas históricas por transferencia no se reescriben: siguen mostrándose en solo lectura con su cuenta bancaria, siguen contando para la completitud (los cuatro documentos de transferencia) y siguen saliendo en el reporte de Cumplimiento.bank_accountya no se pide ni se guarda: la obligatoriedad conTRANSFERENCIA(§2) se sacó, porque quedaba como una rama sin camino de entrada y sin test, ypay()ydatosPago()descartan la cuenta en toda escritura (también la de un borrador deTRANSFERENCIAde antes de G3, aunque el PATCH no traiga el medio: es un dato financiero sin uso). La regla de formato debank_accountsigue aceptándola solo para que una pestaña vieja no reciba un error por un campo que ya no importa. - No hay catálogo de formas de pago. Es una constante en código y no un catálogo de Parámetros (D3-5 a): nadie definió otra forma, y reactivar una Transferencia desde un ABM traería de vuelta el defecto de RV3-13 y los cuatro documentos. Si el cliente pide otras formas (QC-8, sin respuesta; por defecto no hay otras), pasa a un catálogo con atributos de comportamiento por ítem y su propio ADR.
- Una
ACCEPTEDque traía un borradorTRANSFERENCIA(lo guardabadatosPago()mientras no se pagaba, §3) no es historia: la pantalla la abre con Efectivo y sin cuenta, ypay()guarda lo que manda, así que la fila queda consistente al pagar. Mientras no se guarde ni se pague, la lectura de sus documentos requeridos sigue derivándose del valor guardado (los cuatro de transferencia): el backend no resetea nada al leer. - «Confirmar pago» conserva el control Medio de pago con Efectivo como única opción y ya elegido (QC-7, por defecto): es lo que pidió el cliente al pie de la letra y se revierte con una línea. Lo que el §3 decía de que
ConfirmActionModalpide la cuenta bancaria ya no ocurre.
Consecuencias. Es un cambio de contrato (422 donde antes 200): una pestaña con el frontend viejo y TRANSFERENCIA elegida recibe el 422 con ese mensaje. Con esto, todo PAGO de caja es efectivo (nota en ADR-005). Lo que ya había descontado de más una caja de Staging, antes de G3, se corrige con un AJUSTE por caja y no se borra (el ledger es inmutable): el procedimiento está en Staging. Producción nunca se aplicó. Si el pago por transferencia vuelve, no hay nada diseñado —ni qué hace con la caja ni con sus documentos—, y no es un cambio chico.
Actualización — G2.1 (2026-10-06): el §4 tiene una excepción para quien resolvió la transacción
El §4 acota los soportes de una transacción resuelta por PDV, y subirlos a quien la resolvió o a un Supervisor con alcance sobre ese PDV. G2.1 suma a leer (listar y descargar los soportes, la papeleta y el datos_pago) la misma excepción que ya tenía la subida: quien resolvió la tx (resolved_by_user_id) entra aunque el PDV de la tx sea otro, siempre después del permiso por país y solo para esa transacción. Es una sola definición, isResolverOf(), y comparte las tres preguntas (operar, ver y subir). La decisión, lo que no cambia y las consecuencias están en la actualización G2.1 del ADR-008.
Actualización — G5 (2026-10-06): subir lo que falta no es reemplazar lo cargado
Qué pasaba. El §4 decide quién puede subir un soporte después de resolver, y el backend no distinguía entre subir un tipo que falta y subir otro del mismo tipo que ya está cargado: ambos insertaban una fila, y la pantalla mostraba la más reciente (§5). Por eso el Cajero que pagó veía Reemplazar sin límite de tiempo, y el cliente de Guatemala lo pidió acotado (hoja de ajustes v2, ítems 2, 3, 6 y 8: en una transacción pagada los datos y los documentos no se modifican, y reemplazar un documento es de Supervisor y Administrador). No se puede aplicar literal «no modificar documentos de una tx pagada»: la papeleta firmada se escanea después de pagar y el cierre de caja la exige (PENDING_PAYMENT_DOCUMENTS), así que si quien pagó no pudiera subirla, no podría cerrar. Por eso «modificar» se lee como «reemplazar uno ya cargado» (decisión P3-1; que «guardar» sea «Confirmar pago» y no «Guardar datos» es lectura nuestra, pendiente de confirmar con el cliente, QC-2).
Qué se decidió. Una sola regla, con una tabla de estado × acción:
| Estado de la tx | Subir un tipo que falta | Reemplazar uno ya cargado |
|---|---|---|
ACCEPTED | Cualquiera con transacciones:write en el país (como hoy) | Igual: el Cajero corrige hasta «Confirmar pago» |
PAID / CANCELLED | Quien resolvió la tx, el Supervisor con alcance del PDV y el Admin | Solo el Supervisor con alcance del PDV y el Admin. Sin el atajo de quien resolvió |
PermissionService::canReplaceTransactionDocuments(User, Transaction)es la pregunta nueva.canManageTransactionDocumentssigue siendo la de subir, y queda como «quien resolvió, o quien puede reemplazar».TransactionDocumentController::storemira si ya hay un documento de esetype. Si lo hay, la tx no esACCEPTEDy el usuario no puede reemplazar, responde 403CANNOT_REPLACE_DOCUMENTSsin fila nueva y sin archivo en el almacenamiento (la autorización va antes de validar el archivo).index()devuelvepuede_reemplazarjunto apuede_subir, para que la pantalla ofrezca Reemplazar solo a quien puede.- «Supervisa» se evalúa dentro de UNA misma asignación (P3-2). El nuevo helper
PermissionService::assignmentHolds($user, $countryId, [[módulo, acción], …], ?$stationId)pregunta si hay una asignación del país que reúne todas las capacidades pedidas y cubre el PDV; una acción puede traer alternativas ('read|write'), una acción desconocida lanza. Cada uso declara las suyas, no hay una definición única de «supervisor»: para los soportes sonfondeo_caja:readmástransacciones:write. Con$stationIdnulo (una tx sin PDV) solo cubre una asignación sin acotar. La unión de permisos de D3-T2 no se reabre: sigue siendo la unión para el menú, para el alcance de datos y para pagar; lo que se acota es esta pregunta. - Auditoría (P3-3). Reemplazar deja la acción propia
TRANSACTION_DOCUMENT_REPLACED(tipo, id del documento reemplazado, estado de la tx y tamaño), una constancia por reemplazo: no deja además unaTRANSACTION_DOCUMENT_UPLOADED. El documento «reemplazado» es el vigente de ese tipo (el más reciente). Un reemplazo sobre unaACCEPTEDtambién se audita como tal, contransaction_statusACCEPTED. YTRANSACTION_DOCUMENT_UPLOADEDdeja de guardar el nombre original del archivo (H3-09): lo elige quien lo sube, y es habitual que traiga el nombre del beneficiario, a un registro que ve más gente que el propio soporte. El nombre sigue en el documento, para que quien lo sube lo reconozca. Los asientos viejos que lo guardaron no se reescriben (un asiento es inmutable), pero se ocultan al leer: el listado de Auditoría, su PDF y el historial de la ficha de la transacción —que ve cualquiera con lectura de Transacciones— pasan la metadata porAuditLog::withoutFileName(), que saca la claveoriginal_name. Cortar solo la escritura dejaba el dato personal saliendo por el export de lo ya cargado (revisión de G5). - Los soportes siguen sin editarse ni borrarse: reemplazar es subir otro del mismo tipo, y el anterior queda en la base y en el almacenamiento (§5, R8 del análisis funcional).
Cambio de comportamiento que conviene tener presente. Al pasar a «una misma asignación», cambia también quién puede subir: con asignaciones mezcladas (un Cajero del PDV A que es Supervisor del PDV B) la unión ya no lo hace supervisor del PDV A. Antes, el PDV salía de una asignación y «supervisa» de otra, y esa persona subía soportes de lo que había pagado otro en A. Ahora los sube en B, y en A solo lo que él mismo pagó. Lo prueba PermissionServiceTransactionScopeTest y, por API, DocumentosReemplazoApiTest. El aviso «Tenés N pagos con documentación pendiente» sigue la misma regla (revisión de G5): lista los PDVs de las asignaciones que son de Supervisor/Admin (PermissionService::stationIdsWhereAssignmentHolds) y, de los demás, solo lo que pagó la propia persona; antes sacaba los PDVs de la unión y le contaba pagos de A que la ficha le mostraba en «Solo consulta».
Alternativas descartadas.
- Bloquear todo soporte en una tx pagada: rompe el cierre de caja (la papeleta firmada es un documento posterior al pago) y deja sin salida al Cajero que pagó.
- Permitir reemplazar a quien pagó durante un rato (una ventana de minutos o hasta cerrar la caja): es una regla de tiempo que nadie pidió, difícil de explicar y de probar; el Supervisor ya es la salida y queda auditada.
- Una marca
reemplaza_documento_idenTRANSACTION_DOCUMENT_UPLOADED(en vez de una acción propia): no toca el catálogo de acciones, pero obliga a filtrar por metadata para saber quién corrigió qué. Es lo que habría que volver a mirar si algún día se prefiere no sumar acciones. - Una celda de la matriz para «reemplaza soportes»: cambiaría permisos de usuarios reales de Staging y el plan lo deja para cuando el cliente pida configurarlo por perfil. Se deriva de permisos que ya existen, como el resto del §4.
Consecuencias.
- Un Cajero que sube un archivo por error en el hueco equivocado (la papeleta firmada, por ejemplo) ya no puede corregirlo: depende de un Supervisor del PDV o de un Admin, y en un PDV sin Supervisor, solo del Admin. Es lo que pide el cliente y hay que decírselo al capacitar.
- Hay una carrera menor, aceptada: dos subidas simultáneas del mismo tipo faltante por quien pagó (un doble clic) pasan ambas, porque cuando se mira el documento vigente todavía no hay ninguno. No se serializa con un candado sobre la transacción porque la subida incluye escribir el archivo, y retener ese candado frena un pago de la misma transacción mientras tanto. La pantalla deshabilita la carga de todos los casilleros mientras hay una subida en curso.
- Y otra, también aceptada: un reemplazo que decide con la tx
ACCEPTEDmientras otro pedido la paga (el estado se lee al abrir el pedido, ypay()toma el candado, perostore()no). No cruza ninguna frontera de permisos: el resultado es el de haber hecho el reemplazo un instante antes del pago, que era legítimo con la txACCEPTED, y el documento anterior no se borra. Lo único engañoso es que el asientoTRANSACTION_DOCUMENT_REPLACEDdiceACCEPTEDy su hora es posterior al pago. Cerrarla exige retener el candado sobre la fila mientras se escribe el archivo, o partir el servicio en «guardar el archivo» y «registrar la fila»: por la misma razón de arriba, no se hizo. - Si la pantalla recibe un 403 al subir o reemplazar (el permiso cambió con ella abierta), además de avisar vuelve a pedir
puede_subirypuede_reemplazar, para dejar de ofrecer lo que el backend ya negó. - El contrato de
POST /transacciones/{id}/documentos(403CANNOT_REPLACE_DOCUMENTS) y deGET /transacciones/{id}/documentos(puede_reemplazar) queda fijado porDocumentosReemplazoApiTestyTransactionDocumentApiTest.
La pantalla (G5.4 y G5.6). Cada fila de soportes ofrece una acción: Subir si puede_subir y no hay documento, Reemplazar si puede_reemplazar y ya lo hay, y nada más. Quien tiene soportes cargados y no puede reemplazarlos ve «Solo consulta: los documentos cargados no se modifican; si hay un error, pedíselo a un Supervisor o Admin»; quien sí puede ve «Subido por mail el dd/mm» en cada fila, el dato que necesita para decidir. useTransactionDocuments expone puedeReemplazar aparte de puedeSubir y arranca en false (ante la duda no se ofrece, ni cuando una respuesta viene sin el campo). La respuesta de POST trae la misma forma que un elemento de la lista (uploaded_by con id y mail, y created_at), para que la fila no pierda la procedencia hasta recargar. Y los campos de Datos del pago de una pagada, que ya estaban disabled y se rechazaban con 409 PAYMENT_DATA_LOCKED, se ven deshabilitados: el preflight de Tailwind los dejaba idénticos a los editables y el cliente lo leyó como «se pueden modificar».
El formato del número de identificación (G11, 2026-10-07). Este ADR dejó identification_number como un texto libre de hasta 60 caracteres y identification_country como cualquier país de la lista. Desde G11 cada tipo de identificación del catálogo puede traer su formato (caracteres, largo y país emisor) y datosPago() y pay() lo hacen respetar con la misma regla: el DPI son 13 dígitos y lo emite GT; el Pasaporte, de 7 a 13 alfanuméricos y de cualquier país. Nada de lo anterior cambia: los datos viejos no se revalidan (D9), una PAID o CANCELLED sigue respondiendo 409 antes de validar nada y el número guardado en una pagada es inmutable. Ver ADR-023.

