API Rivelys

Начало работы

1. Откройте аккаунт партнёра на rivelys.com и пройдите проверку анкеты.
2. В своём кабинете, на вкладке API, создайте тестовый ключ (rv_test_…): бронирования имитируются и никогда не отправляются водителям.
3. Когда интеграция заработает, создайте боевой ключ (rv_live_…): бронирования становятся настоящими поездками.

Адрес API: https://api.rivelys.com/v1. Передавайте ключ в заголовке Authorization: Bearer rv_…. Обмен данными идёт в JSON (UTF-8), даты — в формате ISO 8601. Храните ключ на своём сервере: никогда не размещайте его на странице, которую видят ваши клиенты.

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

Правила

• Фиксированная цена. Rivelys рассчитывает цену каждой поездки: среднее значение цен свободных подходящих водителей (у каждого свои тарифы), без самой высокой и самой низкой; если водителей слишком мало — эталонная сетка для типа автомобиля. Запросите её через POST /v1/quotes, затем бронируйте, передав эту цену в expected_price: если она за это время изменилась, бронирование отклоняется с новой ценой (код price_changed). После бронирования цена поездки больше не меняется.
• Минимальный срок. Подача должна быть не раньше чем через 48 часов после запроса (текущее значение возвращается в min_notice_hours).
• Оплата, на выбор партнёра: agency_card (ваша карта, сохранённая в кабинете, списание за каждую поездку), monthly_invoice (ежемесячный счёт за завершённые поездки, оплата прямым дебетом SEPA или банковским переводом; включается Rivelys для вашего аккаунта, с лимитом) или client_link (пассажиру отправляется ссылка, он подтверждает поездку и платит водителю картой или наличными).
• Подтверждение. Поездку получает первый проверенный подходящий водитель, который её взял. Если платит партнёр, поездка сразу подтверждена; с client_link пассажир подтверждает её по своей ссылке.
• Никогда не отменяется автоматически. Если ни один водитель не взял поездку, она не отменяется: диспетчерская Rivelys получает оповещение и находит решение.
• Отмена партнёром. Бесплатно, пока поездка не подтверждена (POST /v1/bookings/{id}/cancel). После этого обращайтесь в диспетчерскую Rivelys.
• Лимит. 60 запросов в минуту с одного IP-адреса.

Узнать цену

POST /v1/quotes: те же поля, что и при бронировании (пассажир и оплата необязательны). Ничего не бронируется.

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

Ответ:

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

price_basis: average (среднее по свободным водителям) или reference_grid (эталонная сетка).

Забронировать

POST /v1/bookings: создаёт бронирование (ответ 201). Если external_ref уже отправлялся, возвращается существующее бронирование (ответ 200): после сбоя сети можно безопасно повторить запрос без дублей.

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

Ответ:

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

Отслеживать бронирование

GET /v1/bookings/{id} (например, RV-4F2A9C) возвращает актуальное бронирование. GET /v1/bookings возвращает последние (параметры status и limit, не более 100). Запрашивайте бронирование раз в несколько минут, не чаще одного раза в минуту.

Как только водитель берёт поездку, chauffeur сообщает его имя и автомобиль; после подтверждения — также телефон и номерной знак:

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

Отменить

POST /v1/bookings/{id}/cancel: бесплатно, пока статус searching или awaiting_client. Для подтверждённой поездки ответ — 409 (cannot_cancel): обратитесь в диспетчерскую Rivelys.

Поля бронирования

Статусы

Ошибки

При ошибке возвращаются HTTP-код и объект error с сообщением на английском и французском:

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

Тестовые ключи

С ключом rv_test_… всё проверяется как в боевом режиме (поля, срок, реальная цена), но ничего не отправляется водителям и не оплачивается. Бронирования получают номер TEST-… и сами меняют статус: searching в течение 1 минуты, затем их берёт тестовый водитель (confirmed, если платит партнёр; awaiting_client, а через минуту confirmed с client_link).

Помощь

Вопрос об API: contact@rivelys.com. По текущей поездке обращайтесь в диспетчерскую Rivelys из своего кабинета (кнопка «Связаться с диспетчерской»).