Partner Distribution & Booking API

1. Accesso e autenticazione

Ogni chiamata operativa deve appartenere a un client autorizzato. Il contratto corrente utilizza una credenziale Bearer consegnata attraverso un canale riservato.

Authorization: Bearer <credential-del-partner>
Accept: application/json
Content-Type: application/json

Per le scritture è previsto Idempotency-Key, così un retry dovuto a timeout o problemi di rete non deve generare involontariamente duplicazioni.

2. Scope disponibili

resources:readavailability:readholds:writebookings:readbookings:write

Gli scope indicano le operazioni consentite, ma non danno accesso a tutte le risorse VS: il client riceve soltanto il perimetro concordato per la propria integrazione.

3. Catalogo risorse

GET /resources.php

Restituisce le risorse che il client è autorizzato a distribuire. Il modello è trasversale: può rappresentare alloggi, auto, scooter, bici/e-bike, barche, parcheggi, postazioni e altre risorse prenotabili, mantenendo campi comuni e condizioni di categoria.

Una risorsa può esporre dati utili alla vendita come descrizione, località, capacità, caratteristiche, quantità, modalità di booking, prezzo, vincoli, extra, condizioni e data di aggiornamento. Per il noleggio può inoltre esporre requisiti applicabili come età conducente, one-way, carburante, chilometraggio, carte accettate, deposito, franchigia e patente.

4. Ricerca disponibilità

POST /availability.php

I campi minimi sono start_at e end_at. Sono disponibili anche categoria, località, gruppo, quantità, extra e un oggetto opzionale rental.

{
  "start_at": "2026-10-10T10:00:00+02:00",
  "end_at": "2026-10-12T10:00:00+02:00",
  "category": "car",
  "quantity": 1,
  "extras": ["child_seat"],
  "rental": {
    "pickup_location": "Brindisi Aeroporto",
    "dropoff_location": "Lecce",
    "driver_age": 42,
    "residence_country": "IT",
    "payment_card_type": "credit",
    "fuel_policy": "full_full",
    "mileage_preference": "unlimited"
  }
}

La risposta include soltanto soluzioni compatibili con il perimetro autorizzato e con i requisiti dichiarati quando questi sono disponibili nel catalogo. La ricerca non crea una prenotazione.

5. Campi specifici per il noleggio

Una ricerca affidabile non può basarsi solo su “auto + date”. Il contesto noleggio è quindi separato dai campi universali e può includere:

Le condizioni specifiche della singola offerta prevalgono sempre sui valori generici. Deposito e franchigia sono concetti distinti e vengono rappresentati separatamente quando il supplier li fornisce.

6. Hold temporaneo

POST /holds.php

L'hold blocca temporaneamente la risorsa durante il checkout. Richiede Idempotency-Key, ricontrolla disponibilità e compatibilità e conserva il contesto noleggio per la successiva conferma.

7. Prenotazioni e informazioni di arrivo

POST /bookings.php — conferma

{
  "action": "confirm",
  "hold_id": "hold_example",
  "partner_booking_reference": "PARTNER-12345",
  "traveler_ref": "customer-reference-opaque",
  "arrival_info": {
    "mode": "flight",
    "reference": "XY1234",
    "scheduled_at": "2026-10-10T08:40:00+02:00"
  }
}

arrival_info è opzionale e può rappresentare volo, treno, traghetto o altro riferimento utile al servizio. Non va raccolto se non serve.

GET /bookings.php?reference=... — lettura

Legge una prenotazione creata nel perimetro dello stesso client.

POST /bookings.php — cancellazione

La cancellazione viene accettata soltanto quando stato e condizioni della prenotazione lo consentono.

8. Codici HTTP ed errori

9. Dati, privacy e sicurezza

• HTTPS obbligatorio.
• Credenziali e secret fuori da URL, pagine pubbliche e repository.
• Scope e perimetro risorsa limitati alla specifica integrazione.
• Idempotenza sulle scritture previste.
• Minimizzazione dei dati personali e uso di riferimenti opachi quando sufficiente.
• Nessun accesso diretto al database VS.
• Nessuna esposizione delle logiche tecnologiche riservate.

10. Versionamento e compatibilità

La famiglia corrente usa /api/partner/v1. La versione del contratto OpenAPI è 0.9.2. Le modifiche compatibili restano nella stessa major family; cambiamenti incompatibili richiedono una nuova versione o una migrazione concordata.

Il contratto machine-readable di riferimento è /api/partner-openapi.json.

11. Onboarding partner

Flusso previsto: definizione del caso d'uso → campi realmente necessari → scope → verifica OpenAPI → credenziali tramite canale riservato → test → verifica funzionale → attivazione.