Totes les peticions (excepte les dels webhooks que reps tu) s'autentiquen amb un token Bearer associat a una credencial del club.
El token
curl -s "$PRANARP_URL/api/v1/me" \
-H "Authorization: Bearer $PCK_TOKEN"
- Té el format
pck_live_<aleatori>. - Es crea a Configuració → Integracions i es mostra una sola vegada. Pranarp Club només en desa un hash, de manera que no el podem recuperar.
- Pertany a un club: només veu les dades d'aquell club.
- Les crides actualitzen l'«últim ús» de la credencial al tauler, com a màxim un cop per minut (i no s'actualitza en les respostes
429), així que pot anar fins a un minut per darrere.
Tracta el token com una contrasenya. Si es filtra, revoca'l des del tauler: les aplicacions que el facin servir deixaran de funcionar immediatament.
Permisos (abilities)
En crear la credencial tries què pot fer. Si una operació necessita un permís que no té, reps 403 amb insufficient_ability.
| Permís | Què permet |
|---|---|
spaces:read |
Llistar i llegir espais; demanar un pressupost (/quote). |
availability:read |
Consultar franges lliures (/availability). |
bookings:read |
Llistar i llegir reserves, de qualsevol origen, dels espais permesos. |
bookings:write |
Crear reserves i modificar o cancel·lar les que ha creat aquesta mateixa credencial. |
players:read |
Llegir jugadors sincronitzats. |
players:write |
Crear, reemplaçar i esborrar jugadors. |
bookings:write_all |
Permís ampli: modificar o cancel·lar qualsevol reserva dels espais permesos. |
Sense bookings:write_all, intentar modificar o cancel·lar una reserva que no ha creat la credencial (per exemple, una feta pel personal del club) retorna 403 amb not_owner. Concedeix bookings:write_all només a les integracions que realment gestionen totes les reserves.
Espais permesos
Una credencial es pot limitar a alguns espais. A GET /me, el camp space_ids llista els ids permesos, o és null si pot fer servir tots els espais. Demanar un espai fora de la llista retorna 403 amb space_not_allowed; els llistats només inclouen els permesos.
Caducitat i revocació
Una credencial pot tenir data de caducitat (expires_at a /me, amb l'hora del club) o no caducar mai. Un cop caducada o revocada, el token deixa de funcionar:
| Situació | Estat | Codi |
|---|---|---|
| Falta la capçalera, el token no existeix o és invàlid | 401 | unauthenticated |
| La credencial ha caducat | 401 | token_expired |
| La credencial ha estat revocada | 401 | token_revoked |
El club no té activada la funció integrations |
403 | feature_disabled |
Exemple de resposta:
{
"error": {
"code": "token_revoked",
"message": "This token has been revoked.",
"details": {}
}
}
Per rotar un token sense tallar el servei, crea una segona credencial, canvia la teva aplicació perquè la faci servir i revoca l'antiga.