Salta al contingut
CA ES
Sol·licita una demo

Desenvolupadors

Canvis i versions

Historial de canvis de l'API v1 i política de versions.

Aquí es recullen els canvis de l'API pública i la política que seguim en modificar-la.

v1.0.0: versió inicial

La primera versió pública de l'API, disponible a /api/v1.

  • Autenticació amb tokens Bearer pck_live_… per club, amb permisos (spaces:read, availability:read, bookings:read, bookings:write, bookings:write_all, players:read, players:write), restricció per espais i caducitat opcional. GET /me.
  • Espais: GET /spaces, GET /spaces/{id}.
  • Disponibilitat i pressupost: GET /availability (fins a 14 dies) i GET /quote.
  • Reserves: GET /bookings, GET /bookings/{id}, POST /bookings (amb Idempotency-Key), PATCH /bookings/{id} i DELETE /bookings/{id} (cancel·lació).
  • Jugadors sincronitzats per external_ref: GET, PUT i DELETE /players/{external_ref}.
  • Webhooks signats amb HMAC-SHA256 per a booking.created, booking.updated i booking.cancelled, amb reintents i desactivació automàtica de l'endpoint.
  • Paginació per cursor, errors amb codis estables i límit de 120 peticions per minut per credencial.

Política de versions

Aquesta API és nova i, de moment, encara no té clients en producció. Fins que en tingui, els canvis es faran directament sobre /api/v1, procurant no trencar el contracte descrit en aquestes guies i a la referència.

A partir del moment en què hi hagi integracions en ús, aplicarem aquestes regles:

  • Canvis compatibles, que no requereixen que facis res: nous endpoints, nous camps opcionals a les peticions, nous camps a les respostes, nous codis d'error o nous tipus d'esdeveniment de webhook. El teu client ha d'ignorar els camps i esdeveniments que no conegui.
  • Canvis incompatibles (treure o canviar el nom d'un camp, canviar un tipus o un significat, endurir una validació): arribaran en una versió nova (/api/v2) i mantindrem l'anterior durant un període de transició que anunciarem amb antelació.
  • Els codis d'error estables, els noms dels permisos i el format del payload dels webhooks formen part del contracte.

L'especificació OpenAPI és la font de veritat del contracte, i aquest historial s'actualitzarà amb cada canvi.