API Rivelys

Iniziare

1. Create un account partner su rivelys.com e fate convalidare il vostro fascicolo.
2. Nel vostro spazio, scheda API, create una chiave di test (rv_test_…): le prenotazioni sono simulate e mai inviate agli autisti.
3. Quando la vostra integrazione funziona, create una chiave reale (rv_live_…): le prenotazioni diventano vere corse.

Indirizzo dell’API: https://api.rivelys.com/v1. Inviate la chiave nell’intestazione Authorization: Bearer rv_…. Gli scambi avvengono in JSON (UTF-8), le date in formato ISO 8601. Tenete la chiave sul vostro server: non mettetela mai in una pagina visibile ai vostri clienti.

curl https://api.rivelys.com/v1 -H "Authorization: Bearer rv_test_••••••••"

Le regole

• Prezzo fisso. Rivelys calcola il prezzo di ogni corsa: la media dei prezzi degli autisti disponibili e compatibili (ognuno con le proprie tariffe), senza il più alto né il più basso; con troppo pochi autisti, la griglia di riferimento del tipo di veicolo. Richiedetelo con POST /v1/quotes, poi prenotate rinviando questo prezzo in expected_price: se nel frattempo è cambiato, la prenotazione viene rifiutata con il nuovo prezzo (codice price_changed). Una volta prenotata, la corsa mantiene il suo prezzo.
• Preavviso minimo. La presa in carico deve avvenire almeno 48 ore dopo la richiesta (valore attuale restituito in min_notice_hours).
• Pagamento, a scelta del partner: agency_card (la vostra carta registrata nel vostro spazio, addebitata corsa per corsa), monthly_invoice (fattura mensile delle corse concluse, pagata con addebito SEPA o bonifico; attivata da Rivelys per il vostro account, con un tetto massimo) oppure client_link (un link viene inviato al passeggero, che conferma e paga l’autista con carta o in contanti).
• Conferma. Il primo autista verificato e compatibile che prende la corsa la ottiene. Se paga il partner, la corsa è allora confermata; con client_link, il passeggero la conferma sul suo link.
• Mai annullata automaticamente. Se nessun autista prende la corsa, non viene annullata: il dispatch Rivelys viene avvisato e trova una soluzione.
• Annullamento da parte del partner. Gratuito finché la corsa non è confermata (POST /v1/bookings/{id}/cancel). Dopo, contattate il dispatch Rivelys.
• Limite. 60 richieste al minuto per indirizzo IP.

Ottenere un prezzo

POST /v1/quotes: stessi campi di una prenotazione (passeggero e pagamento sono facoltativi). Non viene prenotato nulla.

curl https://api.rivelys.com/v1/quotes \
  -H "Authorization: Bearer rv_test_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "transfer",
    "pickup_at": "2026-12-20T14:30:00+01:00",
    "pickup_address": "Aéroport Nice Côte d'Azur, Terminal 2",
    "dropoff_address": "Hôtel de Paris, Monaco",
    "passengers": 2,
    "vehicle_type": "Business"
  }'

Risposta:

{
  "price": 92,
  "currency": "EUR",
  "price_basis": "average",
  "distance_km": 28,
  "duration_min": 40,
  "vehicle_type": "Business",
  "min_notice_hours": 48
}

price_basis: average (media degli autisti disponibili) oppure reference_grid (griglia di riferimento).

Prenotare

POST /v1/bookings: crea la prenotazione (risposta 201). Con un external_ref già inviato, viene restituita la prenotazione esistente (risposta 200): potete riprovare senza rischio di doppioni dopo un’interruzione di rete.

curl https://api.rivelys.com/v1/bookings \
  -H "Authorization: Bearer rv_test_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "AG-2026-00042",
    "service": "transfer",
    "pickup_at": "2026-12-20T14:30:00+01:00",
    "pickup_address": "Aéroport Nice Côte d'Azur, Terminal 2",
    "dropoff_address": "Hôtel de Paris, Monaco",
    "flight_number": "AF7300",
    "passengers": 2,
    "luggage_hold": 2,
    "vehicle_type": "Business",
    "passenger": { "name": "John Smith", "phone": "+44 7700 900123", "language": "en" },
    "notes": "Name sign at arrivals",
    "payment": "agency_card",
    "expected_price": 92
  }'

Risposta:

{
  "id": "RV-4F2A9C",
  "external_ref": "AG-2026-00042",
  "environment": "live",
  "status": "searching",
  "service": "transfer",
  "pickup_at": "2026-12-20T13:30:00.000Z",
  "pickup_address": "Aéroport Nice Côte d'Azur, Terminal 2",
  "dropoff_address": "Hôtel de Paris, Monaco",
  "passengers": 2,
  "vehicle_type": "Business",
  "price": 92,
  "currency": "EUR",
  "payment": "agency_card",
  "passenger": { "name": "John Smith", "phone": "+44 7700 900123", "language": "en" },
  "client_link": "https://rivelys.com/suivi?t=…",
  "chauffeur": null,
  "created_at": "2026-12-01T09:12:44.000Z"
}

Seguire una prenotazione

GET /v1/bookings/{id} (ad esempio RV-4F2A9C) restituisce la prenotazione aggiornata. GET /v1/bookings restituisce le ultime (parametri status e limit, 100 al massimo). Interrogate una prenotazione ogni pochi minuti, non più di una volta al minuto.

Appena un autista prende la corsa, chauffeur indica il suo nome e la sua auto; una volta confermata la corsa, il suo telefono e la targa:

"status": "confirmed",
"chauffeur": {
  "name": "Karim B.",
  "vehicle": "Mercedes-Benz Classe E",
  "color": "Noir",
  "phone": "+33 6 12 34 56 78",
  "plate": "AB-123-CD"
}

Annullare

POST /v1/bookings/{id}/cancel: gratuito finché lo stato è searching o awaiting_client. Per una corsa confermata, la risposta è 409 (cannot_cancel): contattate il dispatch Rivelys.

Campi di una prenotazione

Stati

Errori

Un errore restituisce un codice HTTP e un oggetto error, con un messaggio in inglese e in francese:

{
  "error": {
    "code": "price_changed",
    "message": "The price is now 95 EUR. Check it and send the booking again with this expected_price.",
    "message_fr": "Le prix vient d’être recalculé : 95 €.",
    "price": 95,
    "currency": "EUR"
  }
}

Chiavi di test

Con una chiave rv_test_…, tutto viene verificato come in reale (campi, preavviso, prezzo reale), ma nulla viene inviato agli autisti né fatturato. Le prenotazioni hanno un riferimento TEST-… e cambiano stato da sole: searching per 1 minuto, poi un autista di test le prende (confirmed se paga il partner; awaiting_client poi confirmed un minuto dopo con client_link).

Assistenza

Una domanda sull’API: contact@rivelys.com. Per una corsa in corso, contattate il dispatch Rivelys dal vostro spazio (pulsante «Contattare la centrale operativa»).