API de clients · v1

Les dades de la lliga, a la teva web o la teva app

Una API REST de només lectura amb la classificació, el calendari, els resultats, els golejadors i la fitxa de cada equip de qualsevol lliga que tingui la web pública activada. JSON i iCal, calculat al moment.

Aconsegueix una clau Prova-la ara

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

Introducció

L'API llegeix les mateixes dades que veu tothom a la web pública de cada lliga, però en un format pensat per a programes: la pots fer servir per mostrar la classificació a la web del club, enviar els resultats a una pantalla del pavelló o integrar el calendari en una app pròpia.

Totes les respostes es calculen amb el mateix motor que fa servir l'app Derbi: els desempats, les incompareixences i les sancions del reglament de cada lliga ja hi són aplicats.

Només lectura, només lligues publicades
JSON en UTF-8; dates en mil·lisegons UTC
Calendari iCal per subscriure-s'hi
Sempre amb clau, facturada pel consum

Comença en un minut

Fes la primera crida amb la clau de demostració. Retorna la lliga sencera: equips, classificació, partits i golejadors.

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

const res = await fetch("https://derbiapp.com/client-api/v1/leagues/demo-futbol-7", {
  headers: { Authorization: "Bearer dk_demo_derbi_client_api_v1" },
});
if (!res.ok) throw new Error((await res.json()).message);
const data = await res.json();

import requests

res = requests.get(
    "https://derbiapp.com/client-api/v1/leagues/demo-futbol-7",
    headers={"Authorization": "Bearer dk_demo_derbi_client_api_v1"},
)
res.raise_for_status()
data = res.json()

Autenticació

Totes les crides necessiten una clau. Envia-la a la capçalera Authorization com a Bearer (o a X-Api-Key si el teu client no pot posar Authorization).

Authorization: Bearer dk_live_…

Clau de demostració

Pública a propòsit: només llegeix les quatre lligues de demostració, té un límit de 30 crides per minut i no es factura mai.

dk_demo_derbi_client_api_v1

demo-futbol-sala
demo-futbol-7
demo-futbol-11
demo-basquet

La teva clau

Entra a l'admin de Derbi amb el teu compte d'organitzador.
Ves a Compte › API i activa l'API amb la teva targeta.
Crea una clau i copia-la: només es mostra un cop.

Aconsegueix una clau

No posis la clau al codi d'una pàgina web pública: qualsevol la podria copiar i gastar al teu compte. Crida l'API des del teu servidor i desa-hi la resposta.

Consola

Prova qualsevol endpoint aquí mateix. Per defecte fa servir la clau de demostració i les lligues de demostració; amb la teva clau pots llegir qualsevol lliga publicada.

EndpointLligaClau

Comanda curl

Capçaleres

Resposta

Endpoints

Tots són GET i comparteixen la mateixa URL base. {slug} és l'adreça pública de la lliga (la mateixa que /lliga/{slug} a la web).

GET`/leagues/{slug}`

Lliga sencera

Dades de la lliga, equips, classificació, tots els partits i golejadors en una sola resposta. És la crida més útil: amb una sola petició pots pintar tota la web de la lliga.

Paràmetres

slug string · camí · obligatori Adreça pública de la lliga.

Retorna: LeagueView

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

const res = await fetch("https://derbiapp.com/client-api/v1/leagues/demo-futbol-7", {
  headers: { Authorization: "Bearer dk_demo_derbi_client_api_v1" },
});
if (!res.ok) throw new Error((await res.json()).message);
const data = await res.json();

import requests

res = requests.get(
    "https://derbiapp.com/client-api/v1/leagues/demo-futbol-7",
    headers={"Authorization": "Bearer dk_demo_derbi_client_api_v1"},
)
res.raise_for_status()
data = res.json()

Exemple de resposta

