Rivelys-API

Erste Schritte

1. Eröffnen Sie ein Partnerkonto auf rivelys.com und lassen Sie Ihre Unterlagen prüfen.
2. Erstellen Sie in Ihrem Bereich, Reiter API, einen Testschlüssel (rv_test_…): Buchungen werden simuliert und nie an Chauffeure gesendet.
3. Sobald Ihre Integration funktioniert, erstellen Sie einen Live-Schlüssel (rv_live_…): Buchungen werden zu echten Fahrten.

Adresse der API: https://api.rivelys.com/v1. Senden Sie den Schlüssel im Header Authorization: Bearer rv_…. Anfragen und Antworten sind JSON (UTF-8), Datumsangaben im Format ISO 8601. Bewahren Sie den Schlüssel auf Ihrem Server auf: niemals in einer Seite, die Ihre Kunden sehen können.

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

Die Regeln

• Festpreis. Rivelys berechnet den Preis jeder Fahrt: den Durchschnitt der Preise der verfügbaren, passenden Chauffeure (jeder mit seinen Tarifen), ohne den höchsten und den niedrigsten; bei zu wenigen Chauffeuren den Referenztarif des Fahrzeugtyps. Fragen Sie ihn mit POST /v1/quotes an und buchen Sie dann mit diesem Preis in expected_price: Hat er sich inzwischen geändert, wird die Buchung mit dem neuen Preis abgelehnt (Code price_changed). Nach der Buchung behält die Fahrt ihren Preis.
• Mindestvorlauf. Die Abholung muss mindestens 48 Stunden nach der Anfrage liegen (aktueller Wert in min_notice_hours).
• Zahlung, nach Wahl des Partners: agency_card (Ihre in Ihrem Bereich hinterlegte Karte, Fahrt für Fahrt belastet), monthly_invoice (Monatsrechnung der abgeschlossenen Fahrten, per SEPA-Lastschrift oder Überweisung bezahlt; von Rivelys für Ihr Konto freigeschaltet, mit Obergrenze) oder client_link (ein Link wird an den Fahrgast gesendet, der bestätigt und den Chauffeur per Karte oder bar bezahlt).
• Bestätigung. Der erste geprüfte, passende Chauffeur, der die Fahrt übernimmt, bekommt sie. Zahlt der Partner, ist die Fahrt dann bestätigt; mit client_link bestätigt der Fahrgast sie über seinen Link.
• Nie automatisch storniert. Übernimmt kein Chauffeur die Fahrt, wird sie nicht storniert: Der Rivelys-Dispatch wird benachrichtigt und findet eine Lösung.
• Stornierung durch den Partner. Kostenlos, solange die Fahrt nicht bestätigt ist (POST /v1/bookings/{id}/cancel). Danach wenden Sie sich an den Rivelys-Dispatch.
• Limit. 60 Anfragen pro Minute und IP-Adresse.

Preis anfragen

POST /v1/quotes: dieselben Felder wie bei einer Buchung (Fahrgast und Zahlung sind optional). Es wird nichts gebucht.

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"
  }'

Antwort:

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

price_basis: average (Durchschnitt der verfügbaren Chauffeure) oder reference_grid (Referenztarif).

Buchen

POST /v1/bookings: erstellt die Buchung (Antwort 201). Mit einer bereits gesendeten external_ref wird die bestehende Buchung zurückgegeben (Antwort 200): Nach einem Netzwerkfehler können Sie gefahrlos erneut senden, ohne Doppelbuchung.

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
  }'

Antwort:

{
  "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"
}

Buchung verfolgen

GET /v1/bookings/{id} (zum Beispiel RV-4F2A9C) gibt die aktuelle Buchung zurück. GET /v1/bookings gibt die letzten zurück (Parameter status und limit, höchstens 100). Fragen Sie eine Buchung alle paar Minuten ab, höchstens einmal pro Minute.

Sobald ein Chauffeur die Fahrt übernimmt, nennt chauffeur seinen Namen und sein Auto; nach der Bestätigung auch seine Telefonnummer und das Kennzeichen:

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

Stornieren

POST /v1/bookings/{id}/cancel: kostenlos, solange der Status searching oder awaiting_client ist. Bei einer bestätigten Fahrt lautet die Antwort 409 (cannot_cancel): Wenden Sie sich an den Rivelys-Dispatch.

Felder einer Buchung

Status

Fehler

Ein Fehler liefert einen HTTP-Status und ein error-Objekt mit einer Meldung auf Englisch und Französisch:

{
  "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"
  }
}

Testschlüssel

Mit einem rv_test_…-Schlüssel wird alles wie im Echtbetrieb geprüft (Felder, Vorlauf, echter Preis), aber nichts an Chauffeure gesendet oder berechnet. Buchungen erhalten eine Referenz TEST-… und ändern ihren Status von selbst: searching für 1 Minute, dann übernimmt ein Test-Chauffeur (confirmed, wenn der Partner zahlt; awaiting_client und eine Minute später confirmed mit client_link).

Hilfe

Eine Frage zur API: contact@rivelys.com. Für eine laufende Fahrt wenden Sie sich aus Ihrem Bereich an den Rivelys-Dispatch (Schaltfläche „Die Leitstelle kontaktieren“).