Documentacion de comunicacion CtaCte

Arquitectura POS → Gateway → Autorizador, con foco en compra, cobro, adelanto, consultas y gestion profesional de reversas. Esta version incorpora la Evolucion 2: el Gateway deja de ejecutar reintentos periodicos de reversa y el POS vuelve a concentrar la gestion de reversas pendientes.

Version: v6 / Evolucion 2 Foco: POS gestor de reversas Gateway: APROBADO / DENEGADO / DENEGADO_REVERSAR

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 POS → Gateway → Autorizador, el Gateway actua como intermediario. En la Evolucion 2, el Gateway no mantiene un worker periodico de reversas. En su lugar, responde al POS con un estado suficientemente claro para que el POS decida si elimina o conserva la reversa local.

Decision clave de Evolucion 2 La reversa pendiente vuelve a quedar concentrada en el POS. El Gateway puede indicar explicitamente DENEGADO_REVERSAR para que el POS conserve la reversa local.

Regla de oro El POS solo elimina la reversa si tiene una confirmacion clara: APROBADO, DENEGADO, o una consulta post-timeout que confirme que la operacion no existe, esta denegada o esta aprobada.

1. Operaciones 2. POS historico 3. Gateway Evolucion 2 4. Flujo de compra 5. Consulta post-timeout 6. Matriz de decisiones

1. Operaciones CtaCte

Operacion	Codigo	Origen tipico	Modifica saldo	Riesgo de reversa
Consulta de saldo	`OP_CONSULTA`	Consulta informativa	No	No genera reversa
Ultimas operaciones / liquidacion	`OP_ULTOPS` / `OP_ULTLIQ`	Consulta informativa	No	No genera reversa
Compra CtaCte	`OP_CARGO`	Venta POS con medio CtaCte	Si	Debe protegerse con reversa local previa
Adelanto	`OP_ADELANTO`	Operacion financiera	Si	Debe protegerse con reversa local previa
Cobro en cuenta	`OP_COBRO`	Pago de deuda / cuenta	Si	Debe protegerse con reversa local previa
Reversa	`OP_REVERSO`	Compensacion de operacion incierta	Compensa	La administra el POS en Evolucion 2

2. Logica POS historica

El POS guarda una operacion financiera pendiente en CtaCtes.Rev antes de transmitir. Si posteriormente no puede cerrar con certeza el resultado, esa reversa local queda disponible para ser enviada como OP_REVERSO.

Flujo POS historico de reversa local

flowchart TD A([Inicio operacion CtaCte en POS]) --> B{Tipo de operacion} B -->|Consulta| C[Enviar consulta sin reversa local] B -->|Compra / adelanto / cobro| D[Persistir CtaCtes.Rev antes de enviar] D --> E[Enviar operacion] C --> E E --> F{Resultado recibido?} F -->|Si, claro| G[Resolver segun respuesta] F -->|No / incierto| H[(Conservar CtaCtes.Rev)] H --> I[Queda reversa pendiente POS]

Que se conserva de la logica historica El POS sigue siendo el punto que prepara y conserva la reversa local antes de enviar una operacion financiera. Esta proteccion es necesaria para cubrir caidas, cortes de energia o falta de respuesta.

3. Gateway en Evolucion 2

En la Evolucion 2 se elimina del Gateway la logica de envio periodico de reversas. El Gateway deja de ser el actor que mantiene un circuito autonomo de compensacion. Su responsabilidad principal pasa a ser procesar la compra, registrar el estado consultable y devolver al POS una respuesta funcional clara.

Respuestas permitidas del Gateway al POS

Respuesta Gateway	Significado funcional	Accion obligatoria del POS
APROBADO	La operacion quedo aceptada.	Eliminar reversa local e informar aprobada.
DENEGADO	La operacion fue rechazada de forma clara o el Gateway determina que no existe operacion que reversar.	Eliminar reversa local e informar denegada.
DENEGADO_REVERSAR	No se aprueba para el POS, pero existe condicion incierta o compensable. El POS debe conservar la reversa.	Mantener reversa local pendiente.

