Esta guía de integración de API de lotería sirve como documento para compradores e implementadores. Explica qué especificar antes de elegir una modalidad de entrega y qué pruebas solicitar antes de aceptar el trabajo. No es documentación de la API de WhiteLotto: los ejemplos describen requisitos que deben acordarse, no endpoints, métodos de autenticación, integraciones ni funciones incluidas confirmados. Empiece por la descripción de la solución WhiteLotto y acuerde después el alcance real de las interfaces con el equipo de entrega.
Empiece por los límites de la integración, no por una lista de endpoints
Identifique qué sistema controla la cuenta del jugador, el registro de movimientos del monedero, el registro del boleto, la información del sorteo, la decisión de verificación y la comunicación con el cliente. Una interfaz independiente, un back office existente del operador y un servicio de pagos externo crean límites distintos. Una API puede exponer una función sin transferir la responsabilidad operativa correspondiente.
Dibuje el recorrido de una transacción y marque cada traspaso. Para cada límite, registre el sistema que llama, el registro autoritativo, la acción permitida, la respuesta esperada y el responsable de un estado no resuelto. Incluya acceso al back office e informes: una integración que permite comprar pero impide a finanzas conciliar está incompleta.
Incluya este mapa en el documento de evaluación de proveedores. Clasifique cada capacidad solicitada como disponible y acreditada, configurable, personalizada, dependiente de terceros o fuera de alcance. No trate una función de la hoja de ruta como una interfaz comprometida.
API, iFrame o frontend completo: elija el límite de responsabilidad
Una integración mediante API, un iFrame integrado y un frontend entregado por el proveedor dejan distintas partes del recorrido del jugador bajo su control. Elija según la experiencia que necesite gestionar, los sistemas existentes y el equipo disponible para mantener la conexión. Esta decisión es independiente de la denominación comercial «marca blanca» o «turnkey»: acuerde el alcance real de la interfaz y de su operación.
Utilice la visión general de los módulos de la plataforma para identificar qué permanece en su infraestructura. Compare las opciones con el mismo recorrido de compra, en lugar de evaluar una demostración aislada.
| Modalidad | Interfaz del jugador | Responsabilidades que acordar | Enfoque de aceptación |
|---|---|---|---|
| API con frontend propio | Su equipo desarrolla el recorrido de lotería sobre las interfaces acordadas. | Versiones de la interfaz, mantenimiento del adaptador, correspondencia de cuentas y soporte operativo. | El comportamiento técnico y el recorrido del cliente deben funcionar juntos. |
| iFrame integrado | Una interfaz de lotería suministrada se incorpora al sitio existente. | Transferencia de sesión, navegación exterior, comunicación entre interfaces y gestión de incidencias. | Entrada, compra, recuperación y regreso al sitio principal. |
| Frontend completo suministrado | El recorrido web acordado se entrega dentro del alcance de la plataforma. | Marca, cambios de contenido, cuentas, límites del monedero, versiones y exportaciones. | Todo el recorrido acordado, incluidos administración e informes. |
Resuelva los límites de cuenta, monedero y sesión antes de aprobar el diseño
En un casino o una casa de apuestas existente, especifique si el jugador de lotería utiliza la cuenta actual, una cuenta vinculada o un registro independiente. Identifique el sistema que aplica las restricciones y qué ocurre si cambian la verificación o los permisos durante una sesión activa. Pregunte cómo vuelve el jugador después de cerrar sesión, cambiar de dispositivo o abrir un enlace caducado. Una pantalla integrada atractiva no resuelve estas cuestiones operativas.
Separe el saldo mostrado del registro financiero de referencia. Acuerde qué sistema autoriza la compra y cómo recibe la interfaz principal los cambios en fondos, boletos o permisos. La guía de monedero y conciliación aborda el límite financiero; el modelo de integración debe explicar cómo lo percibe el jugador.
Asigne un responsable a cada error visible. Distinga un problema de sesión del sitio principal, una interfaz integrada no disponible, una acción de lotería rechazada y una transacción sin resolver. Defina el mensaje, la siguiente acción permitida y la referencia para soporte. Al abrir de nuevo la página, el jugador debe llegar a un estado acordado y disponer de una vía de investigación si el resultado sigue siendo incierto.
Acepte el modelo de integración además de las transacciones individuales
Añada comprobaciones específicas del modelo a la lista de aceptación UAT y puesta en producción. Pruebe la entrada desde el sitio principal, la caducidad de sesión durante la selección de números, un cambio de restricciones, un componente no disponible y el regreso del pago. Incluya navegación móvil, acceso mediante teclado y vuelta al historial de boletos.
Para cada escenario, registre el sistema responsable, la pantalla prevista, el estado de cuenta o transacción de referencia y la persona encargada de resolverlo. Incluya el traspaso de soporte entre equipos. La modalidad está preparada cuando esas responsabilidades se aceptan conjuntamente, no solo cuando carga una pantalla o responde una interfaz.
CONTACTO para tratar su frontend, sus sistemas de cuenta y monedero y el recorrido de lotería que desea incorporar.
Prepare un registro de requisitos al que los proveedores puedan responder
Utilice una fila por interfaz u operación de negocio, en lugar de una sola fila titulada «integración de API». Añada responsable, prioridad, dependencia, referencia de evidencia y decisión de aceptación a estas preguntas.
| Área | Requisito que debe definirse | Evidencia que debe solicitarse |
|---|---|---|
| Contrato de interfaz | Operaciones, campos, identificadores, errores, versión y entorno admitido. | Especificación versionada y ejemplos representativos de solicitudes y respuestas con datos sintéticos. |
| Límite de acceso | Clientes, roles, marcas y recursos permitidos; emisión, rotación y revocación del acceso. | Matriz de acceso y pruebas de acciones denegadas para el despliegue acordado. |
| Dinero y boletos | Registros autoritativos, transiciones de estado, cierre de ventas y tratamiento de duplicados. | Traza que conecte las referencias del boleto, monedero y proveedor. |
| Eventos asíncronos | Autenticación, duplicados, orden, reintentos y recuperación tras una interrupción. | Contrato de eventos documentado y resultados de casos de fallo. |
| Capacidad y límites | Picos previstos, concurrencia, tiempos de espera, límites de solicitudes y respuesta a sobrecargas. | Hipótesis de carga acordadas y pruebas del alcance correspondiente. |
| Datos e informes | Campos necesarios, conservación, permisos de exportación, marcas de tiempo y vistas de conciliación. | Diccionario de datos y muestra de exportación utilizable, sin registros personales. |
| Cambios y soporte | Compatibilidad, aviso de retirada, responsabilidad en incidentes y condiciones de salida. | Proceso de publicación, escalado y alcance contractual. |
La especificación OpenAPI ofrece una forma estándar de describir interfaces HTTP. Pregunte si la interfaz propuesta dispone de una descripción actualizada, qué versión utiliza y qué comportamientos requieren documentación adicional. Un contrato legible por máquinas facilita la revisión; no demuestra la corrección de las transacciones, la seguridad ni el soporte operativo.
Acuerde el modelo de datos y el sistema de registro
Mapee los identificadores entre el operador, la plataforma y el servicio externo. Distinga el identificador de solicitud del identificador de boleto, la referencia de pago y el asiento del registro de movimientos. Decida cómo puede soporte relacionarlos sin introducir información personal en URLs o registros de acceso irrestricto.
Especifique importes, monedas, precisión, zonas horarias, significado de las marcas de tiempo y definiciones de estado. «Aceptado» puede significar recibido para procesamiento, no boleto confirmado. «Pagado» puede describir un evento del procesador, no la liquidación definitiva. Documente quién puede cambiar cada estado y cómo se registran las correcciones.
Para datos de sorteos y resultados, defina la fuente autoritativa, la actualidad, la política de correcciones y quién liquida los boletos afectados. Especifique la zona horaria del cierre de ventas y la regla para solicitudes próximas a ese límite; una cuenta atrás en la interfaz no determina la aceptación del boleto.
Solicite únicamente la información del jugador que necesita cada integración. Defina acceso, conservación, exportación y uso permitido con los responsables adecuados. La guía sobre titularidad de datos del jugador distingue el acceso operativo útil de las cuestiones contractuales y de privacidad más amplias. La conectividad técnica no establece el derecho a transferir o reutilizar registros.
Diseñe para resultados inciertos y mensajes repetidos
Considere una compra sintética en la que el servicio receptor acepta la solicitud, pero la conexión se cierra antes de que llegue la confirmación al emisor. Un tiempo de espera agotado no demuestra que no haya ocurrido nada. La especificación necesita un mecanismo admitido para establecer el resultado original y evitar que un reintento produzca un segundo efecto financiero.
La semántica HTTP de RFC 9110 distingue las operaciones idempotentes y desaconseja reintentar automáticamente solicitudes no idempotentes sin saber que es seguro. Para compras y cambios en el monedero, acuerde la política de duplicados de la aplicación, la duración de su protección y qué ocurre si llega la misma referencia con contenido diferente. No deduzca esas garantías únicamente del método HTTP.
Para eventos o callbacks, pregunte cómo el receptor verifica el origen, detecta duplicados, gestiona entregas tardías o desordenadas y recupera el procesamiento omitido. Como referencia específica de un proveedor, la documentación de webhooks de Stripe aborda firmas, eventos repetidos y procesamiento asíncrono. Es un ejemplo de las preguntas que debe responder el contrato, no evidencia de que WhiteLotto utilice Stripe o admita el mismo modelo de eventos.
La aceptación debe vincular el resultado final de negocio con sus registros: una compra prevista, el efecto acordado en el monedero, un estado de boleto trazable y una excepción con responsable si la confirmación sigue pendiente. Aplique la misma disciplina a reembolsos, anulaciones y liquidación. La guía de la infraestructura de pagos de lotería explica por qué una respuesta de pago satisfactoria y una conciliación útil son requisitos diferentes.
Incluya seguridad y capacidad en la aceptación
Confirme el mecanismo real de autenticación, los permisos de acceso, el responsable de credenciales y los procesos de almacenamiento, rotación y revocación. Nunca introduzca credenciales de producción en un documento de compra, ejemplo compartido o código entregado al navegador. Separe los entornos y utilice datos sintéticos en demostraciones.
La autorización debe comprobarse para la operación y el recurso solicitado, no solo para la existencia de una sesión válida. Solicite pruebas de un rol no autorizado, un límite entre marcas o cuentas y un cliente revocado. El OWASP API Security Top 10 es una referencia útil sobre acceso a objetos, autenticación, consumo de recursos e inventario. No es una certificación ni demuestra que una plataforma concreta supere esos controles.
Describa la carga prevista: tráfico estable, un pico asociado a un sorteo, compras concurrentes, tareas de informes y recuperación de eventos retrasados. Acuerde qué sucede al alcanzar los límites y qué solicitudes pueden aplazarse con seguridad. Registre los límites de medición de latencia y disponibilidad, incluidas dependencias, en lugar de introducir un objetivo de rendimiento sin fundamento. Utilice la lista de seguridad, disponibilidad y SLA para ampliar la discusión sobre pruebas y escalado.
Utilice un paquete de aceptación pequeño pero completo
Registre la versión de interfaz, configuración, entorno de prueba, datos sintéticos, resultado esperado y evidencia real de cada prueba. Incluya emisor, receptor y responsable operativo. Una grabación de pantalla por sí sola no acredita el estado resultante del registro de movimientos o del boleto.
- Siga un recorrido satisfactorio desde la solicitud hasta el resultado confirmado y su informe.
- Compruebe una solicitud rechazada o inválida, un límite de cierre de ventas y una respuesta no resuelta.
- Repita una solicitud y un evento de prueba permitidos para verificar la política de duplicados acordada.
- Pruebe el acceso denegado, caducado o revocado, las entradas malformadas y los límites acordados.
- Interrumpa una dependencia externa y demuestre recuperación o una cola de excepciones con responsable.
- Verifique que soporte y finanzas pueden investigar mediante registros permitidos.
Separe los defectos bloqueantes de las mejoras opcionales. La lista para demos de plataformas de lotería ayuda a organizar una conversación basada en evidencia, pero una demostración no sustituye la aceptación de la integración contratada.
Prueba operaciones API sin resolver, no solo respuestas correctas
Solicita una demostración aislada con registros sintéticos: envía una solicitud de boleto, interrumpe la confirmación y reintenta con la misma clave de operación. La evidencia debe conectar solicitud, estado del boleto y registro financiero sin efectuar un pago real.
- Especifica qué sistema controla el resultado definitivo y cómo consultarlo cuando no está disponible la primera respuesta.
- Define estados pendiente, aceptado, rechazado y cancelado; agotar el tiempo no implica automáticamente que la compra haya fallado.
- Repite solicitud y notificación para comprobar que no se duplican boletos ni registros financieros.
- Incluye operaciones sin resolver en una exportación de conciliación, con referencias, marcas temporales y un responsable asignado.
Incluye tiempo de recuperación y responsables de escalado en los requisitos de servicio. Lleva los mismos escenarios a la matriz de aceptación del RFP, sin interpretar una lista de interfaces API como prueba de recuperación.
Elige primero la arquitectura y prioriza después cada integración
Mantén esta guía como mapa general de requisitos. No empieces conectando todos los proveedores disponibles: elige sistemas autoritativos y el recorrido completo mínimo que exige la versión acordada. Registra dependencia de negocio, responsable de datos, propietario del adaptador, acceso a terceros y evidencia de aceptación de cada interfaz.
| Área | Decisión previa al desarrollo | Guía detallada |
|---|---|---|
| Sorteos y resultados | Identidad autoritativa, cierre, revisiones y responsabilidad de liquidación. | Integración de sorteos y resultados |
| Pagos | Regla de abono, reintento seguro, eventos verificados y conciliación. | Integración de pasarela de pagos |
| KYC | Estados, permisos, tratamiento manual y datos necesarios. | Requisitos de integración KYC |
| Puntos de venta | Aceptación válida, política offline, recuperación y liquidación del local. | Integración POS de lotería |
| Cuentas de jugadores (PAM) | Responsabilidad de identidad, estados, restricciones, acceso de sesión y recuperación de eventos. | Integración de gestión de cuentas |
| Suscripciones y múltiples sorteos | Renovación frente a compra anticipada, reintentos de pago, cierre y asignación de boletos. | Requisitos de suscripciones y múltiples sorteos |
| Premio instantáneo y rascas digitales | Compromiso de ronda, responsabilidad del resultado, asientos y recuperación de partidas interrumpidas. | Checklist de integración de premio instantáneo |
| Riesgo de jackpot y financiación de premios | Obligaciones de premios, fuente de financiación, límites de exposición y evidencias de liquidación. | Financiación de premios y evaluación del riesgo |
Ordena dependencias alrededor de una operación recuperable
Para comprar, acuerda conjuntamente cuentas y controles, reglas de financiación o monedero, boleto aceptado, sorteos/resultados y exportación financiera. Implementa y prueba un recorrido ficticio completo antes de multiplicar proveedores. Varias llamadas API correctas pero desconectadas pueden dejar a soporte sin capacidad de resolver una compra incierta.
Distingue lo imprescindible para publicar de una extensión comercial posterior. El alcance incluye monitorización, sandbox, recuperación de eventos, documentación y coordinación, no solo código. Un proveedor que no ha aprobado el modelo o no ofrece un entorno de prueba utilizable sigue siendo dependencia aunque el desarrollo interno haya terminado.
Incluye la responsabilidad de cambios en el contrato
Conserva inventario versionado, responsables y política de retirada de versiones. Acuerda cómo anunciar y aceptar cambios de campos, firmas, estados e informes. Mantén una ruta anterior cuando sea segura, reconociendo que revertir un adaptador no revierte registros financieros escritos.
La especificación OpenAPI sirve para describir contratos HTTP. Estados de negocio, recuperación y responsabilidades necesitan documentación explícita adicional. Convierte requisitos en la matriz UAT y utiliza el marco de KPI para comprobar que la integración publicada sigue siendo observable.
Presupueste la responsabilidad después de la primera entrega
Asigne responsables a cada adaptador, regla de monitorización y vía de gestión de incidentes. Acuerde comprobaciones de compatibilidad, avisos de cambios de interfaz, un proceso seguro de actualización y quién paga cambios fuera del alcance original. Incluya coordinación con socios, informes, acceso de prueba y futuras migraciones, no solo la programación de la primera conexión.
Lleve el registro de integraciones a una conversación de alcance con WhiteLotto. Aporte el diagrama de límites entre sistemas, operaciones necesarias, hipótesis de tráfico, secuencia prevista y dependencias pendientes. Pregunte qué requisitos pueden acreditarse ahora y cuáles necesitan más análisis. No envíe exportaciones de jugadores, credenciales ni registros privados de producción.
Preguntas frecuentes sobre integración de API de lotería
¿Esta guía documenta la API de WhiteLotto?
No. Es una guía de requisitos y aceptación. Obtenga del equipo de entrega la especificación vigente acordada y el alcance de implementación antes de desarrollar contra una interfaz.
¿Una API elimina la necesidad de conciliación?
No. Las interfaces trasladan información; la conciliación determina si los registros relacionados coinciden y quién se responsabiliza de una discrepancia. Defínala para monedero, boletos, pagos y liquidación.
¿Puede estimarse el trabajo de integración a partir de una lista de proveedores?
La lista es un punto de partida. Una estimación fiable también necesita operaciones, contratos, acceso a entornos, mapeo de datos, comportamiento ante fallos, carga y responsabilidades de aceptación.
¿Podemos conservar nuestros sistemas actuales de monedero, pagos, KYC y CRM?
La continuidad de un sistema existente debe evaluarse según el alcance acordado y sus interfaces actuales y documentadas; la expresión «integración API» no la garantiza. Identifique el sistema que mantiene el registro de referencia de cuentas, saldos, decisiones de verificación y mensajes al cliente, y después relacione los identificadores y estados de negocio entre sistemas. Acuerde las acciones permitidas, la gestión de excepciones, las pruebas de aceptación y un responsable de cada conexión. Incluya estos requisitos en la lista de evaluación para la solicitud de propuestas antes de decidir qué componentes se conservan, cuáles necesitan adaptadores y cuáles requieren un reparto distinto de responsabilidades operativas.
¿Cómo deben gestionarse los reintentos y las notificaciones duplicadas?
Defina el comportamiento requerido de los reintentos en el contrato de la interfaz: una referencia de negocio estable y un alcance explícito de idempotencia, con un periodo de protección acordado. Las notificaciones entrantes requieren verificar su origen y detectar duplicados de forma persistente para impedir que una repetición cree otro boleto o asiento financiero. Si una respuesta es incierta, exija consultar el estado o conciliar los registros antes de repetir la operación a ciegas. Las pruebas de aceptación deben cubrir notificaciones duplicadas o fuera de orden, respuestas interrumpidas y solicitudes repetidas con contenido modificado. La guía de integración de pasarelas de pago ofrece una lista específica de requisitos; no documenta los endpoints de WhiteLotto.
Wojciech Lysak es el director general de WhiteLotto.com. LinkedIn