Integraciones de API iGaming

Integración de API de Sportsbook: Cuotas, Apuestas y Liquidación

Que una cuota aparezca en una pantalla de apuestas deportivas no significa que la apuesta ya esté aceptada. El proveedor de información transmite eventos, mercados y precios; el servicio de apuestas decide si acepta el boleto; la billetera y el módulo de liquidación registran los movimientos posteriores. Una integración de API confiable conecta esas responsabilidades mediante identificadores persistentes, estados definidos, reintentos seguros y conciliación contable. Esta guía sigue el recorrido desde la cotización en vivo hasta el pago o la corrección de un resultado. Disponer de un feed no demuestra que el mismo proveedor acepte apuestas, mantenga fondos o tenga permisos para operar en cualquier territorio.

Tres componentes tecnológicos de apuestas deportivas conectados para cuotas, validación de boletos y registros de liquidación
La cuota que se muestra, el boleto aceptado y el asiento de liquidación requieren controles distintos.
Contenido

¿Qué abarca realmente la integración de una API sportsbook?

Normalmente intervienen tres dominios: partidos, mercados y cuotas; validación y aceptación de boletos; y resultados con movimientos de dinero. Puede proveerlos una sola empresa o varios socios. Antes de programar, se debe identificar cuál sistema tiene la autoridad de cada paso. [1]

Un mensaje del feed puede describir correctamente el estado de un mercado sin autorizar cambios de saldo. Tampoco el clic de un usuario crea por sí mismo una apuesta confirmada. La decisión debe venir del motor responsable y guardar el monto y la cuota aceptados.

¿Cómo identificar eventos, mercados y selecciones?

Asigna referencias internas estables a partido, mercado, selección y boleto, pero conserva el namespace y los códigos originales del proveedor. Un encuentro tiene muchos mercados; un mercado puede incluir varias líneas. El texto «Más de 2.5» no identifica por sí solo una selección sin el partido y los parámetros.

IDQué identificaPrecaución
Evento externoEncuentro en el feedConservar proveedor
MercadoTipo de apuesta y líneaGuardar especificadores
SelecciónResultado elegidoNo usar solo la etiqueta
Versión de cuotaRevisión del precioRechazar datos viejos
ID de boletoApuesta aceptadaNo cambiar en reintentos
ID de resultadoEvento de liquidaciónVincular al boleto

Versiona los mapeos y conserva los mensajes sin modificar. Un partido reprogramado o un mercado renombrado no debe apuntar un boleto existente a otro resultado. El proveedor diferencia mensajes de calendario, cuotas y liquidación. [1]

¿Qué ocurre si cambia la cuota o se suspende el mercado?

Entre mostrar el precio y recibir la orden puede haber una actualización o suspensión. El consumidor debe interpretar los estados, timestamps y versiones según el contrato del feed. Una cuota que quedó en la caché no vuelve disponible un mercado detenido. El mensaje odds_change documenta esos cambios. [2]

  • Conservar hora de origen y última versión aplicada por mercado.
  • Distinguir activo, suspendido, cerrado y desconocido según el proveedor.
  • Definir vigencia máxima de una cotización y validarla en el servidor.
  • No presentar una cuota en pantalla como aceptación garantizada.

La caché acelera la navegación, pero el endpoint de recepción revalida precio, elegibilidad, controles de exposición y saldo. Si hubo variación, debe devolver rechazo explícito o solicitar autorización para la nueva cuota.

¿Cuándo se convierte una solicitud en un boleto aceptado?

Una solicitud requiere cliente, marca, evento, mercado, selección, monto, precio solicitado y clave única de operación. El servicio autorizado comprueba estado, límites, disponibilidad de fondos y reglas del operador. Un feed de cuotas podría no tener funcionalidad de colocación de apuestas.

  1. Recibir selección, importe, cuota y clave de solicitud irrepetible.
  2. Revisar otra vez precio vigente, mercado, cuenta, límites y saldo.
  3. Pedir al motor de apuestas una decisión: aceptado, rechazado o pendiente.
  4. Guardar boleto y reserva solo una vez y devolver el mismo resultado ante reintentos.
Diagrama en tres etapas desde un feed de cuotas hasta la aceptación del boleto y su liquidación
La cotización informa la validación, pero la responsabilidad de pagar nace de una aceptación confirmada.

Un timeout después de enviar no implica rechazo: el socio pudo aceptar el boleto sin entregar respuesta. Primero consulta por la clave original. Las reglas HTTP no consideran seguro repetir automáticamente cualquier solicitud POST. [6]

¿Cómo ordenar y recuperar mensajes del feed?

Los feeds en vivo pueden duplicar mensajes, perder conectividad o entregar eventos fuera de tiempo. Registra el productor, la secuencia, un checkpoint persistente y el procedimiento de recuperación. Confirma los mensajes críticos solo cuando el estado se guardó de forma segura. El proveedor puede exigir recuperar por separado liquidaciones y cancelaciones. [5]

