Checklist de integración de API de casino: qué construir, probar y vigilar antes de salir a producción

Última revisión 2026-10-09

La integración de una API de juegos de casino falla en sitios previsibles: un débito reintentado que se cobra dos veces, un rollback de una apuesta que nunca recibiste, una divisa con tres decimales. Esta checklist recorre cada capa en el orden en que se la encuentra un desarrollador, con el fallo que evita cada comprobación.

Esta checklist de integración de API de casino es para el desarrollador que ya tiene las claves API y una fecha límite. Sigue el orden en que aparecen las cosas en la práctica: primero el contrato entre tu wallet y el proveedor, luego el lobby, después el lanzamiento de juegos y, por último, las pruebas y la primera semana en producción.

Cada punto está aquí porque, sin él, algo se rompe. Márcalos en un documento compartido y envía los pendientes al equipo de integración del proveedor en forma de preguntas.

0. Antes de la primera línea de código

• Tienes la documentación API completa, no un PDF comercial: cada endpoint, cada código de error, payloads de ejemplo.
• Conoces el modelo de wallet. Seamless (el proveedor llama a tu servidor en cada apuesta y cada premio) o transfer (mueves dinero a un saldo en el lado del proveedor). Esta checklist da por hecho seamless, que es lo que venden la mayoría de agregadores.
• Las credenciales y la URL de callback de staging están separadas de las de producción.
• La firma de las peticiones está clara: qué cabecera, qué algoritmo (normalmente HMAC-SHA256), qué campos se firman y en qué orden.
• Conoces las IP de salida del proveedor, por si quiere que las incluyas en una lista de permitidas.
• Tienes un contacto técnico con nombre y un canal que responde en horas.

1. Callbacks del wallet

El proveedor llamará a tu servidor para cuatro cosas. Constrúyelas antes que nada.

• Saldo (balance). Devuelve el saldo disponible actual del jugador en su divisa.
• Débito (apuesta). Resta la apuesta si hay fondos y devuelve el nuevo saldo. La falta de fondos devuelve el código de error documentado, no un 500.
• Crédito (premio). Suma el premio. Un crédito de cero es válido y debe procesarse bien; muchos estudios lo envían para cerrar una ronda perdedora.
• Rollback (reembolso). Revierte un débito anterior concreto.
• Cada respuesta se firma o se valida como exige la documentación.
• Verificas la firma entrante en cada llamada y rechazas las incorrectas con el código documentado.
• Tu endpoint responde muy por debajo del timeout del proveedor. Busca la cifra en la documentación. Si dice 3 segundos, apunta a menos de 300 ms en el percentil 99.
• Los importes se guardan como enteros en unidades menores o como decimales de coma fija. Nunca como floats.
• Débito y crédito llevan un ID de ronda y un ID de juego. Guarda los dos.

Escenario. Un jugador con una conexión móvil lenta hace un giro. Tu débito se procesa, pero la respuesta tarda 4 segundos y el proveedor se rinde a los 3. Ahora el proveedor envía un rollback o reintenta el débito, según sus reglas. Las secciones 2 y 3 existen para este momento.

2. Idempotencia

• Hay una restricción de unicidad sobre el ID de transacción del proveedor en tu tabla de transacciones.
• Un débito o crédito repetido con el mismo ID de transacción no vuelve a mover dinero. Devuelve la respuesta original, con los mismos valores de saldo.
• Una llamada repetida con el mismo ID pero otro importe se rechaza y se registra con alarma. Es un bug del proveedor o un ataque.
• Los cambios de saldo y la inserción de la transacción ocurren en una sola transacción de base de datos. No hay ningún instante en que exista uno sin el otro.
• Las llamadas concurrentes del mismo jugador se serializan (bloqueo de fila o equivalente). Dos débitos simultáneos desde dos pestañas de juego abiertas no pueden pasar los dos contra un saldo que solo cubre uno.

3. Rollbacks

• Un rollback hace referencia al débito que cancela. Búscalo por el ID de transacción del proveedor.
• Rollback de un débito que nunca recibiste: regístralo como marca (tombstone) y devuelve éxito (o el código documentado). Si el débito llega más tarde, esa marca impide que lo cobres.
• Rollback de un débito ya revertido: devuelve la respuesta original.
• Rollback de un débito cuya ronda ya tiene un premio: sigue la documentación al pie de la letra. Algunos proveedores lo prohíben, otros esperan que reviertas ambos.
• Los rollbacks nunca dejan un saldo en un estado inexplicable. Si pudieran dejarlo en negativo, decide la regla ahora y déjala por escrito.

4. Rondas y partidas sin terminar

