Manejo de callbacks duplicados y reintentos de API
Un cliente de API puede enviar una solicitud, recibir un tiempo de espera agotado y volver a intentarlo sin saber si el primer movimiento se registró. Un agregador de juegos o un intermediario de mensajes también puede entregar el mismo callback varias veces. Si el sistema interpreta cada llegada como un débito, crédito, cancelación o bono nuevo, aparecerán diferencias reales en el libro de movimientos del casino. La solución es separar los intentos de entrega de la transacción de negocio y garantizar que su efecto financiero se registre una sola vez. Cada proveedor maneja identificadores, códigos de duplicidad y reglas de reintento propios: no existe una respuesta universal. Aquí explicamos la recepción autenticada, la escritura atómica, las respuestas seguras, los eventos fuera de orden, la conciliación y las pruebas de aceptación. [1] [2] [4]
Publicado
Pueden repetirse los mensajes; nunca el efecto monetario de la misma transacción.
Contenido
¿Por qué puede recibirse varias veces un callback?
El emisor quizá no reciba la respuesta HTTP aunque el receptor haya completado la operación. Por eso reintenta, o la cola vuelve a entregar un mensaje cuyo acuse no quedó registrado. El modelo de entrega al menos una vez permite duplicados y normalmente no garantiza el orden. Un segundo mensaje no demuestra fraude ni una nueva transacción comercial. [4] [5]
En un casino, un débito, un crédito o una reversión no debe ejecutarse otra vez por una segunda entrega. El movimiento financiero, la recepción del callback y la respuesta HTTP son procesos diferentes. St8 y 7SoftTech usan identificadores de transacción para reconocer duplicados, aunque sus respuestas y excepciones varían. [1] [2]
¿Qué identificadores integran la clave de idempotencia?
Separa el ID de entrega, el proveedor autenticado, la transacción de negocio, el tipo de movimiento, la operación original y la ronda de juego. La identidad comercial acordada evita que se registre el dinero dos veces. Su alcance de unicidad debe respetar el contrato: distintos proveedores o proyectos pueden usar números iguales. [1] [2] [3]
Identificador
Función
Regla de diseño
Proveedor / proyecto
Definir espacio de nombres
Autenticar la fuente
ID de transacción
Identificar movimiento
Único según contrato
Tipo de acción
Débito, crédito o reversión
Respetar el API
ID de evento
Identificar una entrega
No siempre es clave financiera
ID original
Vincular cancelación
Validar la referencia
Ronda y jugador
Contexto del movimiento
No sustituir ID transacción
Guarda junto a la clave una huella estable de los parámetros y el estado final. Si llega el mismo ID con otra cantidad, moneda o jugador, hay un conflicto; no corresponde registrar otro movimiento. AWS explica por qué los reintentos seguros deben representar la misma intención original. [3] [4]
¿Qué validar antes de detectar un duplicado?
Primero verifica la firma o autenticación del proveedor usando el contenido exacto que exige su protocolo. Después comprueba autorización para el operador, el jugador, la cartera, la moneda, la acción y la sesión correspondiente. Una solicitud no autenticada con un ID conocido no demuestra que se haya ejecutado algo. OWASP recomienda validar la procedencia antes de deduplicar. [1] [6]
Comprobar firma, vigencia y protección contra repetición maliciosa según cada proveedor.
Asociar origen autenticado con operadora, cuenta, cartera y moneda correctas.
Validar ID comercial, precisión del importe, acción y vínculo con la operación previa.
Comparar la huella de parámetros con los datos almacenados antes de responder que es un duplicado.
Conserva identificadores seguros, tiempos y hashes para auditoría, pero no secretos ni datos personales innecesarios en registros generales. Una firma falsa debe rechazarse aunque su ID coincida con una operación procesada. [2] [6]
¿Cómo funciona el flujo completo de callbacks seguros?
Tras autenticar la solicitud, el servidor busca o reserva la clave comercial, compara los parámetros y registra el efecto permitido junto con el resultado en una sola transacción durable de base de datos. Una segunda entrega idéntica obtiene el resultado guardado sin modificar otra vez el saldo. Los casos inciertos se envían a conciliación. [1] [4] [6]
Autenticar el callback y encontrar al jugador correcto bajo el proveedor autorizado.
Construir la clave contractual y verificar cualquier referencia de reversión.
Encontrar o reservar la operación de forma atómica, contabilizar una vez y guardar el resultado.
Responder según el proveedor o conciliar la incertidumbre sin producir otro movimiento.
⊕Ampliar diagramaVarias entregas pueden representar la misma transacción registrada de forma permanente.
El commit de la base y el envío de HTTP no suelen formar una sola operación atómica entre sistemas. Debe contemplarse que el asiento se confirme, pero se pierda la respuesta: el proveedor reintentará un movimiento que ya se completó. [4] [7]
¿Cómo asegura la base de datos un solo movimiento?
Implementa una restricción real de unicidad sobre la clave de negocio y registra la recepción, el movimiento contable y la decisión final dentro de una transacción apropiada. Hacer SELECT y luego UPDATE por separado no evita condiciones de carrera: dos workers pueden ver la clave libre al mismo tiempo. El control definitivo debe residir en la base y sus bloqueos. [3] [4]
Estado observado
Tratamiento seguro
Falla por probar
Clave nueva
Asentar y guardar una vez
Dos llegadas simultáneas
Lista, mismos parámetros
Usar resultado guardado
Sin segundo crédito
En curso
Esperar o conciliar
Procesos en competencia
Misma clave, distintos datos
Rechazar conflicto
Otra cantidad o jugador
Rollback antes de commit
Reintentar de forma controlada
Falla después de reservar
Un buzón durable de eventos puede ayudar, pero recibir el callback no prueba que se haya contabilizado dinero. Conserva estados explícitos, referencia al libro y resultado inmutable. Según la API, una reversión puede ser un movimiento independiente o una transición de la operación relacionada. [1] [3]
¿Qué responder a duplicados y reintentos incompatibles?
Ante una repetición autenticada y ya registrada, devuelve el resultado anterior o el código de duplicidad que pide el proveedor. No existe una regla general que obligue a usar HTTP 200, 409 o un JSON específico para todos. St8, 7SoftTech y GR8 Tech documentan contratos de respuesta distintos. [1] [2] [3]
Establecer respuestas coherentes para el mismo ID con la misma intención de negocio.
Rechazar el mismo ID cuando cambia importe, moneda, jugador o acción.
Después de un commit cuya respuesta se perdió, reutilizar la decisión sin nuevo asiento.
Diferenciar rechazo comercial definitivo de error técnico temporal para decidir próximos intentos.
No repitas un saldo viejo cuando el proveedor exige saldo actualizado ni inventes un código de error. Confirma reglas sobre reenvíos, cancelaciones y operaciones rechazadas. Una solicitud HTTP POST no se vuelve segura para repetirla solo por utilizar ese método. [2] [3] [7]
¿Cuándo reintentar, esperar o dejar de enviar solicitudes?
La respuesta depende de la semántica de idempotencia y el tipo de error. Un timeout o una falla temporal puede dejar desconocido el resultado previo. Firmas incorrectas, datos inválidos o decisiones finales no deben causar intentos infinitos. Configura límite de reintentos, intervalos crecientes con jitter y un camino de conciliación. [4] [6] [7]
Condición
Acción sugerida
Motivo
Timeout tras enviar
Consultar o repetir mismo ID
Commit desconocido
5xx / límite temporal
Reintento limitado
Falla transitoria
Firma inválida
Rechazar y alertar
Sin autenticidad
Rechazo final
Detener según contrato
Reintentar no lo corrige
Respuesta perdida post-commit
Recuperar resultado guardado
Evitar doble cargo
Separa los reintentos automáticos de las correcciones manuales. El equipo debe saber qué mensaje puede reenviar, cuál exige consulta de estado y cuál requiere investigación. No cambies el ID de negocio para forzar una transferencia cuyo estado se desconoce. [3] [4]
¿Qué ocurre si los eventos llegan fuera de orden?
Las colas pueden alterar el orden, e incluso una cancelación puede llegar antes del débito original. Algunos contratos exigen conservar una marca de reversión para impedir que la apuesta inicial se contabilice cuando llegue tarde. Otros proveedores usan reglas diferentes; no generalices los códigos específicos de una API. [1] [2] [5]
Guardar referencia original y estado comercial, no solo fecha de recepción.
Documentar transiciones permitidas de débito, crédito, cancelación y ajuste por integración.
Mantener una marca durable de cancelación anticipada cuando lo exige el contrato.
Enviar referencias sin resolver a conciliación sin generar movimientos artificiales.
El orden de recepción no equivale al orden del negocio. No ordenes asientos por una fecha que envía un cliente remoto. Decide según identidad, dependencias y estado financiero autoritativo del proveedor o del operador. [2] [5]
¿Cómo conciliar y monitorear tras una interrupción?
El callback puede recibirse pero fallar antes del asiento, o el asiento quedar listo sin confirmar la entrega al remitente. Monitorea por separado el transporte y el registro contable. Concilia claves dudosas con el libro del operador y los datos del proveedor; define procedimientos explícitos para conflictos. Actualizar el saldo visible no basta. [1] [3] [4]
Medir intentos, duplicados confirmados, errores de firma, conflictos de contenido y cola de conciliación por proveedor.
Alertar sobre timeouts frecuentes, transacciones pendientes, cancelaciones tempranas y discrepancias.
Restringir reprocesos manuales a personal autorizado con ID original y motivo auditable.
Comparar asientos del operador y registros del proveedor antes de crear ajustes compensatorios.
Mantener claves de deduplicación durante los plazos acordados de reintentos y controversias.
Evita datos personales o financieros completos en la analítica general. Guarda identificadores seguros, huellas, tiempos, cambios de estado y acciones autorizadas. Distingue el volumen de mensajes duplicados de las diferencias reales en el libro financiero. [4] [6]
¿Qué pruebas de aceptación comprueban reintentos seguros?
Procesar una apuesta y un premio correctamente una vez no prueba idempotencia. La certificación debe cubrir IDs repetidos, cambios inesperados de parámetros, workers paralelos, respuestas perdidas, cancelaciones y eventos tardíos conforme al contrato. 7SoftTech ofrece ejemplos explícitos para callbacks bet, win y cancel repetidos. [2]
Registrar un débito o crédito, reenviar el callback firmado y confirmar un solo asiento.
Usar el mismo ID con cantidad, jugador o moneda diferentes y verificar rechazo controlado.
Hacer competir dos entregas, perder la respuesta posterior al commit y recuperar el resultado.
Entregar una cancelación antes de su origen y verificar la regla específica del proveedor.
Simular una caída, procesar eventos retrasados y conciliar totales y rastros de auditoría.
Antes del lanzamiento confirma con cada socio las respuestas, la unicidad, la duración de reintentos y las reglas de reversión. El éxito no significa que nunca haya mensajes duplicados: significa que cada movimiento autorizado produzca un solo efecto correcto incluso cuando se pierde una respuesta o cambia el orden de entrega. [1] [3] [4]