¿Cómo crear un bot con suscripciones a equipos, ligas y eventos?

¿Qué es una API de eventos deportivos y qué datos se pueden obtener?

Una API de eventos deportivos es una interfaz de programación que permite a tu bot recibir datos actualizados sobre partidos, equipos y torneos en un formato legible por máquina (generalmente JSON). A través de puntos finales unificados, puedes recuperar horarios de juegos, resultados en vivo, estadísticas, alineaciones, eventos de partidos e incluso cuotas del mercado de apuestas. Esto permite que el bot esté «conectado» a un feed deportivo global y responda automáticamente a cambios en tiempo real.

El servicio por el API de eventos deportivos api-sport.ru cubre fútbol, hockey, baloncesto, tenis, tenis de mesa, deportes electrónicos y otras disciplinas que se añaden regularmente. Para cada deporte, están disponibles categorías (países y ligas), torneos y sus temporadas, equipos, jugadores, así como partidos con estadísticas ampliadas: campo minutoDelPartidoActual, un array eventosEnVivo con goles, tarjetas y sustituciones, bloque estadísticasDelPartido y datos altamente detallados sobre el torneo. Además, puedes obtener un conjunto oddsBase con coeficientes de casas de apuestas y momentosDestacados — enlaces a reseñas en video.

Para un bot con suscripciones, tales datos son especialmente valiosos. Puedes almacenar solo los ID de equipos y torneos en la base de datos, mientras que extraes dinámicamente toda la información «pesada» sobre horarios, puntajes y estadísticas a través de la API. En un futuro cercano, la plataforma planea lanzar streaming WebSocket y herramientas de IA, lo que permitirá notificaciones aún más «inteligentes» (por ejemplo, sobre momentos peligrosos o cambios en la probabilidad de resultados durante el partido) sin análisis manual.

Ejemplo de obtención de una lista de partidos de fútbol de hoy

const apiKey = 'ВАШ_API_КЛЮЧ';
async function getTodayFootballMatches() {
  const url = 'https://api.api-sport.ru/v2/football/matches';
  const res = await fetch(url, {
    headers: {
      Authorization: apiKey
    }
  });
  const data = await res.json();
  console.log('Всего матчей:', data.totalMatches);
  console.log('Пример матча:', data.matches[0]);
}
getTodayFootballMatches().catch(console.error);

Cómo elegir una API de eventos deportivos para un bot: criterios y comparación

Al elegir un proveedor de datos para un bot de suscripción, es importante no solo mirar el número de deportes, sino también la profundidad y estructura de la información. La API debe devolver entidades bien normalizadas: deportes, categorías, torneos, temporadas, equipos, jugadores y partidos con formatos de campo uniformes. Un criterio importante es la disponibilidad de filtros convenientes, como equipo_id, torneo_id, estado, fecha, así como la capacidad de pasar listas de ID separadas por comas. Esto te permite construir solicitudes estrictamente para las suscripciones de tus usuarios sin sobrecargar el sistema con tráfico innecesario.

También es importante considerar la puntualidad de las actualizaciones de datos y la estabilidad de operación. Para eventos en vivo, la latencia y la precisión de los campos son críticas: el minuto actual del partido, eventos en vivo, puntajes por mitades y el resultado final. Cuanto más frecuentemente se actualice el feed y mejor se documenten los cambios (registro de cambios, versiones de API), más fácil será mantener el bot operativo. Los límites predecibles en las solicitudes, precios claros y la disponibilidad de un período de prueba también son importantes para que puedas ejecutar escenarios de suscripción en vivo antes del lanzamiento del producto.

Una ventaja adicional es la presencia de funcionalidad del proveedor además de los datos «en bruto». En el caso de api-sport.ru, esto incluye, por ejemplo, coeficientes de casas de apuestas en el bloque oddsBase, torneos recomendados a través de torneosPredeterminados, así como módulos de WebSocket y IA planificados. Tal pila permite la implementación no solo de notificaciones básicas como «partido iniciado / terminado» sino también de mecánicas avanzadas: señales para cambios en coeficientes, alertas para eventos específicos del partido y selecciones de eventos personalizadas para cada usuario.

Cómo obtener una clave API y configurar solicitudes para eventos deportivos

