Rivelys API

从您的网站、预订软件或平台预订 Rivelys 私人司机：价格固定，预订前即可知晓，Rivelys 调度中心全程跟进每一个行程。API 免费向所有经过验证的合作伙伴开放。

快速开始

在 rivelys.com 上开通合作伙伴账户，并提交资料审核。
在您的账户中，进入 API 标签页，创建测试密钥（rv_test_…）：预订为模拟，绝不会发送给司机。
集成正常运行后，创建正式密钥（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 调度中心。
限额。每个 IP 地址每分钟 60 次请求。

获取价格

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 调度中心。

预订字段

字段	类型	说明
`service`	字符串	`transfer`（接送）或 `hourly`（包车）。默认：`transfer`。
`pickup_at`	ISO 8601 日期	上车日期和时间，含时区。
`pickup_address`	字符串	上车地址（机场：请注明航站楼）。
`dropoff_address`	字符串	目的地地址（`transfer` 必填）。
`stops`	字符串数组	途经站点（最多 5 个）。
`hours`	数字	`hourly` 的时长（小时，1 至 24，以半小时为单位）。
`flight_number`	字符串	到达航班号（例如 AF7300）：司机会跟踪航班落地。
`passengers`	整数	乘客人数（1 至 8）。
`luggage_hold`, `luggage_cabin`	整数	托运行李和随身行李。
`baby_seats`, `booster_seats`	整数	婴儿座椅和增高座椅。
`pet`	布尔值	乘客携带宠物出行。
`vehicle_type`	字符串	可选：`Business`、`Prestige` 或 `Van`。不指定车型时，行程会提供给所有符合条件的司机。
`passenger`	对象	`name`、`phone`（国际格式）、`language`（`fr`, `en`, `it`, `es`, `de`, `pt`, `ru`, `ar`, `zh`；默认 `fr`）：发给乘客的消息使用其语言。
`notes`	字符串	给司机的备注（最多 1000 个字符）。
`payment`	字符串	`agency_card`、`monthly_invoice` 或 `client_link`。
`client_payment`	字符串	使用 `client_link` 时：`card` 或 `cash`。
`commission_percent`	数字	可选：您在该行程上的佣金（默认使用账户中的设置），司机接单前可见。
`expected_price`	数字	您展示给客户的价格：如果价格有变，预订会被拒绝并返回新价格。
`external_ref`	字符串	您自己的参考号（最多 80 个字符）：防止重复预订。

状态

状态	含义
`searching`	已发布：Rivelys 正在寻找司机。
`awaiting_client`	已有司机接单；乘客需通过链接确认。
`confirmed`	已确认。
`en_route`	司机正在途中。
`on_site`	司机已到达。
`on_board`	乘客已上车。
`completed`	已完成。
`no_show_review`	司机报告乘客未到：调度中心核实中。
`cancelled`	已取消。

错误

出错时返回 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"
  }
}

HTTP	代码	何时
401	`missing_key`, `invalid_key`, `revoked_key`	密钥缺失、未知或已停用。
403	`account_not_active`	账户未通过审核或已被冻结。
403	`live_not_open`	正式预订尚未开放：请使用测试密钥。
403	`monthly_invoice_not_enabled`	您的账户未开通月结发票。
402	`card_required`	没有保存银行卡，无法使用 agency_card 支付。
402	`credit_limit`	已达到月结发票额度上限。
404	`not_found`, `unknown_endpoint`	未知的预订或地址。
409	`price_changed`	价格已变：新价格见响应。
409	`cannot_cancel`	行程已确认：请通过调度中心取消。
422	`invalid_fields`	字段缺失或无效（列表见 `fields`）。
422	`too_soon`	上车时间太近（最短提前时间）。
422	`route_not_found`	无法计算路线：请检查地址。
429	—	请求过多：请一分钟后重试。
503	`api_closed`	API 暂时关闭。

测试密钥

使用 rv_test_… 密钥时，所有内容都按正式环境检查（字段、提前时间、真实价格），但不会发送给司机，也不会计费。预订的参考号为 TEST-…，状态会自动变化：searching 持续 1 分钟，然后由测试司机接单（合作伙伴付款时为 confirmed；使用 client_link 时先为 awaiting_client，一分钟后变为 confirmed）。

帮助

API 相关问题：contact@rivelys.com。如行程正在进行，请在您的账户中联系 Rivelys 调度中心（“联系调度中心”按钮）。