Diferencia critica DENEGADO permite borrar la reversa. DENEGADO_REVERSAR prohibe borrarla: el POS debe conservar la reversa local para resolver la incertidumbre.

4. Flujo de compra con Evolucion 2

El POS prepara la reversa antes de enviar la compra al Gateway. Luego decide que hacer con esa reversa segun la respuesta recibida.

Flujo principal POS → Gateway → Autorizador

flowchart TD A([POS inicia compra CtaCte]) --> B[(POS persiste reversa local previa)] B --> C[POS envia compra al Gateway] C --> D[Gateway procesa y comunica con Autorizador] D --> E{Respuesta Gateway al POS} E -->|APROBADO| F[POS elimina reversa local] F --> G([Informar operacion aprobada]) E -->|DENEGADO| H[POS elimina reversa local] H --> I([Informar operacion denegada]) E -->|DENEGADO_REVERSAR| J[(POS conserva reversa local)] J --> K([Informar denegada con reversa pendiente]) E -->|Sin respuesta| L[(POS conserva reversa local)] L --> M[POS ejecuta una consulta unica de estado]

Secuencia operacional

Secuencia de compra y respuesta

sequenceDiagram participant POS participant GW as Gateway participant AUT as Autorizador POS->>POS: Persistir reversa local previa POS->>GW: Compra CtaCte GW->>AUT: Solicitud de compra alt Autorizador aprueba AUT-->>GW: Aprobada GW-->>POS: APROBADO POS->>POS: Eliminar reversa local POS->>POS: Informar aprobada else Autorizador deniega claramente AUT-->>GW: Denegada GW-->>POS: DENEGADO POS->>POS: Eliminar reversa local POS->>POS: Informar denegada else Incertidumbre compensable AUT--xGW: Timeout / error incierto GW-->>POS: DENEGADO_REVERSAR POS->>POS: Mantener reversa local POS->>POS: Informar denegada con reversa pendiente else POS no recibe respuesta GW--xPOS: Sin respuesta / corte POS->>POS: Mantener reversa local POS->>GW: Consulta unica de estado end

5. Consulta unica post-timeout

Si el POS no recibe respuesta de la compra, no debe decidir a ciegas. Debe conservar inicialmente la reversa local y realizar una unica consulta al Gateway para conocer el estado de la operacion enviada.

Resolucion por consulta post-timeout

flowchart TD A([POS no recibe respuesta de compra]) --> B[(Mantener reversa local)] B --> C[Enviar una consulta unica al Gateway] C --> D{Estado informado por Gateway} D -->|No existe operacion| E[POS elimina reversa local] E --> F([Informar denegada]) D -->|Operacion DENEGADA| G[POS elimina reversa local] G --> H([Informar denegada]) D -->|Operacion APROBADA| I[POS elimina reversa local] I --> J([Informar aprobada]) D -->|Sin respuesta / error consulta| K[(POS mantiene reversa local)] K --> L([Queda reversa pendiente para gestion posterior])

Interpretacion Si el Gateway no tiene la operacion, responde funcionalmente como DENEGADA. El POS elimina la reversa porque no existe evidencia de una operacion tomada por Gateway/Autorizador.

Datos recomendados para consultar estado

Dato	Motivo
`posId`, sucursal, caja	Identificar el origen exacto de la operacion.
`nroTicketPOS` / numero de operacion POS	Correlacionar la compra original con la consulta.
Cuenta / cliente / tarjeta	Evitar falsos positivos por tickets repetidos o reintentos.
Importe, moneda, cuotas	Verificar que el estado corresponde a la misma operacion.
Fecha/hora aproximada	Acotar busqueda y auditar.
`idOperacionGateway`, si existe	Clave ideal de idempotencia si el POS llego a recibirla o construirla.

6. Matriz de decisiones POS

