Preguntas Abiertas — Pago con documentos
Análisis Funcional: Pago con documentos — parte 5 de 5. ← La papeleta · Índice
Lo que el cliente todavía no definió, más lo que se resolvió por criterio del equipo y nunca se validó. Mismo formato que las Preguntas Abiertas del Módulo Caja y las del análisis original: numeradas, con estado y fecha, y sin redondear como cerrado nada que no lo esté.
Estados: ✅ RESUELTO · ⚠️ ABIERTA · 📌 PENDIENTE NO BLOQUEANTE
4.1 Abiertas
2. ¿Cuál es el teléfono de servicio al cliente? — ⚠️ ABIERTA (2026-08-07). No bloqueante.
Los dos modelos Word —la papeleta y el formulario de enrolamiento— cierran con la misma línea:
"Para contactarse con servicio al cliente llame gratis al: XXXXXXXXXXX"
El cliente mandó la plantilla sin completar el número. Once equis no son un formato: son un marcador.
Cómo está resuelto hoy: la app lo lee de la configuración (app.customer_service_phone, la variable de entorno CUSTOMER_SERVICE_PHONE) y, si está vacía, cada formato hace una cosa distinta:
- La tirilla de 58 mm imprime un guión (
PapeletaService::datosBase()): sale una línea que dice "llame gratis al: —". - La hoja A4 omite la línea entera mientras no haya número (ver La papeleta, §3.3), así que no imprime un guión donde iría un teléfono.
En un entorno sin la variable —el local y los de test— la línea no sale en el A4: los tests de "una sola hoja" fijan un número para medir el recibo como va a salir en producción.
Qué hace falta: el número, y una definición sobre si es uno solo o uno por país. Guatemala y Ecuador operan mercados distintos; un 1-800 de Ecuador impreso en un ticket guatemalteco no sirve de nada. Hoy la configuración es global — si la respuesta es "por país", hay que moverla a la tabla de países.
No bloquea la entrega. Bloquea imprimir tirillas de verdad en producción: un comprobante que el cliente firma no puede salir con un guión donde va un teléfono. El A4, que es el formato de Guatemala, sale sin la línea en vez de con un guión, pero tampoco da el servicio que el modelo del cliente pide hasta que el número esté cargado.
4. Los cuatro documentos de transferencia van "por una sola vez por cliente", pero no existe la entidad Cliente — ⚠️ ABIERTA (2026-08-07). No bloqueante.
Actualización (2026-10-05, G3): desde que el medio de pago es solo efectivo (ver la pregunta 3, en la sección 4.3) ya no entra ningún pago por transferencia nuevo, así que esta pregunta deja de importar para lo que se hace de acá en adelante. Queda como registro de lo que piden las
PAIDviejas por transferencia, que siguen pidiendo sus cuatro documentos por transacción. Si el pago por transferencia vuelve, esta pregunta vuelve con él.
El material es explícito en la fila 20 de la hoja Módulo caja:
"Pago con tx bancaria: a los documentos anteriores se suman los siguientes, por una sola vez" — formulario de enrolamiento, cartola de banco, solicitud de pago con transferencia, y mail de confirmación de acreditación.
"Por una sola vez" significa por cliente, no por transacción: un beneficiario que se enrola una vez no tiene que volver a presentar su formulario de enrolamiento ni su cartola bancaria en cada giro. Es lo razonable — son documentos de alta, no de operación.
El problema: el modelo de datos no tiene ninguna entidad que agrupe transacciones de la misma persona. Una transacción trae nombre, apellido, mail, teléfono y fecha de nacimiento como campos sueltos; no hay un Cliente con id propio al que colgarle documentos reutilizables.
Cómo está resuelto hoy: los cuatro se piden por transacción. Está anotado en el propio modelo:
// backend/app/Models/TransactionDocument.php:57-62
/**
* Se suman cuando el pago es por transferencia bancaria. El material
* aclara que van *"por una sola vez"* por cliente — pero como todavía no
* existe una entidad Cliente que los agrupe, por ahora se piden por
* transacción.
*/O sea que la app le va a pedir al operador que suba el mismo formulario de enrolamiento en cada giro del mismo beneficiario. Funciona, pero es trabajo repetido, y el operador lo va a notar antes que nosotros.
Qué hace falta: decidir si se crea una entidad Cliente —con la pregunta no trivial de cómo se identifica unívocamente a una persona entre transacciones: ¿por número de identificación? ¿por número más país emisor?— o si se acepta la duplicación. La decisión depende de cuánto volumen de clientes recurrentes con transferencia haya, que hoy nadie sabe porque la figura ni siquiera está confirmada (#3).
No bloquea: la completitud funciona igual, solo pide de más.
14. ¿Qué imprime el recibo de un país que paga en moneda local? — ⚠️ ABIERTA (2026-10-02). No bloqueante hoy; bloquea activar pago_en_moneda_local.
La revisión de B5 lo encontró mirando el A4, pero vale para los dos formatos: comparten el armado de los datos (PapeletaService::datosBase()).
Cuando un país tiene pago_en_moneda_local encendido, el pago congela el tipo de cambio y descuenta la caja a monto × TC en la moneda local (el movimiento de caja guarda el monto local, el TC y la moneda). El recibo, en cambio, imprime Money::format($transaction->amount, paymentCurrency()): el monto en dólares con el código de la moneda local, y la tasa fija 1.00000000. Una transacción de USD 4,143.71 sale como GTQ 4,143.71 en monto enviado, recibido y total, mientras la caja se descontó por el monto convertido. Es un documento que el cliente firma con el importe y la moneda equivocados.
Hoy nadie lo ve: Guatemala paga en dólares (ADR-007 §6) y ningún país tiene el campo encendido. Pero el Admin puede encenderlo desde Países en cualquier momento.
No se corrigió porque toca plata y porque cambia lo que firma el cliente: qué monto va en cada renglón (¿enviado en dólares, recibido en moneda local, total?) es una definición de tesorería, no un detalle de implementación. La tirilla además no puede cambiar (P9).
Qué hace falta: que Carlos o Teresa digan qué debe imprimir el recibo cuando se paga en moneda local y si eso también aplica a la tirilla. Con eso, la corrección es chica: tomar el monto local y el tipo de cambio del movimiento de caja del pago —congelados, no el vigente— y agregar un test del recibo con un país en moneda local. Mientras tanto, conviene no encender pago_en_moneda_local en un país que imprima recibos.
15. ¿Cuántos días vale un MTCN en Guatemala? — ⚠️ ABIERTA (2026-10-05). No bloqueante.
Desde el 2026-10-05 el MTCN vence y una transacción de la API vencida no se puede pagar: la cancela el sistema y se lo avisa a Soterex (§1.7, ADR-017). Cuántos días vale lo decide un valor por país, y para Guatemala es 60: el plazo que figura en la carta que Soterex le manda al beneficiario. Es un valor tomado de un documento, no confirmado por escrito: hasta el 2026-10-05 el código tenía 30 días como default provisional, y ninguna de las dos cifras se validó con Soterex.
Se le pregunta en el sign-off (doc/integracion/2026-10-06-c2p-sign-off.md) y en el mail a Sean. El costo de que sea otra cifra es bajo: cambiar el valor del país no toca lo ya creado (cada transacción conserva su expires_at) ni la lógica. Hoy no hay una pantalla para editarlo (el campo se carga por migración de datos o CountrySeeder; Países no lo muestra), así que un cambio de cifra es una migración chica.
Qué hace falta: que Soterex confirme que 60 días es lo que esperan, o diga otra cifra. Mientras tanto rige 60. Lo que sí hay que evitar es cambiarlo en producción con transacciones pendientes sin avisar a Soterex, porque la fecha que se le devolvió en expiration_date es la que le informa al beneficiario hasta cuándo puede cobrar.
16. ¿Quién puede pagar una ACCEPTED que otro PDV ya reclamó? — ⚠️ ABIERTA (2026-10-06). Decisión de Carlos. No bloquea G2.
El PDV de una ACCEPTED lo fija el primer documento que sube cualquier operador (ADR-008 §1). Desde ese momento, un Cajero acotado a otro PDV que la busca no puede ver los tres documentos previos (404) y la pantalla de Pago le deja Pagar deshabilitado (desde L2 los documentos se ven recién al tocar Iniciar pago; ahí la tarjeta dice que no se pudo cargar la documentación), aunque el backend, en pay(), solo mire que los tres existan. Y por API sí la puede pagar: cualquier Cajero del país con pago:write y una caja con saldo, y desde el pago ve esos soportes (incluida la identificación del beneficiario) por la excepción del pagador de G2.1.
Hay dos salidas y ninguna se tomó: (a) 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 (entonces pay() debería exigirlo, para que la API no sea más permisiva que la pantalla), o (b) abrir la lectura de esos tres documentos previos, que son PII, a quien va a pagar.
Qué hace falta: la decisión de Carlos. Mientras tanto rige lo de hoy (pantalla estricta, API permisiva), documentado en la actualización G2.1 del ADR-008 («Tres consecuencias de la excepción») y en el caso 4 del plan de pruebas de G2. Es un punto de entrada para la revisión de seguridad del MVP1 (E6).
4.2 Pendientes no bloqueantes
6. Género y estado civil: ¿se agregan al modelo? — 📌 PENDIENTE (2026-08-07).
El formulario de enrolamiento los pide. El reporte regulatorio no. Soterex no los manda.
La decisión depende enteramente de si el formulario se genera desde el sistema (como sugirió el cliente en la fila 21) o se sigue subiendo escaneado. Hoy se sube escaneado, así que los dos campos no hacen falta. Ver §3.9.
Qué hace falta: confirmar si CIS-EC quiere que la app emita el formulario. Si la respuesta es sí, se agregan los dos campos al formulario de datos del pago; si es no, no se agregan nunca.
7. La protección de los documentos es detectiva, no preventiva — 📌 PENDIENTE (2026-08-07). Para la auditoría de seguridad.
Lo implementado en §2.5 cubre lo esencial: sin URL directa, alcance por PDV, cada acceso auditado, sin borrado, path generado por el servidor. Es sólido para el flujo normal.
Lo que no cubre, y conviene que quede escrito antes de que la auditoría de seguridad lo encuentre:
- No hay política de retención ni expiración. Los documentos de identidad se guardan indefinidamente. Para datos de personas migrantes, "para siempre" es una decisión, no un default neutro. (Desde G1 el bucket expira las versiones no vigentes —90 días en Staging, 365 en Producción—, pero el soporte vigente no expira nunca: es la parte que falta acordar con CIS-EC.)
- No hay cifrado a nivel aplicación sobre el contenido. Se confía en el cifrado en reposo del bucket de S3 (SSE-S3, con claves administradas por S3, no una clave propia), que protege contra el acceso al disco, no contra credenciales comprometidas. Ese bucket existe desde G1: este texto lo daba por hecho en agosto, cuando todavía no se había construido (ADR-019).
- Cualquier operador con
transacciones:writeen su PDV puede descargar cualquier documento de ese PDV. La auditoría registra quién miró qué; no impide que mire. - La tabla de auditoría crece con cada preview. Abrir la ficha de una transacción y mirar sus cuatro soportes escribe cuatro registros. No es un problema hoy; a volumen puede serlo.
Qué hace falta: que esto entre explícitamente en el alcance de la auditoría de seguridad pendiente del plan, con una definición de retención acordada con CIS-EC.
8. Cambiar el medio de pago cambia la completitud retroactivamente — 📌 PENDIENTE (2026-08-07). Sin validar con el cliente.
Actualización (2026-10-05, G3): el backend ya no acepta
TRANSFERENCIAal escribir, así que a una transacción no se le puede cambiar el medio a transferencia y el caso de abajo no se puede dar de nuevo. Lo que queda es el sentido inverso, que no cambia ninguna regla: unaACCEPTEDque traía un borradorTRANSFERENCIAse abre con Efectivo y, al guardarla, deja de pedir los cuatro documentos. LasPAIDviejas conservan su medio y su completitud.
Una transacción marcada como completa en efectivo pasa a incompleta apenas se cambia su delivery_type a transferencia, porque los cuatro documentos adicionales entran en juego (ver §2.3).
Es el comportamiento correcto —los documentos efectivamente hacen falta— pero nadie se lo validó al cliente, y en pantalla se ve como un badge que pasa de verde a naranja sin que el operador haya tocado ningún documento.
Qué hace falta: confirmar que se espera ese comportamiento, y evaluar si hace falta un aviso explícito al cambiar el medio de pago sobre una transacción ya pagada. Es un cambio de UX chico si la respuesta es sí.
13. Validar con el cliente la lectura de columnas del reporte de Cumplimiento — 📌 PENDIENTE (2026-10-02), respondida en parte (G9). No bloqueante.
El reporte ya sale (punto 5), pero algunas celdas son la lectura del product owner de cómo el cliente llena hoy su planilla a mano, y nadie se las validó:
- Columnas 23, 24, 29 y 30 — el cliente contestó el 2026-10-02 (G9):
Payer Name(24) ✅ «CIS Guatemala», ahora por país (un mapa por ISO enconfig/cumplimiento.php; un país sin entrada sale vacío, no se inventa).Additional Notes(30) ✅ siempre en blanco; el encabezado se mantiene y el reporte dejó de leer la auditoría de las cancelaciones.Transaction Status - Update(29): ✅ el estado real, pero abierto en qué idioma lo quieren: salePending/Paid/Cancelledy ellos lo escribieron «pendiente, pagada o cancelada» (QC-20). No se toca.Transaction Status(23):Sentsiempre, pero abierto: su mail dice «Send» y nuestro archivo dice «Sent» (QC-19). Es un archivo regulatorio y una letra de diferencia es un error, así que no se adivina: queda en una constante hasta ver una fila de su planilla.
- Columnas 33 a 36 (Paid at Branch): solo las pagadas llevan agencia. El plan no condicionaba estas columnas al estado, pero una pendiente puede tener PDV (lo toma con el primer documento que sube el cajero, ADR-008) y una cancelada por un usuario también (el de quien cancela): ninguna se pagó ahí, y el regulador leería que sí. Se dejan en blanco salvo en
PAID. Es una celda de un servicio si el cliente prefiere otra cosa. - Columnas 25 a 27 en una cancelada o pendiente salen con la moneda de pago del país (y, si es dólares, tipo de cambio 1 y el principal), no vacías.
- Las fechas van como texto
d/m/Y, no como fecha de Excel: la fecha de nacimiento no tiene una cota de edad validada, y un año tipeado de más no sería una fecha válida de Excel. El costo: en Excel no se ordenan ni se filtran por fecha. - El prefijo
C-del MTCN (columna 21): el cliente pidió mantenerlo «salvo que Soterex ya no lo use». Se aplicó ya, por configuración (CUMPLIMIENTO_MTCN_PREFIX, defaultC-; vacía lo apaga sin tocar código) y solo en esa columna: el PIN (22) va sin prefijo, y el almacenamiento, la API, los recibos y los extractos siguen con los 10 dígitos. Falta que Soterex confirme si lo sigue usando (QC-21 y la consulta S-2).
Qué hace falta: que Magaly confirme las dos lecturas que quedan abiertas (23 y 29) con la planilla del cliente en la mano, y las demás que no contestó. Ajustar cualquiera es cambiar el servicio del reporte, no el modelo.
4.3 Resueltas
9. ¿El PIN de pago es un dato separado del MTCN? — ✅ RESUELTO (2026-08-07): es el mismo dato.
El análisis del material había concluido que el "PIN Number" de la carta era un control de seguridad que no teníamos modelado, y el primer borrador del diseño técnico agregaba una columna pin a transactions.
Resolución (Carlos, 2026-08-07): no son dos datos. La app genera el MTCN y se lo responde a Soterex, que lo imprime en la carta del beneficiario, donde aparece dos veces — MTCN: C-5436014032 y Payment PIN: 5436014032. No se agregó ninguna columna. (La verificación contra el MTCN que tolerara el prefijo C- se sacó el 2026-08-10, ver abajo; lo que hoy tolera el prefijo es la búsqueda de Pago y el filtro del Reporte individual, desde G9.5 del 2026-10-07.)
Consecuencia (revisada el 2026-08-10): se implementó una verificación y se sacó al probarla. Buscando por número de transacción —el camino habitual, porque el cliente llega con la carta— pedía retipear el número que se acababa de tipear. Sólo aportaba algo por el camino de búsqueda por nombre; si ese escenario aparece en la operación real, se puede reponer acotado a ese caso. El razonamiento completo está en §1.2.
10. ¿"Pagada pero incompleta" es un estado nuevo? — ✅ RESUELTO (2026-08-07): no, se deriva.
El cliente lo planteó como posibilidad a evaluar (hoja Módulo caja, fila 14).
Resolución: status no cambia. La completitud se deriva de los documentos que la transacción tiene contra los que su medio de pago exige, y se expone como documentacion_completa más la lista de faltantes. Las tres razones están en §2.4.
11. ¿El pago se bloquea si faltan documentos? — ✅ RESUELTO (2026-08-07): no.
Resolución: no se bloquea, ni por documentos ni por datos. La plata ya se entregó en el mostrador; frenar el registro no evita el problema, lo convierte en un descuadre de caja contra la realidad física. Ver §1.4.
12. ¿De dónde salen la fecha de nacimiento y la nacionalidad? — ✅ RESUELTO (2026-10-02): las carga el cajero.
El reporte de Cumplimiento las pide (columnas 3 y 4) y la API de Soterex no las manda: SendRequest no define ninguna de las dos. Las columnas existían en transactions, pero nadie las escribía, y la pantalla las mostraba en el bloque "Datos enviados por Soterex" como si fueran de Soterex. La pregunta era si dejarlas fuera del formulario y que el reporte las llevara vacías, o pedirlas.
Resolución (Carlos, 2026-10-02, P12 del plan v2): las carga el cajero en los datos del pago. Son obligatorias como el resto (C1 / ADR-011), la nacionalidad es texto libre y la fecha una fecha pasada, sin edad mínima ni máxima. Salen del bloque de Soterex. Ver §2.1 (actualización de B4.0) y la nota fechada en ADR-011.
Lo que queda por avisarle al cliente: que el formulario del cajero tiene dos campos obligatorios más, y que las transacciones que ya esperan los piden antes de pagarse.
3. ¿Existe la figura de pago con transferencia bancaria? — ✅ RESUELTO (2026-10-05, G3): no. El medio de pago es solo efectivo.
Cómo estaba (2026-08-07, "definición de Teresa"). El material de CIS-EC describía la figura con detalle (hoja Módulo caja fila 12: "seleccionando el medio de pago correcto: efectivo, transferencia bancaria"; la columna
AAdel reporte pedía "un box para escoger el medio de pago"; la fila 20 listaba los cuatro documentos adicionales y la columnaABlos datos de cuenta bancaria), pero dejaba abierto si la figura existía o se dejaba solo efectivo. Se implementó completa aunque estuviera sin confirmar: el costo de tenerla sin usarla era una opción más en un<select>.Quedaba además una segunda pregunta, de plata: ¿un pago por transferencia descuenta la caja física? Todo el Módulo Caja asume efectivo, y la app descontaba igual. Era un descuadre latente anotado como bloqueante: la caja reportaba menos efectivo del que tenía.
Resolución. El medio de pago es siempre efectivo. Carlos lo dejó dicho el 2026-09-30 (C13 del plan de ajustes v2) y el cliente lo pidió en su hoja del 2026-10-02: que se saque la transferencia de los medios de pago (RV3-12) o, si no se saca, que no afecte el saldo del PDV (RV3-13). Se sacó de la pantalla y del backend (D3-4 b del plan de ajustes v3, entrega G3): dejarla viva por la API era dejar vivo el defecto. Como quedó:
- El backend solo escribe efectivo.
PATCH /transacciones/{id}/payy/datos-pagoresponden422conerrors.delivery_type(«El medio de pago solo puede ser efectivo.») si mandanTRANSFERENCIAo cualquier otro valor, antes de tocar la caja o el prefondeo. La lista de lo que se acepta es una constante en código (Transaction::DELIVERY_TYPES_ACEPTADOS), no un catálogo (D3-5 a). - «Confirmar pago» sigue mostrando el control Medio de pago, con Efectivo como única opción y ya elegido, y sin el bloque de cuenta bancaria. Se dejó visible porque es lo que pidió el cliente al pie de la letra; si prefiere que desaparezca de la pantalla es una línea (QC-7, sin respuesta: queda el valor por defecto).
- La historia no se reescribe. Los datos del pago de una
PAIDson inmutables (ADR-011): unaPAIDvieja por transferencia se ve en solo lectura, con su cuenta bancaria, y sigue pidiendo sus cuatro documentos (ver §2.3). UnaACCEPTEDque traía un borradorTRANSFERENCIAno es historia: se abre con Efectivo y se paga con Efectivo. - La segunda pregunta desaparece: todo
PAGOde caja es efectivo. Lo que ya había descontado de más una caja en Staging se corrige con unAJUSTEpor caja (elPAGOno se borra: el ledger es inmutable); el procedimiento está en Staging. Producción nunca se aplicó.
Lo que no se definió y no se diseñó: si más adelante vuelve el pago por transferencia, o aparece otra forma de pago, no hay nada pensado sobre qué pasa con la caja ni con los documentos, y no es un cambio chico (QC-8 sigue sin respuesta: por defecto, no hay otras formas).
5. El reporte regulatorio de 36 columnas — ✅ RESUELTO (2026-10-02, B4): existe, con permiso propio y auditado.
Cómo estaba (2026-08-07): E5a agregó los campos para ese reporte, pero el reporte era una entrega propia que no estaba en ningún plan cerrado. El mapeo columna por columna vive en un adjunto del mail de Maggie (
Soterex - Reporte completo.xlsx, hoja Request Pilot List) que no está en el repositorio por contener 2.957 transacciones reales con datos personales de personas migrantes. El riesgo era silencioso: nadie había verificado que los 13 campos agregados cubrieran todo lo que faltaba, y quedaban sin dueñoPayer Name,Transaction Status - Update,Additional NotesyPaid at Branch City/State.
Cómo se resolvió (plan Ajustes v2 del cliente GT, entrega B4):
- El mapeo está traducido a un documento propio, sin datos personales: 36 columnas con sus nombres y de dónde sale cada una (§B4 del plan). Un test compara la lista entera de encabezados.
- Fecha de nacimiento y nacionalidad (columnas 3 y 4) las carga el cajero en los datos del pago (punto 12). Provincia y ciudad del PDV (34 y 35) salen de los catálogos del país (B4.1).
- Las cuatro columnas que el cliente llenaba a mano tienen ahora una lectura:
Transaction StatusesSent;Payer Namesale de configuración;Transaction Status - Updatees el estado real (Pending,Paid,Cancelled);Additional Notesera el PDV si estaba pagada y el motivo si estaba cancelada. (El cliente contestó el 2026-10-02:Payer Namees «CIS Guatemala» por país yAdditional Notesva siempre en blanco; el MTCN sale con el prefijoC-. Ver el punto 13.) Eran la lectura del product owner: ajustarlas es cambiar un servicio, no el modelo. - Es un Excel de descarga, con permiso propio
reporte_cumplimiento(solo Admin) y una auditoría que registra el pedido y la cantidad de filas, nunca el contenido. El detalle de cómo se arma y qué lo protege está en Secuencias de pantalla, 5.7.
Lo que queda pendiente de este punto es la validación de esas cuatro columnas con el cliente, y está como un punto aparte, la pregunta 13 de la sección 4.2.
1. ¿Qué es "TRANSACCIÓN FIJA: SI / NO"? — ✅ RESUELTO (2026-10-14): se sacó del A4.
Cómo estaba (2026-08-07): el modelo Word de la papeleta imprimía, en la misma línea que la moneda y la tasa de cambio, «TRANSACCIÓN FIJA: SI / NO», con las dos opciones visibles para que el operador marcara una a mano. Nadie supo explicar qué significa: no había ninguna otra mención en el material, ni una columna equivalente en el reporte, ni un campo en el modelo de datos. La tirilla de 58 mm lo omitía; el A4 lo imprimía tal cual.
El cliente contestó el 2026-10-14 (pregunta 6 de la ronda de ajustes): «Eliminar ese texto». Ya no se imprime en ninguna copia: la fila de estado del A4 queda solo con Tipo de transacción: PAGADO. No hay nada que definir: el campo nunca existió en el modelo de datos.
Análisis Funcional: Pago con documentos — parte 5 de 5. ← La papeleta · Índice

