Aceptación de dólares por encima del saldo, con vuelto en pesos

1. Qué hace y para qué

Hasta la versión 20261006P, el medio de pago multimoneda DOLAR solo admitía USD hasta cubrir el saldo, con tope floor(saldo / cotización). Si el cliente traía un billete de más, el cajero no podía aceptarlo y el resto se pagaba en pesos.

Desde 20261014P, cuando los datos lo habilitan, el POS acepta más USD que el saldo. La diferencia se entrega como vuelto en pesos, con el medio EFECTIVO. El dólar nunca da vuelto en dólares.

Ejemplo resuelto (ticket de prueba 504)

Cálculo: 10 × 1520 − 12.490 = 2.710.

Rango de USD aceptado

Cuándo está activo

El sobrepago se habilita solo si se cumple todo; si falta algo, rige el tope anterior:

• El medio DOLAR es de tipo billete: dM_DmdeP.iTaxnumber = 1 (tipo 2 = centavos, nunca admite sobrepago).
• El grupo dM_MdeP DOLAR tiene iVuelto = 0.
• Existe una fila dM_VmdeP DOLAR (9) → medio de vuelto por defecto (1, EFECTIVO) con límite mayor que 0.
• Corren POS_MAIN.EXE y POS_MMON.DLL de 20261014P.

Además, con la versión nueva los USD deben ser enteros (billetes) en el tipo billete, haya o no sobrepago.

2. Flujo del cajero paso a paso

1. Registrar los artículos como siempre. Total del ejemplo: $ 12.490.
2. Medios de Pago (F6 en los datos de prueba). Si aparecen promociones, se continúa. Se baja hasta DOLAR y se confirma con Enter.
3. Consulta de cotización. El POS consulta a Pizarra; la pantalla muestra [MULTIMON] Procesando c/servidor remoto... [0 de 10 seg] Si Pizarra no responde o la cotización está suspendida, el medio no se puede usar: No se puede usar el Medio de Pago
4. Recuadro de ayuda. Con el sobrepago habilitado, muestra una línea con la cotización y el saldo, y la línea de ingreso indica los USD mínimos para cubrir, el vuelto en pesos que darían y el máximo. Por ejemplo, con saldo $2.750: Cotiz.DOLAR:1520.00 Saldo $: 2750.00 y DOLAR cubre 2 (vto $290) max 180:
5. Ingreso de USD. El prompt indica el mínimo y el máximo: Ingrese DOLAR (cubre con 9, max 821): El cajero tipea los billetes recibidos, por ejemplo 10, y Enter. El saldo queda negativo (SaldT:-2710.00 en el log).
   • Con decimales (por ejemplo 10.5): se rechaza y vuelve a pedir el monto. DOLAR sin decimales: ingrese solo billetes enteros!
   • Por encima del máximo: Supera monto maximo permitido, reingrese!
   • Vacío: cancela el ingreso de DOLAR.
6. Vuelto. Se presiona la tecla de vuelto automático (Ctrl+F9 en los datos de prueba). El POS asigna el vuelto a EFECTIVO: diálogo EFECTIVO 2710.00.
7. Cierre del ticket. Se cierra el ticket (con MODO_TECLA_VUELTO activo, la tecla de vuelto pasa directo al cierre). El ticket impreso muestra:

   TOTAL :                         12490.00
   DOLAR 10.00          15200.00
   SU PAGO:                        15200.00
   EFECTIVO             2710.00
   VUELTO:                          2710.00

8. Entregar $ 2.710 en efectivo al cliente.

Si el sobrepago está deshabilitado (o los datos no están completos)

El POS vuelve al comportamiento anterior (prueba V5):

El cajero cobra USD 8 ($ 12.160) y el resto ($ 330) en efectivo u otro medio. Si el saldo es menor que una unidad de USD, sin sobrepago aparece El saldo a pagar es menor al permitido con DOLAR. Con sobrepago, ese caso se acepta con USD 1 y vuelto.

Combinaciones admitidas

• Efectivo primero, USD después: funciona (V3B). Ejemplo: $ 2.000 + USD 9 = $ 15.680 → vuelto $ 3.190, sin mensaje 388.
• USD por debajo del saldo y el resto en efectivo: igual que antes, sin vuelto (V3).
• Anular el ticket en curso (antes de cerrarlo), aun con el sobrepago ya ingresado: funciona y no deja filas de medios de pago (V6B). Una vez cerrado el ticket, no se puede cancelar; es lo esperado.

3. Configuración: tablas, perfiles y Pizarra

Tablas de medios de pago

Los ids son los de Becerra en laboratorio: DOLAR grupo 9 (detalle 9/10), EFECTIVO 1.

Después de cambiar dM_VmdeP hay que reiniciar el POS: la tabla se carga en memoria una sola vez al iniciar.

Perfiles

Ningún perfil cambia con esta funcionalidad; la tabla sirve para verificar que estén bien.

Servidor Pizarra

