¿Cómo crear un bot que envíe notificaciones sobre goles, córners y tarjetas?

¿Qué es una API de eventos deportivos y cómo usarla para obtener goles, córners y tarjetas?

Una API de eventos deportivos es una interfaz de programación que proporciona acceso a datos sobre partidos, equipos y detalles del juego en un formato legible por máquina. En el caso del fútbol, esto incluye no solo el marcador, sino también una lista de eventos en vivo: goles, tarjetas amarillas y rojas, córners, tiros libres y otras acciones en el campo. En la plataforma api-sport.pro esos datos están disponibles a través de una API REST unificada para diferentes deportes, con cada deporte utilizando su propio slug (por ejemplo, fútbol para el fútbol), lo que simplifica la integración y escalado del proyecto.

Técnicamente, el acceso a la información se construye en torno a un conjunto de endpoints. Por ejemplo, el método /v2/fútbol/partidos devuelve una lista de partidos con el marcador actual, minuto del juego (minutoDelPartidoActual) y estadísticas detalladas, mientras que el método /v2/fútbol/partidos/{matchId}/eventos devuelve una lista cronológica de eventos, donde cada evento se describe por tipo (gol or tarjeta), tiempo y participantes. Son estas estructuras las que permiten al bot enterarse en tiempo real de un nuevo gol o tarjeta, y luego enviar una notificación instantánea al usuario. Para córners y otras métricas, es conveniente usar el campo estadísticasDelPartido, donde hay un valor de la métrica para cada equipo.

La principal ventaja de este enfoque es que la lógica del bot se vuelve lo más simple posible: llama periódicamente a la API, recibe un JSON estrictamente estructurado, analiza los campos necesarios y decide si generar una notificación. Al mismo tiempo, la misma API se puede utilizar fácilmente tanto para alertas simples (solo goles) como para escenarios avanzados: notificaciones para el N-ésimo córner, un cierto número de tarjetas o una combinación de eventos. En el futuro, la plataforma api-sport.pro está desarrollando no solo REST sino también canales WebSocket y herramientas de IA, lo que permitirá construir sistemas de bots aún más rápidos e inteligentes para apuestas, análisis y proyectos de medios.

Visión general de las APIs de fútbol populares para notificaciones de goles y estadísticas de partidos.

El mercado de APIs de fútbol está saturado hoy en día, pero no todos los servicios son igualmente convenientes para las tareas de notificaciones sobre goles, tarjetas y córners. Tres parámetros son críticos para el bot: la profundidad de los datos en vivo, la latencia de actualización y la estabilidad operativa. En api-sport.pro la información en vivo está disponible a través del campo. eventosEnVivo en el objeto de coincidencia (puntos finales /v2/fútbol/partidos и /v2/fútbol/partidos/{matchId}) y a través de un método separado /v2/fútbol/partidos/{matchId}/eventos, que permite obtener rápidamente eventos frescos así como restaurar la cronología completa del partido si es necesario.

A continuación se muestra un ejemplo de una solicitud que se puede utilizar en el bot para obtener todos los partidos actuales en progreso y sus eventos en un ciclo de sondeo. El servidor API se utiliza como el host https://api.api-sport.ru, la autorización se realiza a través del encabezado Autorización con tu clave de la cuenta personal:

curl -X GET "https://api.api-sport.ru/v2/football/matches?status=inprogress" \
  -H "Authorization: YOUR_API_KEY"

La respuesta contiene un array partidos, en el que para cada partido hay campos puntajeLocal, puntajeVisitante, minutoDelPartidoActual, un array eventosEnVivo y un bloque estadísticasDelPartido. Esta combinación permite que el bot no solo conozca el hecho de un gol, sino también evaluar el contexto: cuántos córners ya se han tomado, cuántas tarjetas se han mostrado, cómo está cambiando la dinámica. Si a esto le agregas el campo oddsBase Con coeficientes de casas de apuestas, se vuelve posible construir bots para análisis de apuestas y comparación de líneas. Debido a la estructura de datos unificada en diferentes deportes, la API de api-sport.pro es fácilmente escalable: puedes agregar rápidamente hockey, baloncesto o esports al bot de fútbol sin reescribir la arquitectura.

