API de apuestas con liquidación

Dos patrones de integración

	iFrame	API
Front-end	Nuestro, incrustado en su sitio	Suyo
Monedero	Suyo, mediante callbacks de monedero único	Suyo, mediante callbacks de monedero único
Tiempo hasta el lanzamiento	De días a un par de semanas	De seis a doce semanas según su front-end
Control sobre la UX	Solo tematización	Total
Usuario típico	Casino que añade una pestaña de apuestas	Operador cuya casa de apuestas es el producto; proveedores de plataforma

Lo que cuesta cada patrón en tiempo de ingeniería

Las seis a doce semanas de arriba son tiempo transcurrido para un equipo de dos personas, estirado por las partes que no pueden ir en paralelo: la autenticación antes que nada, el catálogo antes que el boleto. La tabla es el mismo trabajo en días-ingeniero, repartido por flujo de trabajo, para que se vea qué partes elimina el iFrame. Los rangos son la diferencia entre un equipo que ya ha lanzado un front-end de apuestas y uno que no.

Flujo de trabajo	iFrame	API
Callbacks de monedero y el libro contable que hay detrás	5–10 días	5–10 días
Autenticación, firma de peticiones, claves de idempotencia	2–4 días	2–4 días
Catálogo: deportes, competiciones, encuentros, mercados, selecciones	Nuestro	10–20 días
Actualizaciones de precio y estado en vivo por el canal push	Nuestro	5–10 días
Boleto, colocación y la política de cambio de precio	Nuestro	10–15 días
Pantalla de cash-out: cotización, parcial, caducidad	Nuestro	4–8 días
Vistas de liquidación, reliquidación e historial de apuestas	Nuestro	4–8 días
Límites, autoexclusión y reglas de licencia en su interfaz	Solo tematización	3–6 días
Ejecución de la certificación y las correcciones que produce	3–5 días	5–10 días

De los totales salen dos cosas. El monedero es el mismo trabajo con cualquiera de los dos patrones, y es la parte que más probablemente esté mal, así que el iFrame no le permite saltársela. Lo que el iFrame elimina es el front-end de apuestas: de 36 a 67 días-ingeniero de los de aquí. Esa es la cifra que hay que poner frente a ser dueño de la interfaz, no la diferencia entre las fechas de lanzamiento.

El contrato del monedero único

Su monedero guarda el saldo y nosotros guardamos la apuesta. Ninguna de las dos partes puede reconstruir la otra a partir de sus propios registros, y por eso cada llamada lleva un identificador de apuesta y un identificador de transacción. La tabla detalla las cuatro llamadas: cuándo enviamos cada una, qué necesitamos de vuelta y qué ocurre cuando no vuelve nada.

Llamada	Cuándo la enviamos	Qué necesitamos de vuelta	Si expira el tiempo
Saldo	Al inicio de sesión, y antes de una colocación si sus límites pueden haber cambiado	Saldo disponible por divisa	La apuesta no se acepta. No se ha movido dinero, así que no hay nada que deshacer.
Reservar y cargar el importe	En la aceptación, con la clave de petición, el identificador de apuesta y el importe	Confirmación y el saldo resultante	Reintentamos con la misma clave, y su monedero debe devolver el primer resultado en lugar de volver a cargar. Si queda sin resolver, la apuesta no se mantiene y el intento queda listado como no confirmado.
Abonar ganancias	En la liquidación de una apuesta o selección ganadora, y al ejecutar un cash-out	Confirmación y el saldo resultante	Se reintenta con la misma clave hasta confirmarse. Una ganancia nunca se pierde: se aplica o se reporta como pendiente.
Anular y reliquidar	En una anulación, un evento cancelado o una corrección de resultado oficial	Confirmación, con la diferencia aplicada	Misma clave, misma regla. Una reliquidación que no se puede aplicar se retiene y se reporta, nunca se aplica dos veces.

