Skip to content

Plan de Pruebas — G4a: el PDV de cada pago, y el 422 al multi-PDV sin PDV activo ​

Fecha: 2026-10-06 Decisión: ADR-020 · plan de ajustes v3, entrega G4a (G4.1, G4.2, G2.2 y G4.7; RV3-17, H3-08, D3-3 a, D3-7 b, D3-8) Ambiente: Dev local (./start-dev.sh) — http://localhost:5173 — o Staging con las cuentas de prueba

Qué cambió: de dónde sale el PDV de un pago. Con módulo Caja, el PDV de la caja de la que sale la plata llena el hueco cuando la persona no tiene PDV activo ni un único PDV; con dos o más PDV, sin PDV activo y sin caja que lo desempate, subir el primer documento o pagar responde 422 en vez de dejar la transacción sin PDV; las asignaciones se leen en un orden fijo; y los PAID viejos sin PDV lo recuperan de su movimiento de caja. Ver Pago con documentos, §1.6.

Lo que se ve por pantalla: el aviso del 422 (el mensaje del backend, con un título que dice dónde se elige el PDV activo), que el pago aparezca con su PDV en Reporte individual y el aviso ámbar «Sin PDV activo» en la ficha de usuario (G4.6, caso 6). La columna «Procesada por» y los rótulos del Reporte individual son de las entregas que siguen (G4.3 a G4.5).

Antes de empezar ​

Usuarios (las contraseñas están en doc/environments/dev.md):

EmailRolAlcancePara qué sirve acá
supervisor@cislatam.testSupervisorGT-CAP-001 y GT-QUE-002, sin PDV activoEl usuario multi-PDV de los casos 1 y 2
admin@cislatam.testAdminGuatemala, todos los PDV, con PDV activo GT-CAP-001 (lo dejan así los seeders de dev y de Staging)Fija el PDV activo de otros (caso 2). Para que sea el alcance sin acotar y sin PDV activo (casos 3.1, 3.2 y 6.6) hay que vaciarle el PDV activo en su ficha antes, y devolvérselo al terminar
backoffice@cislatam.testCajeroSolo GT-CAP-001Control: un solo PDV, no cambia nada
tesoreria@cislatam.testTesoreríaGuatemalaFondea la caja del que paga, si hace falta

Transacciones de prueba: varias ACCEPTED sin documentos (el seed de demo las trae; si hace falta una nueva, el comando tinker está en el plan de pruebas de ADR-008). Una por caso.

Cajas: una caja abierta hoy y con saldo mayor que el monto a pagar, a nombre de quien paga (en Saldos). Si quedó abierta de un día anterior hay que cerrarla y abrirla de nuevo (ADR-013).


1. Dos PDV, sin PDV activo: sin caja se rechaza, con caja el PDV es el de la caja (supervisor@) ​