Para que el bot acceda a los puntos finales de los eventos deportivos, se debe obtener una clave de acceso personal. Para ello, basta con registrarse en tu cuenta personal en api-sport.ru, elegir una tarifa adecuada y generar una clave API. La clave es una cadena que se pasa en el encabezado HTTP Autorización con cada solicitud. Se recomienda almacenarla solo en el lado del servidor (en variables de entorno o en un almacenamiento seguro), sin incrustarla directamente en el código del frontend o en el bot del cliente.

Una solicitud básica a la API se ve como un GET HTTP regular con el tipo de deporte especificado en la ruta (sportSlug) y los parámetros de filtrado necesarios. Por ejemplo, para obtener partidos de un equipo de fútbol por su ID, se utiliza el punto final /v2/fútbol/partidos con el parámetro equipo_id. En la respuesta, recibirás un objeto con el número total de partidos y un array de entidades detalladas partido, donde ya están presentes el estado, la fecha, el marcador, las estadísticas, los eventos en vivo y las cuotas.

En la práctica, las solicitudes a la API de eventos deportivos están convenientemente encapsuladas en un módulo separado o clase de servicio. De esta manera, puedes manejar errores de forma centralizada (por ejemplo, acceso no autorizado o parámetros incorrectos), implementar caché y registrar la carga. Esto es especialmente importante para un bot de suscripción, donde una operación lógica (enviar notificaciones a todos los suscriptores del equipo) puede generar docenas o cientos de llamadas a la API.

Ejemplo de una solicitud para partidos de equipo por ID (JavaScript)

const apiKey = 'ВАШ_API_КЛЮЧ';
async function getTeamMatches(teamId) {
  const url = `https://api.api-sport.ru/v2/football/matches?team_id=${teamId}`;
  const res = await fetch(url, {
    headers: {
      Authorization: apiKey
    }
  });
  if (!res.ok) {
    throw new Error(`Ошибка API: ${res.status}`);
  }
  const data = await res.json();
  return data.matches;
}

Cómo crear un bot con suscripciones a equipos y ligas a través de una API de eventos deportivos

La arquitectura del bot de suscripción se construye en torno a la relación «usuario – objeto de suscripción – fuente de datos». A nivel de interfaz, permites que el usuario seleccione los equipos o torneos (ligas) de interés, y a nivel de backend, guardas sus IDs de la API en la base de datos. Por ejemplo, para el fútbol, esto podría ser el ID del equipo de la entidad Equipo y el ID del torneo de la entidad Torneo. Durante el procesamiento de eventos subsiguientes, el bot simplemente recopila todos los IDs únicos de las suscripciones y forma solicitudes a ellos a través del punto final /v2/{sportSlug}/partidos.

Para suscribirse a equipos, puedes usar el filtro equipo_id, y para ligas — torneo_id (se admite una lista de IDs separados por comas). Este enfoque permite recibir partidos para varios objetos en una sola solicitud, reduciendo significativamente la carga y acelerando el envío de notificaciones. La lógica del bot se reduce a sondear regularmente la API: tomas todas las suscripciones, formas solicitudes por tipos de deportes y luego distribuyes los partidos recibidos a los usuarios que están suscritos a los equipos o torneos correspondientes.

Es importante prever el tipo de suscripción en el modelo de datos: «equipo», «torneo», y posiblemente más tarde «jugador» o un evento de partido separado. En el lado del bot, solo se almacena la combinación de tipo e ID, mientras que toda la otra información (nombre del equipo, emblema, liga actual, ronda) se extrae dinámicamente de la API. Esto hace que el sistema sea flexible: cuando cambia la estructura del torneo o un equipo se mueve a otra división, no tendrás que migrar tus datos: solo continúa usando los mismos identificadores.

Ejemplo de obtención de partidos basados en suscripciones a equipos y torneos

const apiKey = 'ВАШ_API_КЛЮЧ';
async function getMatchesBySubscriptions(teamIds, tournamentIds) {
  const params = new URLSearchParams();
  if (teamIds.length) {
    // для одной команды можно вызывать запрос отдельно,
    // здесь для простоты показываем объединение
    params.set('team_id', teamIds[0]);
  }
  if (tournamentIds.length) {
    params.set('tournament_id', tournamentIds.join(','));
  }
  // Можно добавить фильтр по статусу, например, "notstarted" или "inprogress"
  const url = `https://api.api-sport.ru/v2/football/matches?${params.toString()}`;
  const res = await fetch(url, {
    headers: { Authorization: apiKey }
  });
  const data = await res.json();
  return data.matches;
}

Cómo configurar notificaciones sobre partidos y resultados a través de un bot basado en la API