La clave de petición es todo el contrato. Cada llamada lleva una, y la regla en su lado es que la misma clave siempre produce la misma respuesta: la primera. Un monedero que trata una repetición como una instrucción nueva hará un doble cargo la primera vez que se caiga una conexión, y las conexiones se caen. Por eso el sandbox envía un duplicado de cada llamada, y por eso una clave de producción espera hasta que los duplicados vuelven idénticos. El tiempo de espera y la ventana de reintento se fijan en el contrato junto con los límites de tasa, porque dependen de dónde corra su monedero.

Qué expone la API

Catálogo: deportes, competiciones, encuentros, mercados y selecciones con precios, estado y estado de suspensión. Pre-partido por REST con notificaciones de cambio; en vivo por push (WebSocket) con deltas de precio y estado, reflejando los feeds de origen, que en el caso de Sportradar llegan por AMQP.
Colocación de apuestas: simples, combinadas, sistemas y selecciones de creador de apuestas, con gestión del cambio de precio (aceptar cualquiera, aceptar si sube, rechazar), límites de importe del motor de riesgo y claves de petición idempotentes.
Monedero único: llamamos a su monedero para reservar y cargar el importe, abonar ganancias, anular y reliquidar; un solo saldo para el jugador entre casino y apuestas.
Cash-out: cotizar y ejecutar, total y parcial, en vivo y pre-partido.
Liquidación: resultados y eventos de liquidación por apuesta y por selección, con reliquidación ante una corrección oficial y traza de auditoría completa.
Contexto de cuenta: límites del jugador, autoexclusión y restricciones derivadas de la licencia, enviados con cada petición para que el motor de riesgo y las reglas del regulador se apliquen a sus jugadores igual que a los nuestros.
Informes: volumen apostado, GGR y margen por deporte, mercado y cohorte de jugadores; ficheros de conciliación de liquidación.

Certificación: los escenarios y qué debería ocurrir

Estos son los casos que el sandbox guioniza antes de emitir una clave de producción. La columna central es el comportamiento contra el que certificamos; la columna de la derecha es lo que hace en su lugar una integración que no ha pensado en el caso, y cómo se lee el fallo en su cola de soporte.

Escenario	Comportamiento esperado	Qué hace una integración sin probar
El precio se mueve entre el boleto y la colocación	Aceptar, aceptar si sube o rechazar, según la política enviada con la petición. La apuesta queda a un solo precio.	Acepta al precio obsoleto y después se discute qué precio se mostró.
El mercado se suspende mientras la petición está en vuelo	Rechazada con un motivo de suspensión. No se carga nada.	Carga el importe y luego anula, dejando un cargo y un abono por una apuesta que nunca existió.
Llega una colocación duplicada con la misma clave de petición	Una apuesta, un cargo, y se devuelve de nuevo la respuesta original.	Dos apuestas y dos cargos.
El monedero no responde al cargo	La apuesta no se mantiene; el intento queda listado como no confirmado.	Acepta la apuesta contra un cargo no confirmado y descubre el descuadre en la liquidación.
Cash-out parcial sobre una combinada con una selección ya liquidada	Se cotiza sobre las selecciones aún abiertas; la selección liquidada no se vuelve a valorar.	Valora la apuesta entera y luego no puede liquidar lo que queda de ella.
Se corrige un resultado oficial después del pago	Reliquidación aplicada como diferencia, conservando tanto el original como la corrección.	Sobrescribe la liquidación original, de modo que el historial ya no explica el saldo.
El jugador cruza un límite de depósito o de pérdidas a mitad de sesión	Colocación rechazada por el límite, con el límite nombrado en la respuesta.	Acepta la apuesta, porque el límite vive en su sistema de cuentas y nunca se envió con la petición.
El feed de origen se cae con apuestas abiertas	Los mercados se suspenden, la aceptación se detiene en los encuentros afectados, las apuestas abiertas siguen abiertas y se liquidan cuando lleguen los resultados.	Sigue aceptando precios que han dejado de moverse.

Los feeds que hay detrás

La API es agnóstica respecto al feed. Detrás de ella operamos Sportradar, Genius Sports, LSports u OddsMatrix según su contrato y sus mercados; en llave en mano el contrato de feed es suyo y nosotros lo integramos.