#PasoResultado esperado
1.1Entrar como supervisor@ sin ninguna caja abierta a su nombre. En Pago, buscar una ACCEPTED y subir la CartaSe rechaza con una notificación titulada «Falta tu PDV activo», que dice «Tenés más de un PDV asignado y ninguno marcado como activo, así que no se sabe en cuál estás trabajando. Abrí tu caja desde la pantalla Saldos… o pedile a un Administrador que fije tu PDV activo…» y queda unos 12 segundos. No dice «El archivo no es válido» (era lo que mostraba antes de G2.2). No queda ningún documento subido
1.2(Opcional) En Adminer: select station_id from transactions where mtcn = '…' y select count(*) from transaction_documents where transaction_id = '…'station_id NULL y 0 documentos: el rechazo no escribe nada
1.3En Saldos, abrir una caja en GT-QUE-002Caja del día abierta
1.4Volver a Pago, buscar la misma transacción y subir la CartaSe sube sin error. En Adminer, station_id es el de GT-QUE-002
1.5Subir identificación (anverso y reverso), completar los datos del pago, Iniciar pago → Confirmar pagoLa transacción pasa a PAID y descuenta la caja. station_id sigue siendo el de GT-QUE-002
1.6Como supervisor@, ir a Reporte individual y filtrar PagadaAparece la transacción que acaba de pagar, con su PDV GT-QUE-002 (antes de este cambio quedaba sin PDV y no la veía)
1.7Cerrar la caja en Saldos y, sin abrir otra, buscar otra ACCEPTED con los tres documentos subidos (por otro usuario o por el admin) y tocar Iniciar pago → Confirmar pagoEl aviso es el de siempre, «No tenés ninguna caja abierta a tu nombre…» (NO_CASH_BOX_OPEN_FOR_USER), no el del PDV activo: abrir la caja es lo primero que hay que hacer, y al hacerlo se resuelve también el PDV
1.7bSolo en un país sin Caja (en Guatemala el pago da antes el aviso de la caja del paso 1.7; en dev no hay un país sin Caja con usuarios de prueba, así que lo cubren PagoView.spec.ts y TransaccionDetalleView.spec.ts): como un usuario con dos PDV y sin PDV activo, Iniciar pago → Confirmar pago en Pago, y Cambiar a PAID en la ficha de la transacciónLa misma notificación «Falta tu PDV activo» con el mensaje del backend; el modal de confirmación se cierra y la transacción sigue ACCEPTED. No dice «No se pudo procesar el pago» ni «ya fue actualizada»
1.8Como admin@, AuditoríaDel paso 1.1 no hay ningún TRANSACTION_DOCUMENT_UPLOADED (el rechazo no deja rastro de subida); el TRANSACTION_STATION_BACKFILLED solo aparece si el deploy completó algún pago viejo (caso 5)
1.9Dejar abierta de ayer la caja de supervisor@ (en dev: abrirla en Saldos y en Adminer update cash_sessions set opened_at = opened_at - interval '1 day' where status = 'OPEN' and opened_by_user_id = '…'). En Pago, subir el primer documento de una ACCEPTED nueva422 «Falta tu PDV activo» como si no tuviera caja, y el mensaje dice que, si la tiene abierta de un día anterior, la cierre y la abra de nuevo. No se sube nada. Una caja vencida no desempata: si lo hiciera, la transacción quedaría atribuida a esa caja y el pago saldría de la que abra hoy
1.10Cerrar la caja vencida en Saldos, abrir una en GT-CAP-001 y subir el primer documento de esa misma transacciónSe sube; station_id es el de GT-CAP-001 (la caja de hoy)

2. El PDV activo gana sobre la caja ​

Es la decisión D3-7 (b) y no es un defecto: la caja llena huecos, no pisa. Queda documentada para que cambiarla sea una decisión.

#PasoResultado esperado
2.1Como admin@, en la ficha de supervisor@ fijar el PDV activo = GT-CAP-001 (Administración, Usuarios)Se guarda
2.2Como supervisor@, tener abierta la caja de GT-QUE-002 (otro PDV). Subir el primer documento de una ACCEPTED nueva y pagarlaSe sube y se paga sin rechazo. station_id es el de GT-CAP-001 (el PDV activo), aunque la plata salió de la caja de GT-QUE-002
2.3En Saldos, mirar el movimiento del pagoEl PAGO está en la caja de GT-QUE-002
2.4Quitarle el PDV activo a supervisor@ (campo vacío) y repetir el caso 1 con otra transacciónVuelve a valer el PDV de la caja (paso 1.4)

3. Sin acotar y un solo PDV: no se rechaza ​

#PasoResultado esperado
3.1Como admin@ con el PDV activo vaciado (ver «Antes de empezar») y sin caja abierta, subir el primer documento de una ACCEPTEDSe sube (no se rechaza): un alcance sin acotar no tiene un PDV que elegir. station_id queda NULL
3.2Como admin@ (PDV activo todavía vacío) con una caja abierta en GT-QUE-002, subir el primer documento de otra ACCEPTEDstation_id es el de GT-QUE-002. (Con el PDV activo de fábrica, GT-CAP-001, sería GT-CAP-001: el activo gana, como en el caso 2)
3.3Como backoffice@ (Cajero, un solo PDV), subir el primer documento y pagarTodo como siempre; station_id es GT-CAP-001
3.4Como supervisor@ (con la caja abierta en GT-QUE-002), buscar una ACCEPTED cuyo primer documento ya subió backoffice@ (PDV GT-CAP-001) y pagarlaEl pago se hace y station_id sigue en GT-CAP-001: lo fijó el primer documento y no se pisa. (Si pantalla le impide iniciar el pago por no ver los documentos de otro PDV, ver el caso 4 del plan de G2; se prueba por API en PdvDelPagoApiTest)

| 3.5 | La causa 6 por otra puerta: como admin@ (PDV activo vaciado) con una caja abierta en GT-QUE-002, subir el primer documento de una ACCEPTED con los tres documentos; después, como backoffice@ con su caja de GT-CAP-001, pagarla | La transacción queda PAID en GT-QUE-002 (el PDV que fijó el primer documento) y la plata sale de la caja de GT-CAP-001. Es lo previsto (ADR-020, «Lo que NO cambia»), no un defecto |

4. Verificación por API: país sin módulo Caja y casos de la caja ​

