Manual de la API de Pelota Pro Liga

Consulta el calendario de partidos y las plantillas de los equipos desde tu aplicación.

Introducción

La API es de solo lectura, devuelve JSON (UTF-8) y todas las rutas cuelgan de esta URL base:

https://datosapi.pelotaproliga.com/api/v1

Para usarla necesitas una clave de API. Te la facilita el administrador desde el panel de administración, que también define los límites de uso de tu aplicación.

• Fechas en formato AAAA-MM-DD y horas en HH:MM (hora de la península, Europa/Madrid).
• Los campos sin dato se devuelven como null.
• Puedes probar la conexión con GET /equipos: si responde 200, la URL y la clave son correctas.

Autenticación

Envía la clave en todas las peticiones, con una de estas dos cabeceras:

X-API-Key: bk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Authorization: Bearer bk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Límites de uso

Cada clave tiene un límite de peticiones por minuto, por día y por mes (según su plan). Con cada respuesta se envían estas cabeceras para que sepas cuánto te queda:

Solo aparecen las cabeceras de los límites que tu plan tiene definidos. Si los superas, la API responde 429 con la cabecera Retry-After (segundos que debes esperar). Las peticiones rechazadas no consumen cupo.

Errores

Los errores devuelven siempre este formato:

{
  "error": {
    "code": "unauthenticated",
    "message": "API key ausente o no válida."
  }
}

Calendario de partidos recurso: partidos

Listado de partidos

GET/partidos

Devuelve los partidos ordenados por fecha y hora: los ya disputados con su resultado y los próximos con la información de venta de entradas.

curl -H "X-API-Key: TU_CLAVE" \
  "https://datosapi.pelotaproliga.com/api/v1/partidos?desde=2026-09-01&hasta=2026-09-30&competicion=Masters"

Ejemplo de respuesta (partido ya disputado):

{
  "data": [
    {
      "id": "47208-0-16",
      "fecha": "2026-09-05",
      "hora": null,
      "estado": "finalizado",
      "fronton": { "id": 2345, "nombre": "Santi Brouard", "municipio": "Bilbao", "provincia": "Bizkaia" },
      "competicion": { "id": 47208, "nombre": "[2026] Masters CaixaBank Serie A", "categoria": "Masters CaixaBank Serie A" },
      "fase": "liga_de_clasificacion",
      "titulo": null,
      "tipo": null,
      "orden": "p2",
      "equipo_rojo": {
        "pelotaris": [
          { "id": 2250, "nombre": "EZKURDIA", "alias": "Ezkurdia", "equipo": "aspe", "asiste": true },
          { "id": 2281, "nombre": "ALBISU", "alias": "ALBISU", "equipo": "baiko", "asiste": true }
        ],
        "tantos": 22
      },
      "equipo_azul": { "pelotaris": [ ... ], "tantos": 14 },
      "resultado": { "ganador": "rojo", "tantos_rojo": 22, "tantos_azul": 14 },
      "entradas": null
    }
  ],
  "meta": { "desde": "2026-09-01", "hasta": "2026-09-30", "total": 57, "page": 1, "per_page": 50, "last_page": 2 }
}

Los valores de los ejemplos (identificadores, nombres…) son ilustrativos; la estructura es la real.

Campos devueltos

Estados

Un partido

GET/partidos/{id}

Devuelve un único partido dentro de data, con los mismos campos que el listado (p. ej. /partidos/47208-0-16). Si no existe, responde 404.

Plantillas de equipos recurso: plantillas

Equipos

GET/equipos

{
  "data": [
    { "slug": "baiko", "nombre": "Baiko", "pelotaris": 22 },
    { "slug": "aspe",  "nombre": "Aspe",  "pelotaris": 25 }
  ]
}

El campo slug es el que se usa en el resto de rutas de plantillas.

Pelotaris de un equipo

GET/equipos/{equipo}/pelotaris

curl -H "X-API-Key: TU_CLAVE" \
  "https://datosapi.pelotaproliga.com/api/v1/equipos/baiko/pelotaris?posicion=delantero"

{
  "data": [
    {
      "id": 2278,
      "equipo": "baiko",
      "nombre": "AGIRRE",
      "alias": "AGIRRE",
      "nombre_completo": "Asier Agirre Irisarri",
      "posicion": "delantero",
      "retirado": false,
      "foto": "https://…/agirre.png",
      "foto_miniatura": "https://…/agirre-300x295.png",
      "ficha": {
        "fecha_nacimiento": "1995-06-11",
        "edad": 31,
        "lugar_nacimiento": "Pamplona",
        "provincia_nacimiento": "Navarra",
        "altura_cm": 182,
        "peso_kg": 74,
        "fecha_debut": "2015-06-13",
        "lugar_debut": "Pamplona (Labrit)",
        "palmares_profesional": "2025 Subcampeón Manomanista Serie B\n2024 Campeón Parejas Serie B",
        "palmares_aficionado": null,
        "txapelas": {
          "manomanista": { "numero": null, "anos": null },
          "cuatro_y_medio": { "numero": null, "anos": null },
          "parejas": { "numero": null, "anos": null }
        }
      }
    }
  ],
  "meta": { "equipo": "baiko", "total": 11 }
}

Ficha de un pelotari

GET/pelotaris/{id}

Devuelve la misma estructura que cada elemento del listado, dentro de data. Si el pelotari no existe o no está publicado, responde 404.

Notas y buenas prácticas

• Caché: las respuestas se almacenan unos minutos (5 por defecto). Un cambio en la web puede tardar ese tiempo en reflejarse; no hace falta consultar con más frecuencia.
• Reduce peticiones: pide solo el rango de fechas que necesites y guarda los resultados en tu aplicación, sobre todo la plantilla, que cambia poco.
• Controla los límites: lee X-RateLimit-Remaining y, si recibes 429, espera los segundos de Retry-After antes de reintentar.
• Eventos con entradas sin partidos: pueden aparecer (con id entrada-…), sin pelotaris ni resultado, hasta que se carguen los partidos.
• Soporte: si necesitas más cupo, una IP adicional o una clave nueva, contacta con el administrador de la API.