• El POS consulta GET /APIPizarraPrecios/Tipre/GetCurrentPrice?BranchNumber=<237>&PaymentMethod.Id=9&PaymentMethod.SubId=10 en el puerto 8084.
• La lista de orígenes permitidos (allowlist) de Pizarra debe incluir la subred de los POS. Si no, responde 403 "Origen no permitido" y el POS no deja usar DOLAR.
• Debe haber cotización vigente para la región y el medio 9/10. Si está suspendida, responde 404 y el POS rechaza el medio (prueba T3).
• Cada consulta queda auditada en el servidor (id = transactionId, versión de cotización, HTTP, precio).

4. Cómo habilitar y deshabilitar

A. Camino recomendado: maestro central

1. En el maestro central de Becerra, confirmar que existe el grupo dM_MdeP 9 "DOLAR" y que dM_DmdeP 9/10 tiene iTaxnumber = 1.
2. En dM_MdeP uId 9: iVuelto 1 → 0 y dPorcCobrar 100 → 10000. No tocar dLimite, dUnidad ni dMaxVuelto.
3. En dM_VmdeP: agregar la fila uId 9, uIdv 1, dLimite 99999999.99, dPorcentaje 0 (o el límite que defina el cliente). Que sea la única fila con uId 9.
4. Publicar ambas tablas con versión nueva para que los POS las descarguen.
5. Reiniciar cada POS y verificar con SETVUELT 9 1 (solo lectura) y un ticket real tipo V1.

Para deshabilitar: publicar iVuelto = 1, dPorcCobrar = 100 y sin la fila 9→1, con versión nueva.

B. SETVUELT.EXE: piloto, laboratorio o emergencia

Herramienta de consola (misma familia que SETMDTAX e INSMDEP). Se ejecuta con el POS detenido, con DDFDIR y DATADIR definidos y el motor Btrieve cargado.

SETVUELT <uIdMMon> <uIdVuelto>                       ver (solo lectura)
SETVUELT <uIdMMon> <uIdVuelto> /APPLY [lim] [porc]   habilitar (lim 99999999.99, porc 10000)
SETVUELT <uIdMMon> <uIdVuelto> /UNDO                 deshabilitar

• Idempotente: si ya está en el estado pedido, informa SIN CAMBIOS y sale con 0.
• Backup: antes de escribir agrega una línea con fecha, acción y valores previos a SETVUELT.BAK (directorio actual).
• Relectura: después de grabar relee y responde OK - GRABADO Y RELEIDO. Si no coincide, sale con código distinto de 0.
• Siempre muestra la iVersion de dE_Tranf y advierte que el server pisa el cambio.
• Advierte si dUnidad o dMaxVuelto del medio multimoneda no son 0.

Salidas reales (laboratorio)

/APPLY:

---- SETVUELT 9 1 /APPLY
ANTES:
  dM_MdeP uId=9 (DOLAR): iVuelto=1 dPorcCobrar=100.00 dLimite=99999999.99 dUnidad=0.00 dMaxVuelto=0.00
  dM_VmdeP 9->1: 0 fila(s)   otras filas uId=9: 0
  dE_Tranf dM_MdeP    iVersion=1 (una version nueva del server pisa este cambio)
  dE_Tranf dM_VmdeP   iVersion=1 (una version nueva del server pisa este cambio)
DESPUES (relectura):
  dM_MdeP uId=9 (DOLAR): iVuelto=0 dPorcCobrar=10000.00 dLimite=99999999.99 dUnidad=0.00 dMaxVuelto=0.00
  dM_VmdeP 9->1: 1 fila(s) dLimite=99999999.99 dPorcentaje=0.00   otras filas uId=9: 0
OK - GRABADO Y RELEIDO

/UNDO repetido (idempotencia):

---- SETVUELT 9 1 /UNDO
ANTES:
  dM_MdeP uId=9 (DOLAR): iVuelto=1 dPorcCobrar=100.00 dLimite=99999999.99 dUnidad=0.00 dMaxVuelto=0.00
  dM_VmdeP 9->1: 0 fila(s)   otras filas uId=9: 0
  ...
SIN CAMBIOS: ya esta deshabilitado

Línea de SETVUELT.BAK:

Wed Oct 14 23:29:47 2026 accion=APPLY uIdMMon=9 uIdVuelto=1 | dM_MdeP existe=1 iVuelto=1 dPorcCobrar=100.00 dLimite=99999999.99 dUnidad=0.00 dMaxVuelto=0.00 | dM_VmdeP filas=0 dLimite=0.00 dPorcentaje=0.00 otras=0

5. Binarios y fuentes modificados

Commits

Cambios por archivo (0dd9d2a..vuelto-dolar, +385/−13)

El port previo (dff468b..0dd9d2a, +77/−23) tocó pos_mmon.cpp, pos_mppo.cpp, pos_valo.cpp, pos_defi.h y pcpos.h: quitó la cotización simulada fija, agregó el modo de redondeo por iTaxnumber, el orden de vData con 61= primero y el arqueo en USD.

md5 de los binarios (build completo CO.BAT, 20261014P)