En dev solo Guatemala tiene Caja y no hay un país sin Caja con usuarios de prueba; el comportamiento se verifica por API:

bash
docker exec soterex-backend-1 php artisan test --filter 'PdvDelPagoApiTest|PermissionServiceTransactionScopeTest'
#Qué comprueba el testResultado esperado
4.1País sin Caja, dos PDV, sin PDV activo: subir el primer documento y pagar422 ACTIVE_STATION_REQUIRED en las dos; no queda archivo, documento, PDV, movimiento, saldo tocado ni evento de Auditoría
4.2Lo mismo con PDV activoPasa, y el PDV de la transacción es el activo
4.3Alcance sin acotar, o una asignación del país sin PDVs que convive con una acotada a dosNo se rechaza; sin Caja la transacción queda sin PDV, como siempre
4.4Con Caja, sin caja abierta422 NO_CASH_BOX_OPEN_FOR_USER al pagar (no el código nuevo)
4.5Con Caja, una caja abierta en otro paísNo desempata: 422 ACTIVE_STATION_REQUIRED al subir el primer documento
4.6Pagar una transacción que ya tiene PDVPasa: el PDV no iba a quedar vacío
4.7Dos asignaciones del mismo país con PDV activo distinto, leídas en cualquier orden (PermissionServiceTransactionScopeTest)Gana siempre la asignación más antigua (H3-08)
4.8Con Caja, la caja abierta es de otro usuarioNo desempata: 422 ACTIVE_STATION_REQUIRED al subir el primer documento
4.9Con Caja, la caja abierta es de ayer (vencida)No desempata al subir (422 ACTIVE_STATION_REQUIRED) y pagar da CASH_SESSION_FROM_PREVIOUS_DAY; cerrarla y abrir otra deja la transacción en el PDV de la nueva
4.10Dos sesiones abiertas del mismo usuario (de antes de E4b.1)Se usa la más reciente, la misma de la que pay() descuenta la plata
4.11El Supervisor con dos PDV paga con la caja abierta en BSu pago está en GET /transacciones, su ficha da 200 y el Dashboard lo suma (paid_today_count)
4.12Lo mismo, visto desde el reporte de Cumplimiento (ReporteCumplimientoApiTest)Las columnas 33 a 36 («Paid at Branch…») salen llenas con el PDV de la caja
4.13Una PAID cuya caja es de un PDV dado de baja (PdvDePagosViejosMigrationTest)Se completa igual: la plata salió de ahí. No aparece en ninguna fila del ranking de PDV (solo cuenta los activos)

5. Los pagos viejos recuperan su PDV (migración de datos) ​

Corre sola con el deploy. En dev se prueba contra la base de test:

bash
docker exec soterex-backend-1 php artisan test --filter PdvDePagosViejosMigrationTest
#Qué compruebaResultado esperado
5.1Una PAID sin PDV con un movimiento PAGO en la caja de BQueda con el PDV de B
5.2Una PAID con un PDV ya fijado distinto del de la cajaNo se pisa
5.3Una PAID sin movimiento PAGO, una ACCEPTED, una CANCELLED, un movimiento que no es PAGONo se tocan
5.4PAGO en cajas de dos PDV distintos, o en una caja de otro paísNo se adivina: quedan como estaban
5.5Qué cambia en la filaSolo station_id: ni updated_at, ni last_updated_at, ni quién resolvió, ni los datos del pago
5.6AuditoríaUn evento TRANSACTION_STATION_BACKFILLED con el conteo, sin ids de transacción, sin montos, sin datos personales. En la pantalla Auditoría se ve como «Pagos completados con su PDV», usuario «Sistema» y el detalle «N pago(s) sin PDV completado(s) con el PDV de su caja» (sin JSON ni el código crudo); también se puede filtrar por esa acción
5.7Correrla dos vecesLa segunda no cambia nada y no deja otro evento

En Staging, antes y después del deploy: la consulta de solo lectura que dice cuántos pagos va a completar la migración, y cómo compararla con el evento de Auditoría, están en el runbook de Staging. Después del deploy, en Auditoría se filtra por la acción «Pagos completados con su PDV» (TRANSACTION_STATION_BACKFILLED): si la consulta daba 0, no hay evento; si daba N, el evento dice N, y esas transacciones ahora aparecen en el Reporte individual de quien las pagó y con las columnas 33 a 36 llenas en el reporte de Cumplimiento.

6. El aviso de PDV activo en la ficha de usuario (G4.6) ​

Es un aviso, no un bloqueo: avisa antes de que alguien choque con el 422 del caso 1. Como admin@: Administración → Usuarios → Editar a la persona, sección Roles y Asignaciones.

