Prenotazioni

Creazione idempotente, stati, modifica concorrente e operazioni manuali.

Creazione e idempotenza

curl -X POST "$TAKO_API_URL/api/v1/bookings" \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "optionId": "option-id",
  "startAt": "2030-06-15T07:00:00Z",
  "unitItems": [
    {
      "unitId": "adult-unit-id",
      "quantity": 2
    }
  ],
  "customer": {
    "firstName": "Ada",
    "lastName": "Esempio",
    "emailAddress": "ada@example.com"
  },
  "notes": "Richiesta dal gestionale",
  "idempotencyKey": "gestionale-a:supplier-42:ordine-123",
  "status": "ON_HOLD"
}'

Invia una chiave idempotente stabile per ordine logico, nel corpo JSON. È univoca nel tenant: includi namespace del gestionale e fornitore. Il riuso restituisce la prenotazione esistente senza confrontare il payload. Anche il retry risponde 201.

Conserva id per le API management; uuid è l’identificatore OCTO. source è api/v1. Non puoi impostare externalId: collega l’ordine tramite idempotencyKey.

Stati e azioni

Stato	Significato	Azione
ON_HOLD	Riserva temporanea; scadenza standard 30 minuti, gestita dal worker.	POST /bookings/{id}/confirm
PENDING	Attesa approvazione, capacità ancora riservata.	POST /bookings/{id}/approve oppure /reject
CONFIRMED	Prenotazione confermata.	PATCH /bookings/{id} oppure POST /bookings/{id}/cancel
CANCELLED / REJECTED / EXPIRED	Stati finali; capacità liberata.	Consultazione; nessuna riapertura.

Ometti status per rispettare il prodotto: CONFIRMED normalmente, PENDING con metadata.directBooking: false. Specificare CONFIRMED in creazione supera il default di approvazione. Confirm, approve e cancel non richiedono body; reject accetta {"reason":"…"}. Ripetere una transizione su uno stato non ammesso produce 409: dopo un timeout rileggi GET.

Modifica concorrente

curl -X PATCH "$TAKO_API_URL/api/v1/bookings/{bookingId}" \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedUpdatedAt": "<updatedAt appena letto con GET>",
  "unitItems": [
    {
      "unitId": "adult-unit-id",
      "quantity": 3
    }
  ]
}'

expectedUpdatedAt evita di sovrascrivere modifiche concorrenti. Serve almeno un cambiamento tra partenza, unitItems, resourceItems, retailPrices o participants. unitItems sostituisce l’intera composizione. Su 409 rileggi e rivaluta.

Rileggi dopo ogni transizione: la risposta può contenere campi precedenti alla scrittura. Il PATCH non cambia optionId, customer o notes. Per prenotazioni canale serve una sottoscrizione BOOKING_UPDATE attiva del canale di origine; senza ricevi 409.

Operazioni manuali

customStart: {localDate,localTime} è alternativo a startAt: crea una partenza manuale nel fuso del prodotto e supera il booking cutoff. Senza tariffa per l’orario, fornisci retailPrices. In modifica puoi scegliere pricingReferenceStartAt.

expandCapacity: true aumenta la capacità per accettare la prenotazione: solo per decisioni operative esplicite. backdated richiede una sessione utente; con API key ricevi 403. participants registra i partecipanti nella vendita RESOURCE.

Il PATCH management supera i cutoff; cancel/reject non applicano il cancellation cutoff. Applica le politiche commerciali prima della chiamata. Nessuna azione esegue pagamenti o rimborsi.