DerbiDerbi

API de clientes · v1

Los datos de la liga, en tu web o tu app

Una API REST de solo lectura con la clasificación, el calendario, los resultados, los goleadores y la ficha de cada equipo de cualquier liga con la web pública activada. JSON e iCal, calculado al momento.

URL basehttps://derbiapp.com/client-api/v1

Introducción

La API lee los mismos datos que ve todo el mundo en la web pública de cada liga, pero en un formato pensado para programas: puedes usarla para mostrar la clasificación en la web del club, enviar los resultados a una pantalla del pabellón o integrar el calendario en una app propia.

Todas las respuestas se calculan con el mismo motor que usa la app Derbi: los desempates, las incomparecencias y las sanciones del reglamento de cada liga ya están aplicados.

  • Solo lectura, solo ligas publicadas
  • JSON en UTF-8; fechas en milisegundos UTC
  • Calendario iCal para suscribirse
  • Siempre con clave, facturada por consumo

Empieza en un minuto

Haz la primera llamada con la clave de demostración. Devuelve la liga entera: equipos, clasificación, partidos y goleadores.

curl https://derbiapp.com/client-api/v1/leagues/demo-futbol-7 \
  -H "Authorization: Bearer dk_demo_derbi_client_api_v1"

Autenticación

Todas las llamadas necesitan una clave. Envíala en la cabecera Authorization como Bearer (o en X-Api-Key si tu cliente no puede poner Authorization).

Authorization: Bearer dk_live_…

Clave de demostración

Pública a propósito: solo lee las cuatro ligas de demostración, tiene un límite de 30 llamadas por minuto y nunca se factura.

dk_demo_derbi_client_api_v1
  • demo-futbol-sala
  • demo-futbol-7
  • demo-futbol-11
  • demo-basquet

Tu clave

  1. Entra en el admin de Derbi con tu cuenta de organizador.
  2. Ve a Cuenta › API y activa la API con tu tarjeta.
  3. Crea una clave y cópiala: solo se muestra una vez.
Consigue una clave

No pongas la clave en el código de una página web pública: cualquiera podría copiarla y gastar en tu cuenta. Llama a la API desde tu servidor y guarda allí la respuesta.

Consola

Prueba cualquier endpoint aquí mismo. Por defecto usa la clave de demostración y las ligas de demostración; con tu clave puedes leer cualquier liga publicada.

Comando curl

Cabeceras

Respuesta

Endpoints

Todos son GET y comparten la misma URL base. {slug} es la dirección pública de la liga (la misma que /lliga/{slug} en la web).

GET/leagues/{slug}

Liga entera

Datos de la liga, equipos, clasificación, todos los partidos y goleadores en una sola respuesta. Es la llamada más útil: con una sola petición puedes pintar toda la web de la liga.

Parámetros

slugstring · ruta · obligatorioDirección pública de la liga.

Devuelve: LeagueView

curl https://derbiapp.com/client-api/v1/leagues/demo-futbol-7 \
  -H "Authorization: Bearer dk_demo_derbi_client_api_v1"
