Come possiamo aiutarti?

ParkFlow.io è una piattaforma centralizzata (channel manager) che collega gli operatori di parcheggi aeroportuali con vari canali di vendita come agenzie di viaggio online (OTA), aggregatori, broker e siti B2C. Funge da sistema middleware, semplificando la gestione delle prenotazioni per i parcheggi sincronizzando prenotazioni, aggiornamenti e cancellazioni da più fonti in un'interfaccia unificata. ParkFlow si basa principalmente su un modello di integrazione pull-based, in cui recupera periodicamente i dati di prenotazione dalle API dei partner.

Questa guida è destinata ai fornitori di servizi esterni (es. OTA, broker, marketplace) che desiderano integrarsi con ParkFlow e inviare le proprie prenotazioni tramite un'API.

Modello Operativo

ParkFlow esegue job pianificati che recuperano prenotazioni nuove o aggiornate dall'API di ciascun partner. Questi job vengono tipicamente eseguiti:

- Ogni 2–10 minuti in produzione
- Ogni 15–30 minuti in modalità test

Questo garantisce che l'operatore del parcheggio disponga di informazioni aggiornate sugli arrivi imminenti e sui requisiti del servizio. 

Casi d'Uso Coperti

- Recupero di nuove prenotazioni confermate
- Rilevamento di aggiornamenti ai dati di volo o del cliente
- Acquisizione delle cancellazioni
- Gestione delle modifiche dell'ultimo minuto vicino all'orario di check-in

Requisiti API

Se il proprietario di un parcheggio dispone di più offerte (es. parcheggi o prodotti diversi) nel sistema esterno, ParkFlow stabilirà un'integrazione separata per ciascuna offerta per garantire una mappatura accurata, la sincronizzazione della disponibilità e dei prezzi.

Per integrarsi senza problemi, i partner esterni devono esporre una REST API pubblica che supporti quanto segue:

Autenticazione

ParkFlow supporta più schemi:

- Bearer Token: Authorization: Bearer <token>
- Basic Auth: utente:password codificato in base64
- API Key: Passata nell'header (preferito) o come parametro di query

Nota: Le credenziali vengono archiviate e gestite in modo sicuro all'interno della piattaforma ParkFlow.

Endpoint

ParkFlow richiede un solo endpoint obbligatorio:

GET /bookings – Questo endpoint deve restituire un elenco di tutte le prenotazioni create, aggiornate o cancellate a partire da un determinato momento. ParkFlow lo utilizza per sincronizzare i dati in modo affidabile dal sistema esterno.

L'oggetto prenotazione deve contenere le seguenti informazioni:

- Le date di arrivo e partenza devono essere nel fuso orario locale

- Le date di creazione e aggiornamento devono essere in UTC-0

- Prezzo, importo prepagato e valuta

- Stato della prenotazione

- Numero di veicoli e targhe

- Numero di riferimento

Endpoint opzionali:

- Blocco della Disponibilità

Consente a ParkFlow di informare il sistema esterno quando un determinato prodotto di parcheggio non è più disponibile in date specifiche.

Esempio:

POST /parkings/{id}/locks

Body: { "date": "2025-07-15", "reason": "full" }

- Notifica dello Stato della Prenotazione

Consente a ParkFlow di notificare al sistema esterno le cancellazioni o i no-show avviati dal parcheggio.

Esempio:

POST /bookings/{id}/cancel

Body: { "reason": "no_show" }

- Aggiornamenti dei Prezzi

 Consente a ParkFlow di inviare dati di prezzi stagionali o base per specifiche offerte di parcheggio.

 Esempio:

 POST /parkings/{id}/pricing

 Body: { "type": "seasonal", "valid_from": "...", "valid_until": "...", "prices": [6500, ... }

Raccomandazioni per l'Integrazione

- Garantire risposte accurate e tempestive

- Evitare la memorizzazione nella cache di dati obsoleti

- Consentire a ParkFlow di configurare la frequenza di polling

- Supportare la paginazione per grandi volumi di prenotazioni

- Fornire un ambiente sandbox/di test con dati di prova

Requisiti di Sicurezza

- Tutti gli endpoint devono utilizzare HTTPS

- Utilizzare metodi di autenticazione sicuri (preferire quelli basati su token)

- Limitare l'accesso tramite whitelist di IP, se possibile

- Evitare di conservare dati sensibili dei clienti oltre quanto strettamente necessario