{
  "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`

Partits

Tots els partits de la temporada, ordenats per jornada i hora, amb els equips per resoldre'n els noms. Els partits encara no jugats no porten marcador.

Paràmetres

slug string · camí · obligatori Adreça pública de la lliga.

Retorna: { 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"

const res = await fetch("https://derbiapp.com/client-api/v1/leagues/demo-futbol-7/matches", {
  headers: { Authorization: "Bearer dk_demo_derbi_client_api_v1" },
});
if (!res.ok) throw new Error((await res.json()).message);
const data = await res.json();

import requests

res = requests.get(
    "https://derbiapp.com/client-api/v1/leagues/demo-futbol-7/matches",
    headers={"Authorization": "Bearer dk_demo_derbi_client_api_v1"},
)
res.raise_for_status()
data = res.json()

Exemple de resposta

{
  "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`

Golejadors

Classificació de golejadors (o de màxims anotadors en bàsquet). Retorna 404 si la lliga ha decidit no publicar noms de jugadors.

Paràmetres

slug string · camí · obligatori Adreça pública de la lliga.

Retorna: { 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"

const res = await fetch("https://derbiapp.com/client-api/v1/leagues/demo-futbol-7/scorers", {
  headers: { Authorization: "Bearer dk_demo_derbi_client_api_v1" },
});
if (!res.ok) throw new Error((await res.json()).message);
const data = await res.json();

import requests

res = requests.get(
    "https://derbiapp.com/client-api/v1/leagues/demo-futbol-7/scorers",
    headers={"Authorization": "Bearer dk_demo_derbi_client_api_v1"},
)
res.raise_for_status()
data = res.json()

Exemple de resposta

{
  "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}`

Fitxa d'equip

Un equip: les seves dades, la seva fila de la classificació, els seus partits i la plantilla (si la lliga publica jugadors).

Paràmetres

`slug`	string · camí · obligatori	Adreça pública de la lliga.
`teamId`	string · camí · obligatori	Identificador de l'equip (camp id de Team).

Retorna: 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"

const res = await fetch("https://derbiapp.com/client-api/v1/leagues/demo-futbol-7/teams/demo-futbol-7-sal", {
  headers: { Authorization: "Bearer dk_demo_derbi_client_api_v1" },
});
if (!res.ok) throw new Error((await res.json()).message);
const data = await res.json();

import requests

res = requests.get(
    "https://derbiapp.com/client-api/v1/leagues/demo-futbol-7/teams/demo-futbol-7-sal",
    headers={"Authorization": "Bearer dk_demo_derbi_client_api_v1"},
)
res.raise_for_status()
data = res.json()

Exemple de resposta

{
  "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`

Calendari iCal

Els partits amb data en format iCalendar, per subscriure-s'hi des de Google Calendar, Apple Calendar o Outlook. Amb ?team= només els d'un equip.

Paràmetres

`slug`	string · camí · obligatori	Adreça pública de la lliga.
`team`	string · consulta · opcional	Només els partits d'aquest equip.

Retorna: iCalendar

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

const res = await fetch("https://derbiapp.com/client-api/v1/leagues/demo-futbol-7/calendar.ics", {
  headers: { Authorization: "Bearer dk_demo_derbi_client_api_v1" },
});
if (!res.ok) throw new Error((await res.json()).message);
const data = await res.text();

import requests

res = requests.get(
    "https://derbiapp.com/client-api/v1/leagues/demo-futbol-7/calendar.ics",
    headers={"Authorization": "Bearer dk_demo_derbi_client_api_v1"},
)
res.raise_for_status()
data = res.text

Exemple de resposta

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

Objectes

Els camps opcionals només hi són quan tenen valor. Els noms dels camps no canviaran dins de la v1.

LeagueView

Camp	Tipus	Descripció
`league`	League	La lliga.
`teams`	Team[]	Tots els equips, per nom.
`standings`	Standing[]	La classificació, per posició.
`matches`	Match[]	Tots els partits, per jornada i hora.
`scorers`	Scorer[] \| null	Golejadors; null si la lliga no publica jugadors.
`live`	boolean	Hi ha algun partit en joc ara mateix.

League

Camp	Tipus	Descripció
`name`	string	Nom de la lliga.
`group`?	string	Grup o divisió.
`city`?	string	Ciutat.
`season`	string	Temporada ("2026/27").
`sport`	"futsal" \| "football7" \| "football11" \| "basketball"	Esport.
`rounds`	integer	Jornades totals.
`currentRound`	integer	Jornada actual.
`championSlots`	integer	Posicions de campió (1..n).
`playoffSlots`	integer	Posicions de play-off després de les de campió.
`columns`	string[]	Columnes de la classificació de l'esport, en ordre.
`scoreUnit`	"goals" \| "points"	Unitat del marcador: gols o punts.
`players`	boolean	Si la lliga publica noms de jugadors.
`brand`	Brand	L'aparença que ha triat l'organitzador per a la web.

Brand

Camp	Tipus	Descripció
`mode`	"dark" \| "light"	Tema: fosc o clar.
`color`?	string	Color principal (hex).
`logoUrl`?	string	URL del logo de la lliga.
`coverUrl`?	string	URL de la imatge de portada.
`intro`?	string	Text de presentació (fins a 280 caràcters).

Team

Camp	Tipus	Descripció
`id`	string	Identificador.
`name`	string	Nom.
`short`	string	Abreviatura de 3 lletres.
`color`	string	Color principal (hex).
`homeVenue`?	string	Camp o pavelló habitual.
`kit`?	object	Colors de l'equipació, per peces (hex).
`crest`?	object	Colors de l'escut (hex).

Standing

Camp	Tipus	Descripció
`pos`	integer	Posició.
`teamId`	string	Equip.
`played`	integer	Partits jugats.
`won`	integer	Guanyats.
`drawn`	integer	Empatats (sempre 0 en bàsquet).
`lost`	integer	Perduts.
`for`	integer	Gols o punts a favor.
`against`	integer	Gols o punts en contra.
`diff`	integer	Diferència.
`points`	integer	Punts de classificació.
`zone`	"champion" \| "playoff" \| null	Zona: campió, play-off o cap.
`form`	("W" \| "D" \| "L")[]	Últims 5 resultats, el més recent al final.

Match

Camp	Tipus	Descripció
`id`	string	Identificador.
`round`	integer	Jornada.
`homeId`	string	Equip local.
`awayId`	string	Equip visitant.
`startsAt`	integer \| null	Inici en mil·lisegons UTC; null si la data està per confirmar.
`venue`	string	Camp o pavelló.
`status`	"scheduled" \| "live" \| "pending_result" \| "finished" \| "postponed" \| "suspended_rain"	Estat: programat, en joc, pendent de resultat, acabat, ajornat o suspès per pluja.
`homeScore`?	integer	Marcador local, un cop començat.
`awayScore`?	integer	Marcador visitant, un cop començat.
`outcome`?	{ kind, by }	Si no es va jugar sencer: tipus (incompareixença, abandonament…) i equip responsable.

Scorer

Camp	Tipus	Descripció
`pos`	integer	Posició.
`playerId`	string	Jugador.
`teamId`	string	Equip.
`name`	string	Nom (complet o nom i inicial, segons la lliga).
`value`	integer	Gols o punts.
`matches`	integer	Partits jugats.

TeamView

Camp	Tipus	Descripció
`team`	Team	L'equip.
`standing`	Standing \| null	La seva fila de la classificació.
`matches`	Match[]	Els seus partits.
`players`	Player[] \| null	Plantilla per dorsal; null si la lliga no publica jugadors.

Player

Camp	Tipus	Descripció
`id`	string	Identificador.
`name`	string	Nom.
`number`	integer	Dorsal.
`position`	string	Posició (identificador de l'esport).

Error

Camp	Tipus	Descripció
`error`	"key" \| "billing" \| "league" \| "not_found" \| "rate"	Codi de l'error.
`message`	string	Explicació en anglès.
`docs`	string	Enllaç a aquesta pàgina.

Errors

Els errors tornen un codi HTTP i un JSON amb un codi estable, una explicació i l'enllaç a aquesta documentació.

HTTP	Codi	Quan passa
401	`key`	Falta la clau, no existeix o s'ha revocat.
402	`billing`	El compte de la clau no té l'API activa (o el pagament ha fallat).
403	`league`	La clau no pot llegir aquesta lliga (la de demostració només llegeix les de demostració).
404	`not_found`	No hi ha cap lliga publicada a aquesta adreça, o l'equip no existeix.
429	`rate`	Massa crides en un minut. Espera i torna-ho a provar.

{
  "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ímits i dades

Límit per clau: 600 crides per minut (30 amb la clau de demostració). Si el passes, 429.
Dades al moment: Cada crida amb clau es calcula de nou: veus el resultat que l'àrbitre acaba de tancar.
Desa la resposta: La classificació canvia poques vegades al dia: desa-la uns minuts al teu servidor i estalviaràs crides.
Dates: Mil·lisegons des de l'1/1/1970 UTC. Converteix-les a l'hora local de la lliga (Europa/Madrid) per mostrar-les.
Lligues publicades: Només es poden llegir les lligues amb la web pública activada i la subscripció al dia.

Privacitat

L'organitzador de cada lliga decideix com surten els jugadors: nom complet, nom i inicial del cognom, o cap nom (llavors no hi ha golejadors ni plantilles). L'API no retorna mai correus, telèfons, anys de naixement, codis d'invitació, convocatòries, àrbitres ni pagaments.

Preus

Pagues pel que fas servir, cada mes, amb la targeta del teu compte d'organitzador. Sense crides, no pagues res.

10.000

crides al mes gratis

0,50 €

per cada 1.000 crides més

Exemples per mes

Crides	Import
5.000	0 €
10.000	0 €
50.000	20 €
200.000	95 €
1.000.000	495 €

Preus sense IVA. La factura arriba per correu des de Stripe.

Aconsegueix una clau

Versions

La v1 és estable: només hi afegirem camps o endpoints nous, mai en traurem ni en canviarem el significat. Si algun dia cal un canvi incompatible, sortirà com a /client-api/v2 i la v1 continuarà funcionant.

Descarrega l'especificació OpenAPI

Les dades de la lliga, a la teva web o la teva app

Introducció

Comença en un minut

Autenticació

Clau de demostració

La teva clau

Consola

Endpoints

GET/leagues/{slug}

GET/leagues/{slug}/matches

GET/leagues/{slug}/scorers

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

GET/leagues/{slug}/calendar.ics

Objectes

LeagueView

League

Brand

Team

Standing

Match

Scorer

TeamView

Player

Error

Errors

Límits i dades

Privacitat

Preus

Versions

GET`/leagues/{slug}`

GET`/leagues/{slug}/matches`

GET`/leagues/{slug}/scorers`

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

GET`/leagues/{slug}/calendar.ics`