Documentacion de comunicacion CtaCte
Arquitectura POS -> Gateway -> Autorizador, con foco en compra, cobro, adelanto, consultas y gestion profesional de reversas. No se documentan payloads; se documenta la logica operacional, estados y responsabilidades.
Version: v5 profesional
Foco: reversas preventivas
Ambiente: POS / Gateway / Autorizador
Resumen ejecutivo
El POS historico ya contiene una proteccion local: antes de enviar operaciones financieras de CtaCte guarda una transaccion pendiente en disco para poder reversarla si la operacion queda en estado incierto.
Con la arquitectura actual POS -> Gateway -> Autorizador, aparece una segunda frontera critica: el Gateway puede recibir correctamente la compra del POS, enviarla al Autorizador y perder la respuesta. En ese caso, el POS no debe generar reversa local si recibio respuesta del Gateway. La reversa debe ser administrada por el Gateway.
Decision clave de diseno
El Gateway debe persistir una reversa preventiva antes de enviar la compra al Autorizador. Asi se cubre corte de luz, caida del servicio o reinicio mientras existe una compra en curso.
1. Operaciones CtaCte
| Operacion | Codigo | Origen tipico | Genera riesgo de reversa | Responsable principal |
|---|
| Consulta de saldo | OP_CONSULTA | Consulta cuenta | No | No modifica saldo |
| Ultimas operaciones / liquidacion | OP_ULTOPS / OP_ULTLIQ | Consulta informativa | No | No modifica saldo |
| Compra CtaCte | OP_CARGO | Venta POS con medio CtaCte | Si | POS si no llego al Gateway; Gateway si llego al Gateway |
| Adelanto | OP_ADELANTO | Operacion financiera | Si | Igual que compra |
| Cobro en cuenta | OP_COBRO | Pago de deuda / cuenta | Si | Igual que compra |
| Reversa | OP_REVERSO | Compensacion de operacion incierta | Compensa | Quien controla la frontera donde ocurrio la incertidumbre |
2. Logica POS historica
El POS protege operaciones financieras locales guardando una transaccion pendiente en CtaCtes.Rev antes de transmitir. En la proxima comunicacion, si encuentra ese archivo, intenta enviarlo como OP_REVERSO antes de procesar otra operacion no-consulta.
Flujo POS historico con reversa local
flowchart TD
A([Inicio operacion CtaCte en POS]) --> B{Tipo de operacion}
B -->|Consulta| C[OP_CONSULTA / OP_ULTOPS / OP_ULTLIQ]
B -->|Movimiento financiero| D[OP_CARGO / OP_ADELANTO / OP_COBRO]
C --> E[SendMessage]
D --> E[SendMessage]
E --> F[Completa datos comunes: POS, sucursal, Z, usuario, ticket]
F --> G[Conecta TCP]
G --> H{Existe CtaCtes.Rev local?}
H -->|Si| I[Envia pendiente como OP_REVERSO]
I --> J{Reversa local OK?}
J -->|Si| K[Borra CtaCtes.Rev]
J -->|No y operacion actual no es consulta| X([Bloquea operacion actual: reversa pendiente])
J -->|No y operacion actual es consulta| L[Continua consulta]
H -->|No| L[Procesa operacion actual]
K --> L
L --> M{Operacion actual es consulta?}
M -->|Si| P[Envia sin guardar reversa]
M -->|No| O[Guarda CtaCtes.Rev antes de transmitir]
O --> P[Envia transaccion]
P --> Q{Respuesta valida?}
Q -->|No| R([Queda CtaCtes.Rev pendiente])
Q -->|Si| S{Respuesta denegada o error de negocio?}
S -->|Si| T[Borra CtaCtes.Rev]
S -->|No, autorizada OK| U[Continua cierre local / voucher]
U --> V[Borra CtaCtes.Rev al confirmar cierre local]
Por que existe CtaCtes.Rev
Porque si el POS transmite una compra y luego no recibe respuesta, no sabe si el autorizador impacto o no la operacion. La reversa local cubre esa incertidumbre cuando la frontera de falla esta entre POS y el destino al que se conecta.
Limite de esta logica
Si el POS si recibio una respuesta del Gateway, pero el problema ocurrio entre Gateway y Autorizador, el POS ya no tiene suficiente informacion para reversar correctamente. Esa responsabilidad pasa al Gateway.
3. Arquitectura POS -> Gateway -> Autorizador
El Gateway introduce una nueva capa con estado propio. Debe actuar como coordinador de transacciones contra el Autorizador y como barrera de seguridad para el POS.
Flujo normal de compra autorizada
sequenceDiagram
autonumber
participant POS
participant GW as Gateway
participant AUT as Autorizador
POS->>GW: Compra CtaCte
GW->>GW: Valida que no exista reversa pendiente para ese POS
GW->>GW: Persiste reversa preventiva / operacion en curso
GW->>AUT: Envia Compra
AUT-->>GW: Compra aprobada
GW->>GW: Marca operacion como aprobada y cierra reversa preventiva
GW-->>POS: Compra aprobada
POS->>POS: Cierra ticket / registra medio de pago
Falla Autorizador no responde: reversa queda en Gateway
sequenceDiagram
autonumber
participant POS
participant GW as Gateway
participant AUT as Autorizador
POS->>GW: Compra CtaCte
GW->>GW: Persiste reversa preventiva antes de enviar
GW->>AUT: Envia Compra
AUT--xGW: No responde / timeout / conexion perdida
GW->>GW: Mantiene reversa pendiente
GW->>GW: Agenda reintentos periodicos de OP_REVERSO
GW-->>POS: Error: Autorizador no responde
Note over POS: POS no genera reversa local porque recibio respuesta del Gateway
loop Hasta resolver pendiente
GW->>AUT: Envia OP_REVERSO pendiente
AUT--xGW: No responde o no confirma reversa
GW->>GW: Mantiene pendiente y reprograma intento
end
4. Reversa preventiva en Gateway
La mejora importante es que el Gateway no debe crear la reversa recien despues del timeout. Debe crearla antes de enviar la compra al Autorizador.
Regla profesional
Toda operacion financiera que pueda modificar saldo debe persistirse como operacion en curso / reversa preventiva antes de salir al Autorizador.
Punto exacto donde se prepara la reversa preventiva
flowchart TD
A([Gateway recibe Compra del POS]) --> B{Existe reversa pendiente para este POS?}
B -->|Si| C[No reenviar la compra al Autorizador]
C --> C1([Responder al POS: denegado / reversa pendiente en curso])
B -->|No| D[Validar datos y generar idOperacionGateway]
D --> E[(Persistir reversa preventiva)]
E --> F[Enviar Compra al Autorizador]
F --> G{Resultado del Autorizador}
G -->|Aprobada| H[Cerrar reversa preventiva como OK]
H --> I([Responder compra aprobada al POS])
G -->|Denegada clara| J[Cerrar reversa preventiva sin reversar]
J --> K([Responder compra denegada al POS])
G -->|Timeout / corte / error incierto| L[(Mantener reversa pendiente)]
L --> M[Programar reintentos periodicos de reversa]
L --> N([Responder error al POS si el Gateway sigue vivo])
Datos minimos a persistir
| Campo | Motivo |
|---|
posId, sucursal, caja | Bloquear nuevas compras solo del POS afectado y auditar origen. |
nroTicketPOS / nro operacion POS | Relacionar la compra original con el intento de reversa. |
idOperacionGateway | Idempotencia interna y trazabilidad. |
| cuenta / cliente / tarjeta | Identificar cuenta afectada. |
| importe, moneda, cuotas | Reversa debe compensar la operacion exacta. |
| estado | Ej.: PENDIENTE_ENVIO_COMPRA, COMPRA_ENVIADA, REVERSA_PENDIENTE, REVERSA_OK, CERRADA. |
| intentos, ultimo error, proximo intento | Controlar circuito periodico y soporte operativo. |
5. Bloqueo por reversa pendiente y reintentos
Mientras exista una reversa pendiente en el Gateway para un POS determinado, una nueva compra de ese POS no debe reenviarse al Autorizador. El Gateway debe responder inmediatamente con una denegacion tecnica/operativa: reversa pendiente en curso.
Nueva compra bloqueada por reversa pendiente
sequenceDiagram
autonumber
participant POS
participant GW as Gateway
participant AUT as Autorizador
Note over GW: Existe reversa pendiente para POS X
POS->>GW: Nueva Compra CtaCte POS X
GW->>GW: Consulta estado pendiente por POS
GW-->>POS: Denegado: reversa pendiente en curso
Note over AUT: La nueva compra no se envia al Autorizador
loop Proceso background Gateway
GW->>AUT: Reintento OP_REVERSO
AUT-->>GW: Reversa aprobada
GW->>GW: Libera pendiente POS X
end
POS->>GW: Nueva Compra posterior
GW->>AUT: Se permite enviar compra
Para el POS
Debe mostrar un mensaje claro y no intentar reversar localmente si el Gateway respondio. La operacion no fue autorizada para el cierre del ticket.
Para el Gateway
Debe reintentar reversa hasta recibir confirmacion o hasta que una operatoria administrativa resuelva la inconsistencia.
Para soporte
Debe existir visibilidad de pendientes: POS, ticket, importe, cuenta, cantidad de intentos, ultimo error y proximo intento.
6. Maquina de estados recomendada en Gateway
Estados de una operacion financiera en Gateway
stateDiagram-v2
[*] --> RECIBIDA_DEL_POS
RECIBIDA_DEL_POS --> RECHAZADA_POR_REVERSA_EXISTENTE: Existe pendiente para POS
RECIBIDA_DEL_POS --> PREVENTIVA_PERSISTIDA: No existe pendiente
PREVENTIVA_PERSISTIDA --> COMPRA_ENVIADA_AUTORIZADOR: Envio compra
PREVENTIVA_PERSISTIDA --> REVERSA_PENDIENTE: Gateway cae antes/durante envio o estado incierto
COMPRA_ENVIADA_AUTORIZADOR --> COMPRA_APROBADA: Autorizador aprueba
COMPRA_ENVIADA_AUTORIZADOR --> COMPRA_DENEGADA: Autorizador deniega claramente
COMPRA_ENVIADA_AUTORIZADOR --> REVERSA_PENDIENTE: Timeout / sin respuesta
COMPRA_APROBADA --> CERRADA_OK: Responder OK al POS
COMPRA_DENEGADA --> CERRADA_DENEGADA: Responder denegada al POS
REVERSA_PENDIENTE --> REVERSA_EN_REINTENTO: Timer / worker
REVERSA_EN_REINTENTO --> REVERSA_PENDIENTE: Falla o no confirma
REVERSA_EN_REINTENTO --> REVERSA_CONFIRMADA: Autorizador confirma reversa
REVERSA_CONFIRMADA --> CERRADA_REVERSADA: Liberar POS
RECHAZADA_POR_REVERSA_EXISTENTE --> [*]
CERRADA_OK --> [*]
CERRADA_DENEGADA --> [*]
CERRADA_REVERSADA --> [*]
7. Matriz de decisiones
| Situacion | POS | Gateway | Autorizador | Resultado esperado |
|---|
| POS no logra conectar al Gateway | Puede conservar proteccion local si habia transaccion preparada | No conoce la operacion | No participa | Error local / no autorizada |
| Gateway recibe compra pero aun no envio al Autorizador y cae | Puede quedar esperando/error | Al reiniciar detecta preventiva y la trata como pendiente incierta | No necesariamente participo | Gateway debe resolver/liberar antes de nuevas compras |
| Gateway envia compra y Autorizador aprueba | Cierra ticket | Cierra preventiva | Autoriza | Compra OK |
| Gateway envia compra y Autorizador deniega claramente | No cierra como autorizada | Cierra preventiva sin reversa | Deniega | Denegada comercial/funcional |
| Autorizador no responde al Gateway | Recibe error; no genera reversa local si hubo respuesta del Gateway | Mantiene reversa pendiente y reintenta | Estado incierto | POS queda bloqueado para nuevas compras hasta resolver |
| Nueva compra con reversa pendiente | Recibe denegacion tecnica | No reenvia al Autorizador | No recibe la nueva compra | Mensaje: reversa pendiente en curso |
| Reversa aprobada | Puede volver a operar | Libera pendiente | Confirma reversa | Estado consistente |
8. Reglas finales de implementacion
Regla 1 Consultas no generan reversa: no modifican saldo.
Regla 2 Compra, adelanto y cobro son operaciones financieras; siempre deben tener mecanismo de reversa o cierre seguro.
Regla 3 Si el POS no recibio respuesta del Gateway, puede aplicar su proteccion historica local.
Regla 4 Si el POS recibio respuesta del Gateway indicando que el Autorizador no responde, el POS no genera reversa local. El Gateway es responsable.
Regla 5 El Gateway debe persistir reversa preventiva antes de enviar al Autorizador. No despues del timeout.
Regla 6 Mientras exista reversa pendiente de un POS, el Gateway debe bloquear nuevas compras de ese POS y no reenviarlas al Autorizador.
9. Mensajes operativos sugeridos
| Caso | Mensaje al POS / cajero | Tipo |
|---|
| Autorizador no responde | Operacion no autorizada. Autorizador no responde. | Tecnico |
| Reversa pendiente | Denegado: reversa pendiente en curso. Reintentar mas tarde o llamar a soporte. | Bloqueo operativo |
| Denegada por autorizador | Operacion denegada por autorizador. | Negocio |
| Reversa resuelta | Operacion anterior regularizada. Puede operar nuevamente. | Recuperacion |