Todas las peticiones (salvo las de los webhooks que recibes tú) se autentican con un token Bearer asociado a una credencial del club.
El token
curl -s "$PRANARP_URL/api/v1/me" \
-H "Authorization: Bearer $PCK_TOKEN"
- Tiene el formato
pck_live_<aleatorio>. - Se crea en Ajustes → Integraciones y se muestra una sola vez. Pranarp Club solo guarda un hash, así que no podemos recuperarlo.
- Pertenece a un club: solo ve los datos de ese club.
- Las llamadas actualizan el «último uso» de la credencial en el panel, como mucho una vez por minuto (y no se actualiza en las respuestas
429), así que puede ir hasta un minuto por detrás.
Trata el token como una contraseña. Si se filtra, revócalo desde el panel: las aplicaciones que lo usen dejarán de funcionar inmediatamente.
Permisos (abilities)
Al crear la credencial eliges qué puede hacer. Si una operación necesita un permiso que no tiene, recibes 403 con insufficient_ability.
| Permiso | Qué permite |
|---|---|
spaces:read |
Listar y leer espacios; pedir un presupuesto (/quote). |
availability:read |
Consultar huecos libres (/availability). |
bookings:read |
Listar y leer reservas, de cualquier origen, de los espacios permitidos. |
bookings:write |
Crear reservas y modificar o cancelar las que ha creado esa misma credencial. |
players:read |
Leer jugadores sincronizados. |
players:write |
Crear, reemplazar y borrar jugadores. |
bookings:write_all |
Permiso amplio: modificar o cancelar cualquier reserva de los espacios permitidos. |
Sin bookings:write_all, intentar modificar o cancelar una reserva que no creó la credencial (por ejemplo, una hecha por el personal del club) devuelve 403 con not_owner. Concede bookings:write_all solo a las integraciones que realmente gestionan todas las reservas.
Espacios permitidos
Una credencial puede limitarse a algunos espacios. En GET /me, el campo space_ids lista los ids permitidos, o es null si puede usar todos. Pedir un espacio fuera de la lista devuelve 403 con space_not_allowed; los listados solo incluyen los permitidos.
Caducidad y revocación
Una credencial puede tener fecha de caducidad (expires_at en /me, con la hora del club) o no caducar nunca. Una vez caducada o revocada, el token deja de funcionar:
| Situación | Estado | Código |
|---|---|---|
| Falta la cabecera, el token no existe o es inválido | 401 | unauthenticated |
| La credencial ha caducado | 401 | token_expired |
| La credencial ha sido revocada | 401 | token_revoked |
El club no tiene activada la función integrations |
403 | feature_disabled |
Ejemplo de respuesta:
{
"error": {
"code": "token_revoked",
"message": "This token has been revoked.",
"details": {}
}
}
Para rotar un token sin cortar el servicio, crea una segunda credencial, cambia tu aplicación para usarla y revoca la antigua.