Ejemplo de respuesta
{
  "league": {
    "name": "Lliga Demo Futbol 7",
    "season": "2026/27",
    "sport": "football7",
    "rounds": 18,
    "currentRound": 10,
    "championSlots": 1,
    "playoffSlots": 3,
    "columns": [
      "pos",
      "team",
      "played",
      "won",
      "drawn",
      "lost",
      "for",
      "diff",
      "points"
    ],
    "scoreUnit": "goals",
    "players": true,
    "brand": {
      "mode": "dark",
      "color": "#2f6fd6",
      "intro": "La lliga de futbol 7 dels dissabtes al matí."
    }
  },
  "teams": [
    {
      "id": "demo-futbol-7-sal",
      "name": "CF Saltiró",
      "short": "SAL",
      "color": "#7B4FD6",
      "homeVenue": "Camp del Saltiró"
    },
    {
      "id": "demo-futbol-7-mon",
      "name": "Club Montalt",
      "short": "MON",
      "color": "#D6458F",
      "homeVenue": "Camp de Montalt"
    },
    {
      "id": "demo-futbol-7-roc",
      "name": "FC Rocafort",
      "short": "ROC",
      "color": "#1F9D55",
      "homeVenue": "Camp Municipal Rocafort"
    }
  ],
  "standings": [
    {
      "teamId": "demo-futbol-7-sal",
      "played": 10,
      "won": 5,
      "drawn": 4,
      "lost": 1,
      "for": 19,
      "against": 6,
      "diff": 13,
      "points": 19,
      "form": [
        "W",
        "W",
        "W",
        "D",
        "D"
      ],
      "pos": 1,
      "zone": "champion"
    },
    {
      "teamId": "demo-futbol-7-mon",
      "played": 10,
      "won": 4,
      "drawn": 5,
      "lost": 1,
      "for": 10,
      "against": 3,
      "diff": 7,
      "points": 17,
      "form": [
        "W",
        "W",
        "W",
        "D",
        "L"
      ],
      "pos": 2,
      "zone": "playoff"
    },
    {
      "teamId": "demo-futbol-7-roc",
      "played": 10,
      "won": 5,
      "drawn": 1,
      "lost": 4,
      "for": 17,
      "against": 11,
      "diff": 6,
      "points": 16,
      "form": [
        "W",
        "L",
        "W",
        "W",
        "W"
      ],
      "pos": 3,
      "zone": "playoff"
    }
  ],
  "matches": [
    {
      "id": "demo-futbol-7-j10-48",
      "round": 10,
      "homeId": "demo-futbol-7-vil",
      "awayId": "demo-futbol-7-est",
      "startsAt": 1792828800000,
      "venue": "Camp de Vilanoveta",
      "status": "finished",
      "homeScore": 3,
      "awayScore": 1
    },
    {
      "id": "demo-futbol-7-j10-49",
      "round": 10,
      "homeId": "demo-futbol-7-can",
      "awayId": "demo-futbol-7-sal",
      "startsAt": 1792828800000,
      "venue": "Camp de Canyet",
      "status": "finished",
      "homeScore": 1,
      "awayScore": 1
    },
    {
      "id": "demo-futbol-7-j11-50",
      "round": 11,
      "homeId": "demo-futbol-7-gav",
      "awayId": "demo-futbol-7-bel",
      "startsAt": 1793437200000,
      "venue": "Camp de les Gavarres",
      "status": "scheduled"
    }
  ],
  "scorers": [
    {
      "pos": 1,
      "playerId": "demo-futbol-7-sal-5",
      "teamId": "demo-futbol-7-sal",
      "name": "Roger Vilaró",
      "value": 5,
      "matches": 10
    },
    {
      "pos": 2,
      "playerId": "demo-futbol-7-vil-4",
      "teamId": "demo-futbol-7-vil",
      "name": "Arnau Xirau",
      "value": 4,
      "matches": 10
    },
    {
      "pos": 3,
      "playerId": "demo-futbol-7-bel-5",
      "teamId": "demo-futbol-7-bel",
      "name": "Eloi Gual",
      "value": 4,
      "matches": 10
    }
  ],
  "live": false
}

GET/leagues/{slug}/matches

Partidos

Todos los partidos de la temporada, ordenados por jornada y hora, con los equipos para resolver sus nombres. Los partidos aún no jugados no llevan marcador.

Parámetros

slugstring · ruta · obligatorioDirección pública de la liga.

Devuelve: { matches: Match[], teams: Team[] }

curl https://derbiapp.com/client-api/v1/leagues/demo-futbol-7/matches \
  -H "Authorization: Bearer dk_demo_derbi_client_api_v1"