Cómo elegir y conectar una API de eventos deportivos: registro, claves, límites.

Antes de lanzar el bot, es importante elegir adecuadamente un proveedor de API deportiva y configurar correctamente la conexión. Primero que nada, evalúa qué torneos y deportes necesitas, y si la API tiene las ligas específicas para las que se planean notificaciones. A continuación, presta atención a la disponibilidad de eventos detallados: no todos los servicios tienen tipos separados para goles, tarjetas o sustituciones, así como estadísticas detalladas sobre córners. api-sport.pro Todos estos datos están disponibles a través de la especificación OpenAPI descrita abiertamente, por lo que el desarrollador entiende la estructura de las respuestas de antemano y puede planificar con precisión la lógica del bot. Además, considera la disponibilidad de datos sobre coeficientes de casas de apuestas si se planea la integración con apuestas.

Conectarse a la API se reduce a obtener una clave individual y agregarla a cada solicitud. En la plataforma api-sport.ru, esto se hace a través de tu cuenta personal: después de registrarte, recibes una clave API y la especificas en el encabezado Autorización. Luego, cualquier cliente HTTP (curl, axios, fetch, requests, etc.) podrá acceder a los métodos de la API. El ejemplo más simple en JavaScript podría verse así:

fetch('https://api.api-sport.ru/v2/football/matches?status=inprogress', {
  headers: { 'Authorization': 'YOUR_API_KEY' }
})
  .then(res => res.json())
  .then(data => console.log(data.matches));

Estudia las limitaciones sobre la frecuencia de solicitudes y el tamaño de la muestra por separado. Cualquier API deportiva tiene límites básicos sobre el número de solicitudes por unidad de tiempo, y un bot con sondeo frecuente debe trabajar correctamente con ellos. Por lo general, un intervalo de sondeo razonable (por ejemplo, 5-10 segundos para partidos clave) y almacenar en caché datos donde la alta frecuencia no es crítica es suficiente. A medida que aumenta la carga, puedes optimizar la lógica: usar filtros por estado del partido, torneos o equipos, solicitar solo los campos verdaderamente necesarios, y en el futuro, cambiar a WebSocket, que se planea lanzar en api-sport.ru y permitirá recibir actualizaciones de eventos sin sondeo REST constante.

Cómo obtener datos sobre goles, córners y tarjetas a través de la API: estructura de solicitud y respuesta.

Para que el bot responda correctamente a goles, córners y tarjetas, es necesario entender dónde exactamente en las respuestas de la API se encuentra esta información. En la sección de fútbol, /v2/fútbol/ las principales fuentes son los métodos /matches, /matches/{matchId} и /matches/{matchId}/events. En el objeto de partido, el campo eventosEnVivo contiene un array de eventos en tiempo real. Cada elemento se describe por un tipo (tipo: gol, tarjeta, etc.), el tiempo del evento en minutos (tiempo), el equipo (equipo: local/visitante) y, si está disponible, el jugador. Basado en estos campos, es fácil determinar qué exactamente sucedió y qué texto de notificación necesita ser generado para el usuario.

Los córners y tarjetas se leen convenientemente del bloque estadísticasDelPartido, que viene junto con el partido. Contiene un array de períodos (por ejemplo, TODOS, 1RO, 2DO), dentro de los cuales hay grupos de estadísticas y elementos con claves como tiros de esquina or tarjetas amarillas. Esto permite al bot rastrear métricas acumulativas: por ejemplo, enviar una señal tan pronto como el equipo tome el quinto córner o reciba la tercera tarjeta amarilla. A continuación se muestra un fragmento simplificado de la respuesta JSON para ilustrar la estructura:

{
«id»: 14570728,
«homeScore»: { «current»: 1 },
«awayScore»: { «current»: 0 },
«liveEvents»: [
{
«time»: 23,
«type»: «gol»,
«team»: «local»,
«homeScore»: 1,
«awayScore»: 0
},
{
«time»: 30,
«type»: «tarjeta»,
«team»: «visitante»,
«razón»: «Tarjeta amarilla»
}
],
«estadísticasDelPartido»: [
{
«período»: «TODOS»,
«grupos»: [
{
«nombreDelGrupo»: «Resumen del partido»,
«elementosDeEstadísticas»: [
{ «clave»: «tirosDeEsquina», «valorLocal»: 4, «valorVisitante»: 2 },
{ «clave»: «tarjetasAmarillas», «valorLocal»: 1, «valorVisitante»: 2 }
]
}
]
}
]
}

En el lado del bot, es suficiente recordar el estado anterior de las estadísticas del partido y compararlo con la nueva respuesta de la API. Si el indicador de córners o tarjetas ha aumentado, o ha aparecido un nuevo elemento en el array eventosEnVivo de tipo gol, se forma y envía una notificación. Este enfoque funciona igualmente bien para alertas simples como «¡Gol! 1:0» y para desencadenantes más complejos relacionados con apuestas y análisis en vivo, especialmente considerando que la API api-sport.pro proporciona además las cuotas básicas de las casas de apuestas a través del campo oddsBase.

Cómo crear un bot de Telegram con notificaciones sobre goles y tarjetas basado en una API deportiva.

El esquema práctico del bot de Telegram funciona así: el usuario inicia el bot, selecciona los torneos o equipos de interés, el bot guarda estas configuraciones y luego consulta periódicamente la API deportiva para verificar nuevos eventos. Cuando aparece un gol o una tarjeta, el bot envía un mensaje al usuario en Telegram. Es conveniente usar la API REST https://api.api-sport.ru/v2/football con filtrado por estado del partido (en progreso) y los torneos o equipos requeridos. Así, la lógica principal se transfiere a un único bucle en segundo plano que consulta la API y actualiza el estado de los partidos rastreados.

A continuación se muestra un ejemplo de código Python simplificado que ilustra la idea básica: una solicitud a la API de eventos deportivos y el envío de una notificación a través de la API del Bot de Telegram. Por brevedad, el manejo de errores y el almacenamiento de estado no se muestran aquí, pero el principio sigue siendo el mismo en cualquier implementación de producción:

import requests
API_KEY = 'YOUR_API_KEY'
TELEGRAM_TOKEN = 'TELEGRAM_BOT_TOKEN'
CHAT_ID = 'USER_CHAT_ID'
base_url = 'https://api.api-sport.ru/v2/football/matches'
resp = requests.get(base_url, params={
    'status': 'inprogress'
}, headers={'Authorization': API_KEY})
matches = resp.json().get('matches', [])
for match in matches:
    for event in match.get('liveEvents', []):
        if event['type'] == 'goal':
            text = f"Гол! Счет {event['homeScore']}:{event['awayScore']} на {event['time']} минуте"
            requests.get(f"https://api.telegram.org/bot{TELEGRAM_TOKEN}/sendMessage", params={
                'chat_id': CHAT_ID,
                'text': text
            })

En la práctica, el bot debe guardar los IDs de los eventos ya procesados para evitar enviar notificaciones duplicadas y mantener las configuraciones del usuario: qué partidos rastrear, qué tipos de eventos son de interés. Todo esto se implementa en su servidor o función en la nube, mientras que la API de eventos deportivos de api-sport.ru proporciona una fuente de datos estable y predecible. A medida que el servicio evoluciona, habrá una oportunidad de utilizar conexiones WebSocket y funciones de IA para análisis predictivos, haciendo que tales bots sean aún más rápidos y precisos sin complicar la lógica de su lado.

Configuración de filtros y frecuencia de notificación para el bot de partidos de fútbol.