Después de implementar la estructura de suscripción, el siguiente paso es configurar los disparadores de notificación. En la práctica, se utiliza el sondeo periódico de la API según un horario (cron), o, en el futuro, conexiones WebSocket, que se planean en la infraestructura pronto. api-sport.pro. Para la encuesta, puedes solicitar partidos con el estado deseado: no comenzado para juegos próximos, en progreso para notificaciones en vivo, y completado para resultados finales. El endpoint /v2/{sportSlug}/partidos te permite combinar filtros por fecha, torneos, equipos y estado.

Un escenario típico: según el calendario, solicitas partidos para la próxima hora y envías a los suscriptores un recordatorio «el partido comenzará pronto.» Luego, con un intervalo más corto, sondeas partidos con el estado en progreso y rastreas cambios en el marcador, el minuto actual, y eventosEnVivo. Con cada nuevo evento (gol, tarjeta roja, penalti), formas el texto de la notificación y lo entregas a los usuarios suscritos al equipo o torneo correspondiente. Después de que el partido se complete, por estado completado puedes enviar el resultado final con estadísticas clave.

Si tu bot está enfocado en apuestas, puedes analizar adicionalmente el conjunto. oddsBase para partidos seleccionados. Esto abre la posibilidad de enviar señales sobre cambios en las cuotas, cierres de mercado o la aparición de nuevas líneas. En el futuro, el enfoque de WebSocket permitirá abandonar el sondeo frecuente de la API y recibir eventos directamente a medida que ocurren, mientras que los módulos de IA ayudarán a resaltar automáticamente los momentos «importantes» y crear notificaciones más personalizadas para cada usuario.

Ejemplo de verificación de partidos en vivo y envío de notificaciones

const apiKey = 'ВАШ_API_КЛЮЧ';
async function getLiveMatchesForTeam(teamId) {
  const url = `https://api.api-sport.ru/v2/football/matches?team_id=${teamId}&status=inprogress`;
  const res = await fetch(url, {
    headers: { Authorization: apiKey }
  });
  const data = await res.json();
  return data.matches;
}
async function processLiveNotifications(subscriptions) {
  for (const sub of subscriptions) {
    const matches = await getLiveMatchesForTeam(sub.teamId);
    matches.forEach(match => {
      const score = `${match.homeTeam.name} ${match.homeScore.current} : ${match.awayScore.current} ${match.awayTeam.name}`;
      // Здесь вызываем отправку сообщения в выбранный мессенджер
      console.log(`Отправляем пользователю ${sub.userId}: ${score}`);
    });
  }
}

Límites, costos y restricciones de la API de eventos deportivos para un bot de suscripción

Al diseñar un bot con suscripciones, es importante considerar los límites y costos de uso de la API por adelantado. Típicamente, las tarifas dependen del número de solicitudes por día o mes, el conjunto de deportes soportados y el acceso a datos adicionales (estadísticas en vivo, cuotas de casas de apuestas, reseñas en video). Encontrarás condiciones específicas y limitaciones actuales para la API de Eventos Deportivos en el sitio web api-sport.pro y en la cuenta personal, por lo que tiene sentido compararlas con la carga esperada: cuántos suscriptores activos tendrás, con qué frecuencia planeas actualizar datos en vivo y para cuántos deportes.

Para evitar alcanzar los límites demasiado rápido, debes optimizar el esquema de solicitudes. Primero, combina varios IDs en una sola llamada donde sea posible (por ejemplo, torneo_id como una lista separada por comas). Segundo, almacena en caché datos relativamente constantes: no es necesario solicitar la lista de deportes, categorías, torneos y temporadas en cada inicio del bot. Tercero, diferencia la frecuencia de sondeo: los partidos en vivo pueden solicitarse con más frecuencia, mientras que la historia y los resultados de días anteriores deben solicitarse con mucha menos frecuencia.

Otro tema importante es el manejo de errores y el exceso de límites. Un bot correctamente configurado debería ser capaz de reconocer las respuestas del servidor sobre acceso no autorizado o parámetros incorrectos y no intentar ciegamente repetir las mismas solicitudes. Para escenarios con alta carga, la aparición planificada de la interfaz WebSocket es especialmente útil: al recibir actualizaciones de eventos a través de suscripciones para partidos o torneos específicos, puedes reducir significativamente el número de llamadas HTTP y, en consecuencia, disminuir costos y carga del sistema.