Ejemplo de respuesta
{
  "matches": [
    {
      "id": "demo-futbol-7-j10-48",
      "round": 10,
      "homeId": "demo-futbol-7-vil",
      "awayId": "demo-futbol-7-est",
      "startsAt": 1792828800000,
      "venue": "Camp de Vilanoveta",
      "status": "finished",
      "homeScore": 3,
      "awayScore": 1
    },
    {
      "id": "demo-futbol-7-j10-49",
      "round": 10,
      "homeId": "demo-futbol-7-can",
      "awayId": "demo-futbol-7-sal",
      "startsAt": 1792828800000,
      "venue": "Camp de Canyet",
      "status": "finished",
      "homeScore": 1,
      "awayScore": 1
    },
    {
      "id": "demo-futbol-7-j11-50",
      "round": 11,
      "homeId": "demo-futbol-7-gav",
      "awayId": "demo-futbol-7-bel",
      "startsAt": 1793437200000,
      "venue": "Camp de les Gavarres",
      "status": "scheduled"
    }
  ],
  "teams": [
    {
      "id": "demo-futbol-7-sal",
      "name": "CF Saltiró",
      "short": "SAL",
      "color": "#7B4FD6",
      "homeVenue": "Camp del Saltiró"
    },
    {
      "id": "demo-futbol-7-mon",
      "name": "Club Montalt",
      "short": "MON",
      "color": "#D6458F",
      "homeVenue": "Camp de Montalt"
    },
    {
      "id": "demo-futbol-7-roc",
      "name": "FC Rocafort",
      "short": "ROC",
      "color": "#1F9D55",
      "homeVenue": "Camp Municipal Rocafort"
    }
  ]
}

GET/leagues/{slug}/scorers

Goleadores

Clasificación de goleadores (o de máximos anotadores en baloncesto). Devuelve 404 si la liga ha decidido no publicar nombres de jugadores.

Parámetros

slugstring · ruta · obligatorioDirección pública de la liga.

Devuelve: { scorers: Scorer[], teams: Team[] }

curl https://derbiapp.com/client-api/v1/leagues/demo-futbol-7/scorers \
  -H "Authorization: Bearer dk_demo_derbi_client_api_v1"
Ejemplo de respuesta
{
  "scorers": [
    {
      "pos": 1,
      "playerId": "demo-futbol-7-sal-5",
      "teamId": "demo-futbol-7-sal",
      "name": "Roger Vilaró",
      "value": 5,
      "matches": 10
    },
    {
      "pos": 2,
      "playerId": "demo-futbol-7-vil-4",
      "teamId": "demo-futbol-7-vil",
      "name": "Arnau Xirau",
      "value": 4,
      "matches": 10
    },
    {
      "pos": 3,
      "playerId": "demo-futbol-7-bel-5",
      "teamId": "demo-futbol-7-bel",
      "name": "Eloi Gual",
      "value": 4,
      "matches": 10
    }
  ],
  "teams": [
    {
      "id": "demo-futbol-7-sal",
      "name": "CF Saltiró",
      "short": "SAL",
      "color": "#7B4FD6",
      "homeVenue": "Camp del Saltiró"
    },
    {
      "id": "demo-futbol-7-mon",
      "name": "Club Montalt",
      "short": "MON",
      "color": "#D6458F",
      "homeVenue": "Camp de Montalt"
    },
    {
      "id": "demo-futbol-7-roc",
      "name": "FC Rocafort",
      "short": "ROC",
      "color": "#1F9D55",
      "homeVenue": "Camp Municipal Rocafort"
    }
  ]
}

GET/leagues/{slug}/teams/{teamId}

Ficha de equipo

Un equipo: sus datos, su fila de la clasificación, sus partidos y la plantilla (si la liga publica jugadores).

Parámetros

slugstring · ruta · obligatorioDirección pública de la liga.
teamIdstring · ruta · obligatorioIdentificador del equipo (campo id de Team).

Devuelve: TeamView

curl https://derbiapp.com/client-api/v1/leagues/demo-futbol-7/teams/demo-futbol-7-sal \
  -H "Authorization: Bearer dk_demo_derbi_client_api_v1"