La distribución mínima es POS_MAIN.EXE + POS_MMON.DLL. Se recomienda distribuir el set completo de un mismo CO.BAT (las 16 DLL, listadas con md5 en built_binaries.md5 de la evidencia) para que coincidan versiones y md5. Al arrancar, el log debe mostrar Inicia POS=20261014P y todas las DLL en 20261014P.

Matriz de compatibilidad

6. Registro y arqueo

Cada pago genera filas en dE_DDMP. El vuelto es una fila EFECTIVO negativa (marcada como recibo de vuelto, bRecVuelto) sin vData. La fila DOLAR guarda el importe en pesos y, en vData, los USD, la cotización y el transactionId de Pizarra.

Ejemplo: ticket 504 (volcado de dE_DDMP)

• 61= USD recibidos, 60= cotización, 62= transactionId (id de auditoría en Pizarra). cComprobante lleva solo los primeros dígitos del id.
• 61= debe ir primero: el arqueo lee solo la primera clave de vData.
• El ticket impreso muestra EFECTIVO 2710.00 en positivo en el bloque de vuelto; en la base la fila es negativa.
• La copia binaria del Z actual (DE_DDMP.BIN) tiene las mismas filas sin vData (visto en los tickets 508 y 510).

Cómo cuenta el arqueo por moneda

• Con multimoneda habilitado, la fila DOLAR suma al acumulador de USD el valor de 61= (10), no los pesos.
• La fila de vuelto (EFECTIVO, sin 61=) resta pesos de EFECTIVO y no toca el acumulado de USD.
• Los totales en pesos quedan cuadrados: DOLAR 15.200 + EFECTIVO −2.710 = 12.490.

Cálculo sobre las filas volcadas de los tickets 504–510 (no se imprimió cierre X/Y en laboratorio):

7. Pruebas realizadas

Laboratorio con DOSBox-X y Pizarra local, cotización 1520 (versión 10345). Ticket base: 4 × COCA COLA + 1 PINZA = $ 12.490. Todas las consultas a Pizarra quedaron auditadas con HTTP 200.

Pendientes sugeridos para el piloto: reimpresión del ticket, cierre X/Y/Z por moneda y Pizarra caída con la versión nueva (con la versión 20261006P ya se probó, T4).

Pruebas previas del port multimoneda (20261006P)

Evidencia: SistemaBiMonetarismo/docs/evidence/pos-becerra-vuelto-20261014/ (logs, tickets impresos, volcados, salidas de SETVUELT, auditorías) y …/pos-becerra-mmon-20261006/ (port, T1–T5).

8. Despliegue en un cliente

Orden: primero el código en todos los POS (es inerte con los datos viejos), después los datos, que funcionan como interruptor.

Checklist

• Validar con el contador del cliente la operatoria de vuelto en pesos por pago en divisas (§9).
• Confirmar que cada POS corre 20261006P o posterior. Las versiones 20260807P, 20260824P y 20260917P tienen la cotización simulada fija (1200) activa.
• Pizarra: allowlist con la subred de los POS, puerto 8084 accesible, cotización vigente para la sucursal y el medio 9/10.
• Perfiles verificados: 554=1, 555, 556=8084, 557, 558, 237, 200=0, 22=1, 171=1 (§3).
• Maestro central: existe el grupo 9 "DOLAR" y dM_DmdeP 9/10 con iTaxnumber=1.
• Distribuir el set completo de binarios 20261014P (como mínimo POS_MAIN.EXE + POS_MMON.DLL) y verificar md5.
• Reiniciar y verificar en el log Inicia POS=20261014P y las DLL en 20261014P.
• Ticket de control con los datos viejos: debe regir el tope anterior (como V5).
• Confirmar la tecla de producción de vuelto automático (evento 8303) y el perfil MODO_TECLA_VUELTO.
• Aplicar los datos en el maestro central (§4.A) y publicar con versión nueva. En el piloto, opcionalmente, SETVUELT 9 1 /APPLY local, sabiendo que el server lo pisa.
• Reiniciar el POS y verificar con SETVUELT 9 1 (solo lectura).
• Ticket real tipo V1 (USD por encima del saldo): vuelto en efectivo, filas en dE_DDMP como en §6.
• Ticket con decimales (tipo V4): debe rechazarse.
• Al cierre del día: revisar el arqueo por moneda (USD y EFECTIVO).

Rollback

1. Primera opción, por datos: publicar en el maestro iVuelto=1, dPorcCobrar=100 y sin la fila 9→1, y reiniciar. En emergencia, SETVUELT 9 1 /UNDO en el POS (con el POS detenido). El código queda con el tope anterior.
2. Solo si hace falta, por binarios: volver a POS_MAIN.EXE + DLL de 20261006P. Es seguro con cualquier estado de datos (matriz §5).

9. Notas, límites y riesgos

Preguntas abiertas para el cliente

• ¿Quién mantiene el maestro de dM_MdeP / dM_VmdeP y existe en producción el grupo 9 DOLAR?
• ¿Qué versión corre hoy cada POS?
• ¿Qué tecla de producción tiene el vuelto automático (8303)?
• ¿Qué límite de vuelto se quiere (dM_VmdeP.dLimite)? En laboratorio se usó "sin límite".