ProblemaAcciónComprobación
Mensaje repetidoIgnorar por claveSin efecto duplicado
Salto de secuenciaDetener uso riesgosoReplay o snapshot
Feed caídoBloquear precio viejoOrigen actualizado
Liquidación tardíaProcesar evento propioBoleto identificado
ReinicioContinuar desde checkpointSin doble pago

Recuperar cuotas recientes no garantiza que se hayan procesado todos los resultados financieros. Verifica alcance y retención de cada mecanismo de recovery y concilia por separado los boletos abiertos.

¿Cómo manejar resultados, anulaciones y reversiones?

La liquidación cierra un boleto según las reglas aplicables: ganancia, pérdida, devolución, resultado parcial u otro estado previsto. Las apuestas combinadas pueden requerir reglas adicionales. Unified Odds Feed publica mensajes bet_settlement y también rollback_bet_settlement para corregir liquidaciones previas. [3] [4]

  1. Guardar monto y cuota aceptados, parámetros del mercado y versión de las reglas.
  2. Aceptar resultados solo de orígenes válidos y para boletos existentes.
  3. Registrar el pago o devolución una vez con una clave única de liquidación.
  4. Corregir mediante un asiento inverso con motivo, sin borrar registros históricos.

Una reversión no es una ganancia adicional; tampoco todas las anulaciones tienen idéntica semántica. Respeta el tipo exacto del evento. En Gran Bretaña, cuando corresponda, las normas exigen resolver apuestas según reglas publicadas e informar a clientes afectados por ciertos errores. [7]

¿Cómo conciliar saldos, apuestas y pagos?

Usa referencias inmutables separadas para reserva de fondos, boleto aceptado, liquidación y corrección. Recibir una notificación no significa que el abono se realizó. Toda operación de dinero debe tener una clave única y compararse con el boleto y el resultado de la fuente.

Estado del boletoAcción en billeteraEvidencia
Solo cotizadoNo descontarSolicitud y vencimiento
AceptadoReservar monto una vezReferencia aceptada
RechazadoLiberar reservaMotivo del rechazo
LiquidadoPagar o cerrar pérdidaResultado y asiento
CorregidoRevertir o reembolsarID previo y motivo

La conciliación cruza montos exactos por boleto y moneda, reservas pendientes y asientos inversos. Una diferencia requiere investigación; nunca se debe generar una compensación automática desde un callback no comprobado.

¿Qué controles de latencia y riesgo importan en vivo?

Durante un partido, las cuotas y permisos para apostar cambian con rapidez. Un feed ágil mejora la visualización, pero no sustituye señales de suspensión, ventanas de confirmación, límites de riesgo o demoras de recepción aplicables. Diseña el comportamiento seguro para fallas y estados inciertos.

  • Medir por separado retraso de origen, antigüedad de cuota y respuesta de aceptación.
  • Rechazar o detener si el mercado o el servicio de riesgo no tienen estado confiable.
  • Guardar la cuota realmente aceptada, distinta de la última mostrada.
  • Probar variaciones rápidas, interrupciones del evento y envíos repetidos bajo carga.

El cliente debe distinguir claramente aceptación de rechazo. No hay una garantía universal de aceptación, tiempo de liquidación o límite de apuesta que sirva para todas las ligas y jurisdicciones. [2] [7]

¿Qué revisar de seguridad, regulación y monitoreo?

Protege las API con autenticación de servicios, autorización por cliente y marca, gestión de secretos, cifrado y auditoría. Leer cotizaciones no debe otorgar permiso para aceptar apuestas o mover dinero. Valida cada ID de boleto frente al dueño de la operación.

  • Alertar sobre cuotas viejas, huecos en el feed e intentos en mercados suspendidos.
  • Cruzar tickets pendientes, aceptados y liquidados contra reportes permitidos.
  • Simular POST duplicados, timeouts, callbacks falsos y reversiones desordenadas.
  • Documentar licencias, protección de datos y reclamos por cada país de operación.

Separa paneles de disponibilidad técnica y de exactitud contable. Procesar todos los eventos no basta si quedan apuestas sin resultado, pagos duplicados u obligaciones financieras sin conciliar.

¿Qué lista de verificación usar antes de lanzar la API?

En un ambiente de pruebas recorre todo el ciclo: cambio de cuota, suspensión, rechazo, aceptación, resultado demorado, devolución, rollback, recuperación del feed y discrepancia de saldo. Cada caso debe vincular el evento original con el asiento final.

  1. Validar IDs, alcance contractual, precisión de cuota y vigencia del precio.
  2. Probar idempotencia, timeouts, rechazo y liberación de fondos reservados.
  3. Demostrar liquidación, anulación, reversión y conciliación del libro.
  4. Reunir aprobaciones operativas, técnicas y legales antes de activar producción.

Una integración lista para operar no solo muestra mercados y entrega un número de boleto. También permite justificar cada decisión de aceptación, cada resultado y cada corrección financiera con pruebas auditables.

Fuentes y recursos adicionales

Visor de diagramas