Feed	Cobertura publicada
Sportradar	Más de 900,000 eventos al año, 32 deportes
Genius Sports	Más de 600,000 encuentros, más de 40 deportes
LSports	Más de 175,000 eventos pre-partido al mes, más de 100 deportes, 2,500 mercados
OddsMatrix	Más de 200,000 eventos en vivo al mes

Más sobre cada feed, incluido cuál recomendamos para cada tipo de libro, en la página de apuestas llave en mano.

Qué no incluye una licencia de datos de cuotas

Varios proveedores venden las cuotas como datos, y algunos dicen con claridad en sus propias páginas que son infraestructura de cuotas y no una casa de apuestas. La tabla lista lo que hay entre un precio y una apuesta liquidada, y de dónde sale cada parte bajo los dos modelos.

Qué hace falta	Licencia de datos de cuotas	Esta API
Precios, encuentros y estado de mercado	Incluido	Incluido
Aceptación de apuestas	Lo construye usted	Incluido
Límites de riesgo y exposición por jugador, mercado y evento	Lo construye usted	Los límites de importe llegan del motor de riesgo con la petición
El contrato del monedero	Lo construye usted	Cuatro llamadas, idempotentes, certificadas antes de la salida en vivo
Valoración del cash-out	Lo construye usted	Cotizar y ejecutar, total y parcial
Liquidación de apuestas y selecciones	Lo construye usted	Incluida, por apuesta y por selección
Reliquidación ante corrección oficial	Lo construye usted	Incluida, con la traza de auditoría
Límites del jugador y autoexclusión aplicados en la aceptación	Lo construye usted	El contexto de cuenta viaja con cada petición
Ficheros de conciliación e informes al regulador	Lo construye usted	Incluidos

Una licencia de cuotas es la compra correcta para un medio, un producto de pronósticos o un modelo, ninguno de los cuales coge dinero de un jugador. Es la compra equivocada para un operador, y es la línea más barata del presupuesto, que es como se comete el error.

Sandbox y salida en vivo

Sandbox con reproducciones grabadas de mercados en vivo, para que su front-end se pueda probar contra movimiento real de precios y no contra datos estáticos. La lista de certificación del lede se ejecuta contra ese sandbox antes de emitir las claves de producción, de modo que los casos límite se detectan antes del lanzamiento y no en la primera semana de tráfico real. Los límites de tasa y los SLA se fijan en el contrato; los cotizamos cuando sabemos su concurrencia pico prevista, porque una API de checkout y un feed en vivo tienen tolerancias distintas.

Preguntas frecuentes

¿Podemos tomar solo las cuotas y hacer nuestra propia aceptación de apuestas?

Eso es una licencia de datos, no una API de casa de apuestas — un feed solo de cuotas, que varios de nuestros proveedores de origen también venden directamente, sin aceptación de apuestas, gestión de riesgo ni liquidación. La nuestra es lo contrario: la aceptación, el riesgo y la liquidación son el producto, y las cuotas son aquello contra lo que los aplicamos.

¿Podemos empezar con el iFrame y pasar a la API más adelante?

Sí, y en ese orden cuesta menos. El trabajo de monedero se conserva sin cambios, porque los dos patrones usan las mismas cuatro llamadas. Lo que construye en segundo lugar es el front-end de apuestas: los 36 a 67 días-ingeniero de la tabla de arriba. La cuenta, los jugadores y el historial de apuestas se quedan donde están; lo único que cambia es la interfaz que tienen delante.

¿Los límites los fijamos nosotros o ustedes?

Los dos, pero en un solo sentido. El motor de riesgo devuelve límites de importe por mercado, selección y jugador junto con el catálogo, y usted puede bajarlos. No puede subirlos por encima de los límites de exposición del libro, porque la responsabilidad recae en quien puso precio al mercado. Sus propias reglas — límites de depósito y de pérdidas, autoexclusión, restricciones de licencia — viajan con cada petición y se aplican en la aceptación, no se comprueban después.

¿Soportan fantasy o apuestas mutuas?

Apuestas mutuas sí, sobre el mismo catálogo. Fantasy no.

¿Y los contratos al estilo de los mercados de predicción?

Producto distinto, licencia distinta en la mayoría de los sitios; vea la plataforma de mercados de predicción.