Momento	Respuesta / evento	Accion sobre reversa POS	Resultado para usuario POS
Compra	APROBADO	Eliminar reversa	Operacion aprobada
Compra	DENEGADO	Eliminar reversa	Operacion denegada
Compra	DENEGADO_REVERSAR	Mantener reversa	Denegada con reversa pendiente
Compra	Sin respuesta	Mantener inicialmente	Ejecutar consulta unica
Consulta post-timeout	No existe operacion	Eliminar reversa	Denegada
Consulta post-timeout	Operacion denegada	Eliminar reversa	Denegada
Consulta post-timeout	Operacion aprobada	Eliminar reversa	Aprobada
Consulta post-timeout	Sin respuesta / error consulta	Mantener reversa	Reversa pendiente

Regla de seguridad Ante duda o falta de respuesta, el POS conserva la reversa. Solo la elimina cuando recibe una respuesta final clara o cuando la consulta confirma que no hay operacion tomada.

7. Responsabilidades por componente

POS

Persistir reversa antes de operaciones financieras, interpretar las tres respuestas del Gateway, consultar una vez ante timeout y conservar la reversa si no hay certeza.

Gateway

Procesar compra, comunicarse con Autorizador, registrar estado consultable y responder APROBADO, DENEGADO o DENEGADO_REVERSAR. No ejecuta reintentos periodicos de reversa.

Autorizador

Autorizar o denegar la operacion financiera. Sus timeouts o errores inciertos son traducidos por el Gateway para que el POS gestione la reversa local.

Comparativa contra evolucion anterior

Aspecto	Evolucion anterior	Evolucion 2
Worker periodico de reversas	Lo administraba el Gateway	Se elimina a nivel server
Dueño de reversa pendiente	Gateway para incertidumbre Gateway-Autorizador	POS como gestor principal
Bloqueo por reversa pendiente	Gateway podia bloquear nuevas compras del POS	POS conserva y gestiona su reversa; Gateway informa estados
Respuesta especial	Error / reversa pendiente en curso	`DENEGADO_REVERSAR`
Reconciliacion inmediata	Gateway reintentaba reversa periodicamente	POS hace una consulta unica post-timeout

8. Estados sugeridos

La implementacion puede variar, pero estos estados ayudan a mantener trazabilidad sin introducir reintentos periodicos en el Gateway.

Estados de la reversa local en POS

stateDiagram-v2 [*] --> SinReversa SinReversa --> ReversaPreparada: Antes de enviar compra ReversaPreparada --> Cerrada: APROBADO ReversaPreparada --> Cerrada: DENEGADO ReversaPreparada --> Pendiente: DENEGADO_REVERSAR ReversaPreparada --> ConsultaEstado: Sin respuesta ConsultaEstado --> Cerrada: No existe / DENEGADA / APROBADA ConsultaEstado --> Pendiente: Sin respuesta consulta Pendiente --> Cerrada: Reversa resuelta posteriormente Cerrada --> SinReversa

9. Mensajes operativos sugeridos

Situacion	Mensaje sugerido al POS / usuario	Accion tecnica
APROBADO	Operacion aprobada	Eliminar reversa
DENEGADO	Operacion denegada	Eliminar reversa
DENEGADO_REVERSAR	Operacion denegada. Reversa pendiente	Mantener reversa
Sin respuesta y consulta aprobada	Operacion aprobada por consulta de estado	Eliminar reversa
Sin respuesta y consulta denegada/no existe	Operacion denegada por consulta de estado	Eliminar reversa
Sin respuesta y consulta falla	No se pudo confirmar estado. Reversa pendiente	Mantener reversa y escalar

Conclusion

La Evolucion 2 simplifica el Gateway eliminando el circuito periodico de reversas, pero exige que el POS sea estricto: preparar reversa antes de enviar, eliminarla solo ante estados finales claros y conservarla cuando el Gateway indique DENEGADO_REVERSAR o cuando no exista confirmacion confiable.

Principio final APROBADO y DENEGADO cierran la reversa. DENEGADO_REVERSAR, timeout o error de consulta la mantienen pendiente.