Documentación API v1

Navegación

🔑 Autenticación

Todas las peticiones (excepto /status) requieren tu API Key en el header Authorization.

Authorization: Bearer avafa_xxxxxxxxxxxxxxxxxxxxxxxx

Sin key → 401. Key inválida → 401. Límite excedido → 429.

Health check. No requiere API key. Útil para monitorización.

{
  "success": true,
  "data": {
    "status": "ok",
    "version": "1.0",
    "liga": "LaLiga (España)",
    "total_predicciones": 139,
    "proximos_partidos": 30,
    "ultima_actualizacion": "2026-03-26T05:00:00Z"
  }
}

Predicciones de la próxima jornada disponible (LaLiga). Plan Professional+: filtrar por risk_profile y league_id.

{
  "success": true,
  "data": [
    {
      "match_id": 19439545,
      "match_date": "2026-04-03T19:00:00Z",
      "jornada": "29",
      "liga": "LaLiga",
      "equipo_local": "Rayo Vallecano",
      "equipo_visitante": "Elche",
      "prediccion": {
        "mercado": "resultado",
        "seleccion": "local",
        "cuota": 1.72,
        "confianza_pct": 68,
        "mercado_recomendado": "Resultado 1X2"
      },
      "notas": "Ventaja local esperada: 1.60 vs 1.00 goles"
    }
  ],
  "meta": { "tier": "basic", "requests_remaining": 97, "jornada": "29" },
  "disclaimer": "Juega con responsabilidad..."
}

Predicción de un partido específico por su ID. Devuelve resultado real si el partido está terminado.

curl -H "Authorization: Bearer TU_KEY" \
  /api/v1/predictions/19439545

Error 404 si el partido no existe.

Historial de predicciones con resultado real. Devuelve campo acertada: true/false por partido.

{
  "success": true,
  "data": [
    {
      "match_id": 19439432,
      "match_date": "2026-01-09T20:00:00Z",
      "equipo_local": "Getafe",
      "equipo_visitante": "Real Sociedad",
      "resultado_real": "1-2",
      "prediccion": { "mercado": "resultado", "seleccion": "visitante", "cuota": 2.1, "confianza_pct": 62 },
      "acertada": true,
      "resultado": "win"
    }
  ],
  "meta": { "tasa_acierto_pct": 61.5, "aciertos": 67, "resolvidos": 109 }
}

Estadísticas globales: tasa de acierto, ROI, racha actual y rendimiento por jornada.

{
  "success": true,
  "data": {
    "total_predicciones": 139,
    "aciertos": 67,
    "tasa_acierto_pct": 61.5,
    "roi_pct": 14.3,
    "confianza_media_pct": 65,
    "racha_actual": 4,
    "jornadas_recientes": [
      { "jornada": "28", "aciertos": 7, "fallos": 3, "roi_pct": 15.0 }
    ]
  }
}

Análisis extendido: xG, BTTS, goles promedio, forma reciente (últimos 5), análisis táctico del enfrentamiento.

{
  "data": {
    "stats_local": {
      "goles_marcados_casa_avg": 1.8,
      "btts_casa_pct": 66.7,
      "xg": { "xg_casa_avg": 1.92 }
    },
    "forma_reciente_local": [
      { "rival": "Getafe", "condicion": "casa", "marcador": "2-0", "resultado": "V" }
    ],
    "analisis_tactico": {
      "perfil": "ofensivo",
      "probabilidad_btts_pct": 72
    }
  }
}

Lista de ligas disponibles con número de fixtures activos.

❌ Códigos de Error

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEDIDO",
    "message": "Has superado el límite de 100 requests/hora. Prueba de nuevo en 42 minutos.",
    "retry_after": 2520
  }
}

⚡ Rate Limits

Headers de respuesta incluidos en cada llamada:

• X-RateLimit-Limit — Límite total por hora
• X-RateLimit-Remaining — Requests restantes esta hora
• X-RateLimit-Reset — Unix timestamp del próximo reset

Predicciones de LaLiga con mercados básicos: resultado 1X2, Over/Under, BTTS.

curl -H "Authorization: Bearer avafa_demo_starter_2026_x8k2m4n9p" \
  https://marcorodriguez.polsia.app/api/v1/predictions/today

{
  "success": true,
  "data": [
    {
      "match_id": 19439545,
      "jornada": "30",
      "liga": "LaLiga",
      "equipo_local": "Real Madrid",
      "equipo_visitante": "Atletico Madrid",
      "prediccion": { "mercado": "resultado", "seleccion": "local", "cuota": 1.85, "confianza_pct": 72 }
    }
  ],
  "meta": { "tier": "starter", "requests_remaining": 97 }
}

Análisis extendido con xG, BTTS, forma reciente y filtros risk_profile.

curl -H "Authorization: Bearer avafa_demo_professional_2026_q7r3s1" \
  https://marcorodriguez.polsia.app/api/v1/predictions/19439545/analysis

{
  "data": {
    "equipo_local": "Real Madrid",
    "equipo_visitante": "Atletico Madrid",
    "prediccion": { "mercado": "resultado", "seleccion": "local", "cuota": 1.85, "confianza_pct": 72 },
    "stats_local": { "goles_marcados_casa_avg": 2.3, "btts_casa_pct": 55.6, "xg": { "xg_casa_avg": 2.1 } },
    "analisis_tactico": { "perfil": "ofensivo", "probabilidad_btts_pct": 47 }
  },
  "meta": { "tier": "professional", "requests_remaining": 498 }
}

Acceso total — todas las ligas, white-label, SLA 99.5%, prioridad en servidor.

curl -H "Authorization: Bearer avafa_demo_enterprise_2026_z5w9v2t" \
  "https://marcorodriguez.polsia.app/api/v1/predictions/today?league_id=39&risk_profile=conservative"

{
  "data": [
    {
      "liga": "Premier League",
      "equipo_local": "Arsenal",
      "equipo_visitante": "Chelsea",
      "prediccion": { "seleccion": "local", "cuota": 1.75, "confianza_pct": 76 }
    }
  ],
  "meta": { "tier": "enterprise", "requests_remaining": 1998, "risk_profile_applied": "conservative" }
}