Ejemplo de respuesta
{
  "team": {
    "id": "demo-futbol-7-sal",
    "name": "CF Saltiró",
    "short": "SAL",
    "color": "#7B4FD6",
    "homeVenue": "Camp del Saltiró"
  },
  "standing": {
    "teamId": "demo-futbol-7-sal",
    "played": 10,
    "won": 5,
    "drawn": 4,
    "lost": 1,
    "for": 19,
    "against": 6,
    "diff": 13,
    "points": 19,
    "form": [
      "W",
      "W",
      "W",
      "D",
      "D"
    ],
    "pos": 1,
    "zone": "champion"
  },
  "matches": [
    {
      "id": "demo-futbol-7-j1-4",
      "round": 1,
      "homeId": "demo-futbol-7-sal",
      "awayId": "demo-futbol-7-can",
      "startsAt": 1787385600000,
      "venue": "Camp del Saltiró",
      "status": "finished",
      "homeScore": 1,
      "awayScore": 1
    },
    {
      "id": "demo-futbol-7-j2-9",
      "round": 2,
      "homeId": "demo-futbol-7-vil",
      "awayId": "demo-futbol-7-sal",
      "startsAt": 1787990400000,
      "venue": "Camp de Vilanoveta",
      "status": "finished",
      "homeScore": 1,
      "awayScore": 5
    }
  ],
  "players": [
    {
      "id": "demo-futbol-7-sal-1",
      "name": "Jofre Pagès",
      "number": 1,
      "position": "goalkeeper"
    },
    {
      "id": "demo-futbol-7-sal-5",
      "name": "Roger Vilaró",
      "number": 5,
      "position": "forward"
    }
  ]
}

GET/leagues/{slug}/calendar.ics

Calendario iCal

Los partidos con fecha en formato iCalendar, para suscribirse desde Google Calendar, Apple Calendar u Outlook. Con ?team= solo los de un equipo.

Parámetros

slugstring · ruta · obligatorioDirección pública de la liga.
teamstring · consulta · opcionalSolo los partidos de este equipo.

Devuelve: iCalendar

curl https://derbiapp.com/client-api/v1/leagues/demo-futbol-7/calendar.ics \
  -H "Authorization: Bearer dk_demo_derbi_client_api_v1"
Ejemplo de respuesta
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Derbi//Lliga//CA
X-WR-CALNAME:Lliga Demo Futbol 7
BEGIN:VEVENT
UID:demo-futbol-7-j11-50@demo-futbol-7.derbi
DTSTART:20261107T090000Z
DTEND:20261107T101500Z
SUMMARY:CE Gavarres - Penya Bellavista
LOCATION:Camp de les Gavarres
DESCRIPTION:Lliga Demo Futbol 7 · J11
END:VEVENT
END:VCALENDAR

Objetos

Los campos opcionales solo aparecen cuando tienen valor. Los nombres de los campos no cambiarán dentro de la v1.

LeagueView

CampoTipoDescripción
leagueLeagueLa liga.
teamsTeam[]Todos los equipos, por nombre.
standingsStanding[]La clasificación, por posición.
matchesMatch[]Todos los partidos, por jornada y hora.
scorersScorer[] | nullGoleadores; null si la liga no publica jugadores.
livebooleanHay algún partido en juego ahora mismo.

League

CampoTipoDescripción
namestringNombre de la liga.
group?stringGrupo o división.
city?stringCiudad.
seasonstringTemporada ("2026/27").
sport"futsal" | "football7" | "football11" | "basketball"Deporte.
roundsintegerJornadas totales.
currentRoundintegerJornada actual.
championSlotsintegerPosiciones de campeón (1..n).
playoffSlotsintegerPosiciones de play-off tras las de campeón.
columnsstring[]Columnas de la clasificación del deporte, en orden.
scoreUnit"goals" | "points"Unidad del marcador: goles o puntos.
playersbooleanSi la liga publica nombres de jugadores.
brandBrandLa apariencia que ha elegido el organizador para la web.

Brand

CampoTipoDescripción
mode"dark" | "light"Tema: oscuro o claro.
color?stringColor principal (hex).
logoUrl?stringURL del logo de la liga.
coverUrl?stringURL de la imagen de portada.
intro?stringTexto de presentación (hasta 280 caracteres).

Team

CampoTipoDescripción
idstringIdentificador.
namestringNombre.
shortstringAbreviatura de 3 letras.
colorstringColor principal (hex).
homeVenue?stringCampo o pabellón habitual.
kit?objectColores de la equipación, por piezas (hex).
crest?objectColores del escudo (hex).

Standing

CampoTipoDescripción
posintegerPosición.
teamIdstringEquipo.
playedintegerPartidos jugados.
wonintegerGanados.
drawnintegerEmpatados (siempre 0 en baloncesto).
lostintegerPerdidos.
forintegerGoles o puntos a favor.
againstintegerGoles o puntos en contra.
diffintegerDiferencia.
pointsintegerPuntos de clasificación.
zone"champion" | "playoff" | nullZona: campeón, play-off o ninguna.
form("W" | "D" | "L")[]Últimos 5 resultados, el más reciente al final.