• Puedes ver qué rondas están abiertas (débito recibido, sin crédito de cierre).
• Sabes cómo cierra el proveedor las rondas atascadas: crédito automático tras un timeout, una herramienta manual o un ticket de soporte.
• Los premios de bonos y de free rounds van etiquetados para que tu lógica de bonos los trate de forma distinta a los premios en efectivo.
• Tu backoffice muestra el historial completo de rondas por jugador: cada llamada, cada respuesta, con marcas de tiempo.

5. Divisas

• Cada jugador tiene una única divisa fija, definida en el registro, enviada en el lanzamiento y repetida en cada callback.
• Compruebas que la divisa del callback coincide con la del jugador y rechazas las discrepancias.
• Los decimales son correctos para cada divisa. La mayoría de divisas fiat usan dos, algunas cero y otras tres. Las cripto pueden usar ocho o más; acuerda con el proveedor la precisión que viaja en las llamadas.
• Cada juego que listas admite de verdad la divisa en la que lo muestras. Un estudio puede admitir EUR y USD pero no BDT ni ETB.
• Los límites de apuesta por divisa tienen sentido. Una apuesta mínima pequeña en EUR puede resultar rara en IDR o enorme en BTC.
• En los informes no se mezclan la divisa de visualización y la de liquidación.

6. Sincronización de la lista de juegos

• La lista de juegos se descarga de la API de forma programada, al menos una vez al día, y se guarda en local.
• Los juegos desactivados o retirados desaparecen del lobby en la siguiente sincronización, no el trimestre que viene.
• Si haces curación, los juegos nuevos entran en estado de revisión, no directamente en el lobby.
• Guardas el ID de juego estable del proveedor, no el nombre. Los nombres cambian.
• Las imágenes se cachean en tu lado o se sirven a un tamaño adecuado para móvil.
• Cada juego lleva su categoría, estudio, dispositivos y divisas admitidas, para que los filtros del lobby no mientan.
• Los estudios desactivados para un mercado se filtran con tus propias reglas, no se dejan al azar.

7. URLs de lanzamiento

• El lanzamiento con dinero real pasa un token de sesión de vida corta vinculado al jugador. Nunca una contraseña ni un ID reutilizable.
• La caducidad del token está gestionada: una pestaña antigua muestra un mensaje claro, no un frame roto.
• Idioma, divisa, tipo de dispositivo y URL de vuelta al lobby se definen en el lanzamiento.
• Se pasa una URL de depósito o de cajero cuando el juego lo admite, para que «fondos insuficientes» lleve a algún sitio.
• El juego se abre bien tanto en un iframe como en una ventana nueva. Algunos estudios bloquean los iframes en ciertos dominios o navegadores.
• Los lanzamientos en modo demo, si existen, nunca tocan el wallet real. Pruébalo de forma explícita.
• El tiempo desde el clic hasta el primer fotograma se mide en un móvil de gama media con 4G. Más de 5 segundos hace perder jugadores.

8. Pruebas

• Un jugador de prueba por cada divisa que vayas a admitir.
• Una ronda completa por tipo de juego: slot, mesa en vivo, crash, juego de mesa, virtual.
• Fallos forzados: tu servidor devuelve un timeout, un 500, un código de fondos insuficientes. Observa qué hace después el proveedor.
• Llamadas duplicadas reenviadas a mano: débito dos veces, crédito dos veces, rollback dos veces.
• Llamadas desordenadas: rollback antes del débito, crédito después del rollback.
• Dos pestañas, mismo jugador, girando a la vez.
• Caducidad de la sesión en mitad de la partida.
• Un premio grande y un premio de cero.
• Tu informe de conciliación coincide con el del proveedor para el periodo de prueba, al céntimo.

9. Salida a producción

• Claves y URL de callback de producción cambiadas, y staging desactivado para los jugadores reales.
• Monitorización de la latencia de los callbacks, la tasa de errores y los fallos de firma, con alertas que llegan a una persona, no a un panel que nadie abre.
• Proceso de conciliación diaria: tus totales por juego y por divisa contra los del proveedor.
• En modelos prepago, una alerta de crédito bajo bastante por encima de cero, y alguien que pueda recargar un domingo.
• Un interruptor de apagado por juego y por estudio en tu backoffice.
• El canal de soporte del proveedor y el contacto de escalado, apuntados en tu runbook.

10. Los primeros siete días

• Revisa la conciliación cada mañana.
• Revisa todos los callbacks rechazados y las rondas abiertas.
• Vigila los errores de lanzamiento por estudio; un estudio que falla puede hundir un lobby entero.
• Pide al proveedor su parte de los logs de errores y compáralos.

Un equipo pequeño que lanza una marca cripto puede completar esta lista en una semana si la documentación del proveedor es sólida. Si la documentación es escasa, la lista también sirve para poner a prueba al proveedor: cuenta cuántos puntos has tenido que preguntar. El ranking de seamless wallet y la página de agregadores para nuevos operadores puntúan a los proveedores precisamente en este tipo de trabajo de integración.