Para evitar que el bot abrume al usuario sin perder eventos importantes, es necesario configurar adecuadamente los filtros y la frecuencia de consulta de la API. En las solicitudes a /v2/fútbol/partidos es recomendable usar parámetros estado=enprogreso, torneo_id, equipo_id и categoría_ids. De esta manera, el bot recibirá solo aquellos juegos que realmente están sucediendo en ese momento y que son genuinamente interesantes para la audiencia del usuario. Por ejemplo, para rastrear solo la Liga de Campeones y la Premier League inglesa, es suficiente pasar sus IDs separados por comas en el parámetro. torneo_id, y para la personalización — limitar a coincidencias de un equipo específico a través de equipo_id.

La consulta a la API puede organizarse por temporizador o a través de una tarea programada. El intervalo depende de los requisitos del proyecto para la velocidad de respuesta. Para la mayoría de los bots, 5–15 segundos es suficiente, especialmente si solo se procesan los partidos clave. Al mismo tiempo, es importante no olvidar los límites: con un gran número de usuarios y torneos, es mejor separar la lógica en varios hilos y almacenar en caché los datos donde un pequeño retraso es aceptable (por ejemplo, estadísticas de córner cada 30 segundos). Para aumentar la precisión, se pueden combinar dos niveles: consulta frecuente de una lista limitada de partidos «calientes» y actualizaciones menos frecuentes de la lista general de encuentros.

Los filtros a nivel de lógica de negocio permiten una gestión flexible de la carga y la experiencia del usuario. El usuario puede elegir qué eventos le interesan: solo goles, goles y tarjetas, todos los cambios estadísticos clave. El bot guarda estas configuraciones y, al recibir una respuesta de la API, la compara con el perfil del usuario. Por ejemplo, si solo se habilitan los córners, el bot analiza el bloque estadísticasDelPartido y envía una notificación solo cuando se alcanza el umbral especificado. Este enfoque hace que trabajar con la API sea eficiente: un número mínimo de solicitudes, notificaciones útiles máximas y alta lealtad de la audiencia a su producto.

Errores típicos y limitaciones al trabajar con APIs de eventos deportivos y cómo superarlos.

Al desarrollar un bot basado en una API deportiva, a menudo ocurren los mismos errores. El más común es la autorización incorrecta: falta de encabezado Autorización o uso de una clave expirada. Como resultado, el servidor devuelve el estado 401, y el bot «permanece en silencio». Este problema se resuelve con una simple verificación de configuración al inicio de la aplicación y almacenamiento centralizado de la clave obtenida a través de tu cuenta personal. El segundo error común es el uso incorrecto de los parámetros de filtrado: incorrecto sportSlug (por ejemplo, un error tipográfico en lugar de fútbol), IDs de torneo o equipo incorrectos. En tales casos, es importante registrar solicitudes y respuestas para ver rápidamente las fuentes de problemas.

Otro escenario típico es exceder los límites de solicitudes. Si el bot intenta consultar la API con demasiada frecuencia o sin filtros, conduce a errores y retrasos. Para evitar esto, incorpore almacenamiento en caché, agregación de solicitudes y intervalos de consulta razonables en la arquitectura. Por ejemplo, en lugar de solicitar detalles por separado para cada partido cada segundo, puede obtener la lista de partidos una vez a través de /v2/fútbol/partidos?estado=enprogreso, y luego actualizar solo los juegos verdaderamente importantes caso por caso. En el futuro, la transición a WebSocket, que está planeada en la plataforma api-sport.ru, permitirá la eliminación completa de las consultas «innecesarias» y la recepción de eventos a través de suscripción.

Otro aspecto importante es el manejo correcto de la estructura de respuesta. A veces, los desarrolladores se atan rígidamente al orden de los elementos en el array o no manejan nuevos campos que aparecen a medida que la API evoluciona. La estrategia correcta es centrarse en las claves descritas en la especificación OpenAPI (por ejemplo, tipo, tiempo, estadísticasDelPartido, oddsBase), y anticipar que pueden aparecer datos adicionales en la respuesta. Esto hace que el bot sea resistente a las actualizaciones de la plataforma y permite la integración fluida de nuevas funciones, como estadísticas para otros deportes, integración con APIs de cuotas de apuestas o servicios de IA basados en datos. api-sport.pro.