Match

CampoTipoDescripción
idstringIdentificador.
roundintegerJornada.
homeIdstringEquipo local.
awayIdstringEquipo visitante.
startsAtinteger | nullInicio en milisegundos UTC; null si la fecha está por confirmar.
venuestringCampo o pabellón.
status"scheduled" | "live" | "pending_result" | "finished" | "postponed" | "suspended_rain"Estado: programado, en juego, pendiente de resultado, terminado, aplazado o suspendido por lluvia.
homeScore?integerMarcador local, una vez empezado.
awayScore?integerMarcador visitante, una vez empezado.
outcome?{ kind, by }Si no se jugó entero: tipo (incomparecencia, abandono…) y equipo responsable.

Scorer

CampoTipoDescripción
posintegerPosición.
playerIdstringJugador.
teamIdstringEquipo.
namestringNombre (completo o nombre e inicial, según la liga).
valueintegerGoles o puntos.
matchesintegerPartidos jugados.

TeamView

CampoTipoDescripción
teamTeamEl equipo.
standingStanding | nullSu fila de la clasificación.
matchesMatch[]Sus partidos.
playersPlayer[] | nullPlantilla por dorsal; null si la liga no publica jugadores.

Player

CampoTipoDescripción
idstringIdentificador.
namestringNombre.
numberintegerDorsal.
positionstringPosición (identificador del deporte).

Error

CampoTipoDescripción
error"key" | "billing" | "league" | "not_found" | "rate"Código del error.
messagestringExplicación en inglés.
docsstringEnlace a esta página.

Errores

Los errores devuelven un código HTTP y un JSON con un código estable, una explicación y el enlace a esta documentación.

HTTPCódigoCuándo pasa
401keyFalta la clave, no existe o se ha revocado.
402billingLa cuenta de la clave no tiene la API activa (o el pago ha fallado).
403leagueLa clave no puede leer esta liga (la de demostración solo lee las de demostración).
404not_foundNo hay ninguna liga publicada en esta dirección, o el equipo no existe.
429rateDemasiadas llamadas en un minuto. Espera y vuelve a intentarlo.
{
  "error": "key",
  "message": "Missing, unknown or revoked API key. Send it as `Authorization: Bearer <key>`; create one in the Derbi admin.",
  "docs": "https://derbiapp.com/client-api/v1/apidoc"
}

Límites y datos

Límite por clave
600 llamadas por minuto (30 con la clave de demostración). Si lo pasas, 429.
Datos al momento
Cada llamada con clave se calcula de nuevo: ves el resultado que el árbitro acaba de cerrar.
Guarda la respuesta
La clasificación cambia pocas veces al día: guárdala unos minutos en tu servidor y ahorrarás llamadas.
Fechas
Milisegundos desde el 1/1/1970 UTC. Conviértelas a la hora local de la liga (Europa/Madrid) para mostrarlas.
Ligas publicadas
Solo se pueden leer las ligas con la web pública activada y la suscripción al día.

Privacidad

El organizador de cada liga decide cómo salen los jugadores: nombre completo, nombre e inicial del apellido, o ningún nombre (entonces no hay goleadores ni plantillas). La API nunca devuelve correos, teléfonos, años de nacimiento, códigos de invitación, convocatorias, árbitros ni pagos.

Precios

Pagas por lo que usas, cada mes, con la tarjeta de tu cuenta de organizador. Sin llamadas, no pagas nada.

10.000

llamadas al mes gratis

0,50 €

por cada 1.000 llamadas más

Ejemplos por mes

LlamadasImporte
50000 €
10.0000 €
50.00020 €
200.00095 €
1.000.000495 €

Precios sin IVA. La factura llega por correo desde Stripe.

Consigue una clave

Versiones

La v1 es estable: solo añadiremos campos o endpoints nuevos, nunca quitaremos ni cambiaremos su significado. Si algún día hace falta un cambio incompatible, saldrá como /client-api/v2 y la v1 seguirá funcionando.

Descarga la especificación OpenAPI