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):
| Rol | Alcance | Para qué sirve acá | |
|---|---|---|---|
supervisor@cislatam.test | Supervisor | GT-CAP-001 y GT-QUE-002, sin PDV activo | El usuario multi-PDV de los casos 1 y 2 |
admin@cislatam.test | Admin | Guatemala, 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.test | Cajero | Solo GT-CAP-001 | Control: un solo PDV, no cambia nada |
tesoreria@cislatam.test | Tesorería | Guatemala | Fondea 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@)
| # | Paso | Resultado esperado |
|---|---|---|
| 1.1 | Entrar como supervisor@ sin ninguna caja abierta a su nombre. En Pago, buscar una ACCEPTED y subir la Carta | Se 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.3 | En Saldos, abrir una caja en GT-QUE-002 | Caja del día abierta |
| 1.4 | Volver a Pago, buscar la misma transacción y subir la Carta | Se sube sin error. En Adminer, station_id es el de GT-QUE-002 |
| 1.5 | Subir identificación (anverso y reverso), completar los datos del pago, Iniciar pago → Confirmar pago | La transacción pasa a PAID y descuenta la caja. station_id sigue siendo el de GT-QUE-002 |
| 1.6 | Como supervisor@, ir a Reporte individual y filtrar Pagada | Aparece 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.7 | Cerrar 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 pago | El 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.7b | Solo 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ón | La 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.8 | Como admin@, Auditoría | Del 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.9 | Dejar 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 nueva | 422 «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.10 | Cerrar la caja vencida en Saldos, abrir una en GT-CAP-001 y subir el primer documento de esa misma transacción | Se 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.
| # | Paso | Resultado esperado |
|---|---|---|
| 2.1 | Como admin@, en la ficha de supervisor@ fijar el PDV activo = GT-CAP-001 (Administración, Usuarios) | Se guarda |
| 2.2 | Como supervisor@, tener abierta la caja de GT-QUE-002 (otro PDV). Subir el primer documento de una ACCEPTED nueva y pagarla | Se 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.3 | En Saldos, mirar el movimiento del pago | El PAGO está en la caja de GT-QUE-002 |
| 2.4 | Quitarle el PDV activo a supervisor@ (campo vacío) y repetir el caso 1 con otra transacción | Vuelve a valer el PDV de la caja (paso 1.4) |
3. Sin acotar y un solo PDV: no se rechaza
| # | Paso | Resultado esperado |
|---|---|---|
| 3.1 | Como admin@ con el PDV activo vaciado (ver «Antes de empezar») y sin caja abierta, subir el primer documento de una ACCEPTED | Se sube (no se rechaza): un alcance sin acotar no tiene un PDV que elegir. station_id queda NULL |
| 3.2 | Como admin@ (PDV activo todavía vacío) con una caja abierta en GT-QUE-002, subir el primer documento de otra ACCEPTED | station_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.3 | Como backoffice@ (Cajero, un solo PDV), subir el primer documento y pagar | Todo como siempre; station_id es GT-CAP-001 |
| 3.4 | Como supervisor@ (con la caja abierta en GT-QUE-002), buscar una ACCEPTED cuyo primer documento ya subió backoffice@ (PDV GT-CAP-001) y pagarla | El 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:
docker exec soterex-backend-1 php artisan test --filter 'PdvDelPagoApiTest|PermissionServiceTransactionScopeTest'| # | Qué comprueba el test | Resultado esperado |
|---|---|---|
| 4.1 | País sin Caja, dos PDV, sin PDV activo: subir el primer documento y pagar | 422 ACTIVE_STATION_REQUIRED en las dos; no queda archivo, documento, PDV, movimiento, saldo tocado ni evento de Auditoría |
| 4.2 | Lo mismo con PDV activo | Pasa, y el PDV de la transacción es el activo |
| 4.3 | Alcance sin acotar, o una asignación del país sin PDVs que convive con una acotada a dos | No se rechaza; sin Caja la transacción queda sin PDV, como siempre |
| 4.4 | Con Caja, sin caja abierta | 422 NO_CASH_BOX_OPEN_FOR_USER al pagar (no el código nuevo) |
| 4.5 | Con Caja, una caja abierta en otro país | No desempata: 422 ACTIVE_STATION_REQUIRED al subir el primer documento |
| 4.6 | Pagar una transacción que ya tiene PDV | Pasa: el PDV no iba a quedar vacío |
| 4.7 | Dos 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.8 | Con Caja, la caja abierta es de otro usuario | No desempata: 422 ACTIVE_STATION_REQUIRED al subir el primer documento |
| 4.9 | Con 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.10 | Dos 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.11 | El Supervisor con dos PDV paga con la caja abierta en B | Su pago está en GET /transacciones, su ficha da 200 y el Dashboard lo suma (paid_today_count) |
| 4.12 | Lo 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.13 | Una 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:
docker exec soterex-backend-1 php artisan test --filter PdvDePagosViejosMigrationTest| # | Qué comprueba | Resultado esperado |
|---|---|---|
| 5.1 | Una PAID sin PDV con un movimiento PAGO en la caja de B | Queda con el PDV de B |
| 5.2 | Una PAID con un PDV ya fijado distinto del de la caja | No se pisa |
| 5.3 | Una PAID sin movimiento PAGO, una ACCEPTED, una CANCELLED, un movimiento que no es PAGO | No se tocan |
| 5.4 | PAGO en cajas de dos PDV distintos, o en una caja de otro país | No se adivina: quedan como estaban |
| 5.5 | Qué cambia en la fila | Solo station_id: ni updated_at, ni last_updated_at, ni quién resolvió, ni los datos del pago |
| 5.6 | Auditoría | Un 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.7 | Correrla dos veces | La 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.
| # | Paso | Resultado esperado |
|---|---|---|
| 6.1 | Abrir 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.2 | En esa asignación, tocar PDVs | El formulario trae el mismo aviso y el de la lista desaparece: se ve uno solo |
| 6.3 | En el formulario, elegir un PDV activo sin guardar | El aviso desaparece apenas se elige. Cancelar devuelve el aviso (lo guardado no cambió) |
| 6.4 | Con el aviso a la vista (sin elegir PDV activo), tocar Guardar | Guarda igual: no bloquea |
| 6.5 | Guardar con el PDV activo elegido y volver a abrir la ficha | Sin aviso |
| 6.6 | Ficha 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 activo | Sin 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.7 | Nueva 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.8 | Una asignación de un rol que no paga (sin pago:write) con dos PDV | Sin aviso |
| 6.9 | Modo oscuro y ancho de celular | El 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:
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
| # | Paso | Resultado esperado |
|---|---|---|
| 7.1 | Un Cajero de un solo PDV sube documentos y paga, con y sin Caja | Sin diferencias |
| 7.2 | Pagar con PDV activo configurado | El PDV de la transacción es el activo, como desde el 2026-07-25 |
| 7.3 | Tests de lo que toca el cambio | Verdes (comando abajo) |
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
CANCELLEDpor la API de Soterex sigue sin PDV: no hay persona que la haya cancelado (causa 2 de RV3-17). - Una
ACCEPTEDsigue 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»).