#PasoResultado esperado
6.1Abrir la ficha de supervisor@ (dos PDV, sin PDV activo, rol que paga)Debajo de la tabla de asignaciones, un aviso ámbar «Sin PDV activo en Guatemala»: tiene más de un PDV y ninguno activo, y para subir el primer documento o pagar va a tener que abrir su caja (el PDV del pago pasa a ser el de esa caja) o que le marquen su PDV activo (Guatemala tiene Caja)
6.2En esa asignación, tocar PDVsEl formulario trae el mismo aviso y el de la lista desaparece: se ve uno solo
6.3En el formulario, elegir un PDV activo sin guardarEl aviso desaparece apenas se elige. Cancelar devuelve el aviso (lo guardado no cambió)
6.4Con el aviso a la vista (sin elegir PDV activo), tocar GuardarGuarda igual: no bloquea
6.5Guardar con el PDV activo elegido y volver a abrir la fichaSin aviso
6.6Ficha de admin@ con el PDV activo vaciado (todos los PDV de Guatemala) y de backoffice@ (un solo PDV). Con el PDV activo de fábrica, admin@ tampoco avisa, pero por otro motivo: tiene PDV activoSin aviso: con Caja, quien paga tiene siempre una caja abierta y su PDV llena el hueco; con un solo PDV no hay ambigüedad
6.7Nueva asignación de un rol que paga: elegir país y rol y dejar «PDVs (vacío = todos)» vacío (país sin Caja, en Staging)Aviso «queda sin PDV… No impide pagar: marcale un PDV activo si querés que quede en uno». Con dos PDV elegidos en ese país, el aviso de «no va a poder subir el primer documento ni pagarla», sin ofrecer abrir la caja. Si la persona ya tenía su aviso guardado en ese país, se ve uno solo (el del formulario)
6.8Una asignación de un rol que no paga (sin pago:write) con dos PDVSin aviso
6.9Modo oscuro y ancho de celularEl aviso se lee: texto en tinta, borde y fondo ámbar, sin cortar el texto

Los casos de lógica están cubiertos por pdvActivo.spec.ts, AvisoPdvActivo.spec.ts y UsuariosView.spec.ts:

bash
docker exec soterex-frontend-1 sh -c 'cd /app && npx vitest run src/utils/__tests__/pdvActivo.spec.ts src/components/__tests__/AvisoPdvActivo.spec.ts src/views/admin/__tests__/UsuariosView.spec.ts'

7. No se rompió nada de lo que ya existía ​

#PasoResultado esperado
7.1Un Cajero de un solo PDV sube documentos y paga, con y sin CajaSin diferencias
7.2Pagar con PDV activo configuradoEl PDV de la transacción es el activo, como desde el 2026-07-25
7.3Tests de lo que toca el cambioVerdes (comando abajo)
bash
docker exec soterex-backend-1 php artisan test --filter 'PdvDelPagoApiTest|PdvDePagosViejosMigrationTest|PermissionServiceTransactionScopeTest|PagadorOtroPdvApiTest|TransactionApiTest|TransactionDocumentApiTest|PagoApiTest|NotificationPayloadTest|ReporteCumplimientoApiTest'

8. Qué NO es parte de este cambio (no reportar como bug) ​

  • La causa 6 de RV3-17 sigue existiendo (casos 2 y 3.5): quien tiene un PDV activo distinto del de su caja paga con la plata de una y queda atribuido a la otra, y lo mismo si el primer documento lo subió otra persona con su caja en otro PDV. Es la opción (b) de D3-7; si la cliente confirma QC-9 («siempre el PDV de la caja»), cambia.
  • El PDV activo puede estar fuera del alcance de la persona (el ABM de Asignación solo exige que sea del país): quien tiene ese PDV paga con él y no ve su propio pago en Reporte individual. Es anterior a G4a y está anotado como deuda en el ADR-020.
  • La columna «Procesada por» y los rótulos «Sin asignar (bolsa del país)», «Cancelada por Soterex» y «Sin PDV asignado» del Reporte individual son G4.3 a G4.5: no están en esta entrega.
  • Una CANCELLED por la API de Soterex sigue sin PDV: no hay persona que la haya cancelado (causa 2 de RV3-17).
  • Una ACCEPTED sigue sin PDV mientras nadie suba un documento ni la pague (causa 1): es por diseño, es la bolsa del país.

Cómo reportarme el feedback ​

Para cada punto que falle, con el número de la tabla alcanza (ej. «1.4 no tomó el PDV de la caja»).

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