API de feed de cuotas: del snapshot a la liquidación

Una pantalla de sportsbook parece estática: una lista de partidos y una columna de cuotas. Por debajo, un feed de cuotas es un flujo de miles de pequeños cambios, y el trabajo del operador es aplicarlos todos en el orden correcto. Esta guía recorre ese flujo desde la primera petición hasta la apuesta liquidada.

1. El modelo de datos

Casi todos los feeds usan la misma jerarquía:

• Deporte: fútbol, tenis, esports.
• Torneo o liga: Premier League, ATP Tokio, Worlds de League of Legends.
• Evento: un partido, con hora de inicio y participantes.
• Mercado: una pregunta sobre el evento, como 1X2, más/menos de 2,5 goles o hándicap por mapa.
• Resultado: una respuesta, con cuota y estado (activo, suspendido, liquidado).

Cada elemento tiene un identificador estable. La mayoría de errores de integración vienen de tratar los nombres como identificadores: los nombres de los equipos cambian de grafía, los ID no.

2. Primero el snapshot, luego los deltas

Al arrancar, el cliente pide un snapshot: el estado completo del momento. A partir de ahí recibe deltas, mensajes pequeños que dicen «esta cuota se ha movido», «este mercado está suspendido», «este evento ha empezado».

Los buenos feeds numeran sus deltas. Nocturn Sport, por ejemplo, describe su feed como un snapshot completo más deltas con versión. Si el cliente tiene la versión N y recibe la N+2, sabe que se perdió un mensaje y recarga en lugar de mostrar una cuota caducada. Los feeds sin versión obligan al cliente a adivinar, y adivinando es como una casa de apuestas acaba ofreciendo las cuotas de ayer.

3. Push y pull

En fútbol en vivo una cuota puede cambiar varias veces por minuto, así que los feeds en vivo suelen enviar (push) los mensajes por una conexión persistente. Las cuotas prepartido se mueven tan despacio que consultarlas (pull) por HTTP cada pocos segundos suele bastar. Muchos operadores usan ambos: pull para el catálogo prepartido y push para el directo.

4. Suspensiones

Una suspensión es el feed diciendo «no aceptes apuestas en esto ahora». Los desencadenantes incluyen un gol, un penalti, una rotura de servicio, el final de un mapa o que el proveedor pierda su propia fuente de datos. El cliente debe aplicar las suspensiones más rápido que cualquier otra cosa; aceptar una cuota en los segundos posteriores a un gol es la forma clásica de perder dinero.

Los mercados prepartido también cierran antes del inicio. Nocturn Sport, por ejemplo, los cierra un minuto antes de que empiece el evento.

5. Colocar la apuesta

Si la API va más allá de publicar cuotas, la colocación de apuestas sigue un patrón:

1. El cliente envía la selección, la cuota que mostró y el importe, con un ID de petición único.
2. El servidor comprueba que la cuota sigue siendo válida y el mercado está abierto.
3. Acepta, rechaza u ofrece una cuota nueva.
4. Si falla la red, el cliente reenvía con el mismo ID de petición y el servidor devuelve la respuesta original en lugar de crear una segunda apuesta.

Ese último paso, la idempotencia, protege tanto el saldo del jugador como las cuentas del operador.

6. Liquidación

Cuando termina el evento, el feed publica los resultados de cada opción: ganada, perdida, nula, o mitad ganada y mitad perdida en líneas divididas como los hándicaps asiáticos. La plataforma liquida cada apuesta con esos datos. Hay correcciones: un resultado puede modificarse tras una revisión, así que el proceso de liquidación debe poder volver a liquidar limpiamente.

7. Qué probar antes de salir en vivo

• Cortar la conexión a mitad de partido y comprobar la recuperación.
• Reenviar un delta fuera de orden y comprobar que el cliente lo detecta.
• Colocar la misma apuesta dos veces con un mismo ID de petición.
• Liquidar una combinada con una selección anulada.

Un feed que supera esas cuatro pruebas está listo para un sábado por la tarde.