Espais, disponibilitat i pressupost

Abans de crear una reserva has de saber quins espais hi ha, quan són lliures i quant costen. Tres endpoints de només lectura ho resolen.

Llistar espais#

Requereix spaces:read. Retorna els espais actius del club als quals la credencial té accés, ordenats per sort_order i després per id, amb paginació per cursor.

curl -s "$PRANARP_URL/api/v1/spaces?limit=50" \
  -H "Authorization: Bearer $PCK_TOKEN"

{
  "data": [
    {
      "id": 7,
      "name": "Pista 1",
      "code": "P1",
      "sport": "padel",
      "space_type": { "slug": "padel-court", "name": "Pista de pàdel" },
      "indoor": false,
      "surface": "cristall",
      "min_players": 2,
      "max_players": 4,
      "booking_step_minutes": 30,
      "min_booking_minutes": 60,
      "max_booking_minutes": 120,
      "parent_id": null
    }
  ],
  "meta": { "next_cursor": null }
}

GET /spaces/{id} retorna un sol espai. Els espais inactius o eliminats responen 404 not_found, i un espai fora dels permesos de la credencial respon 403 space_not_allowed.

Els camps booking_step_minutes, min_booking_minutes i max_booking_minutes marquen les regles de durada que s'apliquen en reservar: l'hora d'inici i la durada han de respectar el pas, i la durada ha d'estar entre el mínim i el màxim.

Consultar disponibilitat#

Requereix availability:read. Retorna els trams lliures d'un espai dins de [from, to), ja fusionats i amb la diferència horària del club.

curl -s -G "$PRANARP_URL/api/v1/availability" \
  -H "Authorization: Bearer $PCK_TOKEN" \
  --data-urlencode "space_id=7" \
  --data-urlencode "from=2026-10-22T08:00:00+02:00" \
  --data-urlencode "to=2026-10-22T22:00:00+02:00"

{
  "data": {
    "space_id": 7,
    "timezone": "Europe/Madrid",
    "slots": [
      { "starts_at": "2026-10-22T09:00:00+02:00", "ends_at": "2026-10-22T11:30:00+02:00" },
      { "starts_at": "2026-10-22T16:00:00+02:00", "ends_at": "2026-10-22T22:00:00+02:00" }
    ]
  }
}

Què té en compte el càlcul i què has de saber:

• S'apliquen els horaris d'obertura, els descansos, les excepcions, les reserves existents i els bloquejos.
• El rang màxim és de 14 dies; si el superes, reps 422 validation_failed.
• El que ja ha passat no s'ofereix mai: l'instant actual s'arrodoneix cap amunt al següent múltiple de booking_step_minutes (comptat des de la mitjanit local).
• Els trams més curts que la reserva mínima de l'espai (min_booking_minutes, o el valor per defecte del club) es descarten.
• Un tram lliure és un rang continu, no una llista de reserves possibles: dins seu tries un inici i una durada vàlids.
• from i to són ISO 8601 estricte; sense diferència horària s'interpreten a la zona horària del club. Més detalls a Dates i zones horàries.

La disponibilitat és una foto del moment. Encara que un tram aparegui lliure, una altra reserva pot ocupar-lo abans que la teva: en crear la reserva rebràs 409 slot_unavailable si ha passat.

Demanar un pressupost#

Requereix spaces:read. Calcula el preu d'usar un espai entre dos instants amb la tarifa de no soci, sense crear res. Els imports són enters en cèntims.

curl -s -G "$PRANARP_URL/api/v1/quote" \
  -H "Authorization: Bearer $PCK_TOKEN" \
  --data-urlencode "space_id=7" \
  --data-urlencode "starts_at=2026-10-22T18:00:00+02:00" \
  --data-urlencode "ends_at=2026-10-22T19:30:00+02:00"

{
  "data": {
    "space_id": 7,
    "starts_at": "2026-10-22T18:00:00+02:00",
    "ends_at": "2026-10-22T19:30:00+02:00",
    "minutes": 90,
    "total_amount_cents": 3600,
    "currency": "EUR",
    "priced": true,
    "reason": null,
    "segments": [
      { "starts_at": "2026-10-22T18:00:00+02:00", "ends_at": "2026-10-22T19:30:00+02:00", "minutes": 90, "price_unit": "hour", "amount_cents": 3600 }
    ]
  }
}

Si no es pot calcular cap preu, la resposta continua sent 200, amb total_amount_cents: 0, priced: false i un reason:

Els espais inactius, en manteniment, eliminats o d'un altre club responen 404.

De la disponibilitat a la reserva#

Quan hagis triat un tram, crea la reserva amb POST /bookings, tal com es descriu a la referència. Envia sempre una capçalera Idempotency-Key per poder reintentar sense duplicar.