API de sorteos y resultados de lotería: integración y liquidación
Una integración API de sorteos y resultados debe conservar la relación entre el sorteo correcto, el boleto aceptado, el resultado autorizado y su liquidación. El trabajo decisivo consiste en definir cierres de venta, zonas horarias, revisiones de resultados y recuperación de mensajes ausentes o repetidos, no solo en mostrar números ganadores. Esta es una guía […]
Una integración API de sorteos y resultados debe conservar la relación entre el sorteo correcto, el boleto aceptado, el resultado autorizado y su liquidación. El trabajo decisivo consiste en definir cierres de venta, zonas horarias, revisiones de resultados y recuperación de mensajes ausentes o repetidos, no solo en mostrar números ganadores.
Esta es una guía de requisitos independiente del proveedor, no una especificación de endpoints reales de WhiteLotto ni una promesa de que todas las interfaces descritas estén incluidas. Empieza por la guía de arquitectura API de lotería y acuerda el contrato real con el equipo de implementación.
Utiliza identificadores estables, no solo fechas
La fecha no identifica de forma fiable un sorteo cuando un producto tiene varios sorteos diarios, cambios de horario o múltiples zonas horarias. Relaciona los identificadores del producto, del sorteo del proveedor y del sorteo de la plataforma. Conserva esas referencias en boletos e informes. Decide si un sorteo reprogramado mantiene su identidad y cómo una cancelación afecta a los boletos aceptados.
| Registro | Definir antes de implementar | Evidencia de aceptación |
|---|---|---|
| Calendario de sorteos | ID estable, producto, hora prevista, cierre de ventas y zona horaria aplicable. | Una trazabilidad entre catálogo, compra e informe. |
| Aceptación del boleto | Hora autoritativa de aceptación, regla de cierre y respuestas inciertas. | Casos justo antes, en el límite y después del cierre. |
| Resultado | Fuente autoritativa, estado, publicación, versión e integridad. | Resultados no publicados, preliminares y definitivos. |
| Corrección | Referencia de revisión, motivo, aprobación y tratamiento de boletos afectados. | Historial que relaciona el resultado anterior con el corregido. |
| Liquidación | Disparador, responsable del cálculo, referencias de apuntes y conciliación. | Un efecto financiero por cada liquidación prevista. |
Acuerda el significado del tiempo y el cierre de ventas
Guarda un instante inequívoco junto con la zona horaria local identificada que utilizan la presentación al cliente y las reglas del negocio. El formato de marcas temporales RFC 3339 es una referencia para representar un instante con desplazamiento horario. El desplazamiento por sí solo no describe las futuras reglas regionales de cambio de hora.
Especifica si la aceptación depende de la llegada a la plataforma, de la aceptación por un proveedor o de otro evento contractual. Una cuenta atrás en pantalla es informativa: no debe decidir si existe el boleto. Prueba sincronización, desfase de relojes, solicitudes retrasadas y cambios de hora. Muestra un resultado claro cuando las ventas hayan cerrado.
Un timeout cerca del cierre necesita una consulta del resultado o un proceso de excepción con responsable. Reintentar sin comprobar puede crear un duplicado o un boleto para otro sorteo. Conserva la operación original y el sorteo solicitado.
Trata las correcciones como cambios controlados
Distingue resultados recibidos, validados, definitivos y corregidos en el modelo acordado. No interpretes un campo ausente como un boleto perdedor. Define quién aprueba la liquidación y cómo se autentica la fuente. Si se corrige un resultado, conserva la versión anterior y relaciona el ajuste con su motivo y aprobador.
Repetir una notificación no debe liquidar un boleto dos veces. Un resultado antiguo que llegue tarde no debe sustituir una revisión autorizada más reciente. Las correcciones financieras deben ser trazables, no reescribir silenciosamente el historial contable. La guía de integración de pagos aborda esta disciplina para eventos financieros asíncronos.
Haz visibles los eventos ausentes
- Detecta sorteos cuyos resultados no han llegado dentro del plazo operativo acordado.
- Compara el catálogo de origen con el inventario local después de una interrupción.
- Recupera eventos mediante un mecanismo soportado de repetición o consulta.
- Distingue boletos pendientes de resultado y pendientes de liquidación.
- Asigna escalado y mensajes al cliente para sorteos o resultados retrasados.
La guía de idempotencia HTTP ayuda a plantear reintentos seguros, pero las garantías de boletos y liquidación deben especificarse en la aplicación. Utiliza el marco de KPI del operador para medir liquidación completada y antigüedad de excepciones.
Checklist de aceptación del feed de resultados
Utiliza sorteos y boletos ficticios en un entorno autorizado. Prueba cambios de calendario, cancelaciones, mensajes duplicados o desordenados, fuentes no disponibles, resultados incompletos y un resultado definitivo corregido. Verifica conjuntamente estado del boleto, información al jugador, apuntes de liquidación y exportaciones. Registra la versión de la interfaz y la configuración en el paquete de aceptación UAT.
Separa la publicación del resultado, la aprobación de la liquidación y la liberación de retiradas
Un feed de resultados no debe convertirse en una instrucción ilimitada para mover dinero. Define tres límites de aprobación: qué puede mostrarse a los jugadores, qué versión del resultado puede utilizarse para liquidar boletos y qué permite liberar una retirada relacionada. Estas decisiones pueden corresponder a sistemas y equipos distintos. Pide al proveedor que demuestre esos límites con la configuración realmente propuesta, en lugar de asumir que un campo «definitivo» autoriza todas las acciones posteriores.
Proporciona al operador un registro verificable de cada decisión: pruebas de la fuente, sorteo afectado, versión del resultado, alcance de la autorización y persona o regla automatizada aprobada responsable. Una actualización de la pantalla no debe cambiar silenciosamente una decisión de retirada. Coordina estos límites con la guía de gestión de cuentas de jugadores y la guía de integración de pagos; un premio abonado y un pago externo completado son registros diferentes.
| Punto de decisión | Pruebas que conservar | Pregunta sobre responsabilidad |
|---|---|---|
| Publicación para el jugador | Referencia de la fuente, texto autorizado para la presentación y versión del resultado mostrada. | ¿Quién aprueba publicar o corregir la información para el cliente? |
| Proceso de liquidación | Resultado aprobado, alcance de boletos afectados y resumen de cálculos o apuntes. | ¿Quién puede aprobar el proceso y resolver excepciones? |
| Abono en el monedero | Resultado del boleto, referencia del abono y conciliación con el proceso de liquidación. | ¿Quién revisa una diferencia entre el resultado del boleto y el saldo disponible? |
| Liberación de la retirada | Referencia del pago, controles aplicables y decisión registrada para esa retirada. | ¿Quién autoriza la liberación, revisión o pausa permitida? |
| Disputa sobre el cierre de ventas | Sorteo solicitado, pruebas de aceptación y regla contractual del límite. | ¿Quién decide la participación y comunica la resolución? |
Prepara una corrección después de que los fondos se hayan movido
Amplía las pruebas de corrección más allá de un boleto pendiente de liquidación. Incluye un premio abonado que sigue en la cuenta, una retirada en revisión y un pago ya completado fuera de la plataforma. Registra boletos afectados, apuntes originales, referencias de retirada y diferencia derivada de la revisión aprobada. Acuerda cómo llegan esos casos a finanzas, operaciones y soporte antes de que alguien aplique un ajuste.
La respuesta debe seguir el contrato aplicable, las condiciones del cliente y el proceso de decisión autorizado; esta guía no prescribe una regla universal de recuperación. No asumas que cambiar el resultado mostrado revierte un pago externo ni que un saldo negativo sea la respuesta automática correcta. Pregunta cómo registra el equipo una decisión de no ajustar, un ajuste permitido o un caso sin resolver. Mantén las responsabilidades de financiación de premios de la revisión de riesgo de jackpot y financiación de premios separadas de la entrega del feed de resultados.
Exige un escenario de corrección detallado en el paquete de aceptación UAT. Utiliza solo registros de prueba y verifica las pruebas de revisión del operador y la explicación al cliente, no únicamente el importe ganador recalculado.
Documenta la resolución de una participación disputada
Para una compra disputada cerca del cierre de ventas, reúne un expediente con el sorteo original solicitado, la trazabilidad de aceptación, el registro del pago y la regla aplicable. Un cargo por sí solo no debe considerarse prueba de participación. Identifica quién puede obtener pruebas del proveedor y quién aprueba la resolución para el cliente. Las decisiones sobre participación, tratamiento del pago o comunicación al cliente deben seguir vinculadas al expediente, no convertirse en soluciones de soporte sin documentar.
Define las pruebas necesarias para cerrar cada excepción, incluidas las diferencias pendientes entre registros del proveedor, boletos y finanzas. Usa el marco de KPI del operador para distinguir el cierre del caso de la simple recepción de un mensaje y la biblioteca de preparación del operador para preparar los equipos implicados. Comparte con WhiteLotto tus límites de aprobación y los requisitos de los casos disputados. CONTACTO
Preguntas frecuentes sobre API de sorteos
¿Basta con publicar los números ganadores?
No. El operador necesita identidad del sorteo, estado autoritativo del resultado, correspondencia con boletos aceptados y liquidación auditable.
¿Puede un resultado corregido sustituir al anterior?
La presentación puede cambiar, pero la operación debe conservar el historial y la relación entre la liquidación original y los ajustes autorizados.
Comparte tus proveedores de sorteos, productos, cierres de venta e informes necesarios en la definición del alcance de plataforma. CONTACTO.