API de Rivelys

Empezar

1. Cree una cuenta de socio en rivelys.com y haga validar su expediente.
2. En su espacio, pestaña API, cree una clave de prueba (rv_test_…): las reservas son simuladas y nunca se envían a los conductores.
3. Cuando su integración funcione, cree una clave real (rv_live_…): las reservas se convierten en trayectos reales.

Dirección de la API: https://api.rivelys.com/v1. Envíe la clave en la cabecera Authorization: Bearer rv_…. Los intercambios se hacen en JSON (UTF-8) y las fechas en formato ISO 8601. Guarde la clave en su servidor: nunca la ponga en una página visible para sus clientes.

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

Las reglas

• Precio fijo. Rivelys calcula el precio de cada trayecto: la media de los precios de los conductores disponibles y compatibles (cada uno con sus tarifas), sin el más alto ni el más bajo; con muy pocos conductores, la tabla de referencia del tipo de vehículo. Pídalo con POST /v1/quotes y luego reserve enviando ese precio en expected_price: si ha cambiado mientras tanto, la reserva se rechaza con el nuevo precio (código price_changed). Una vez reservado, el trayecto conserva su precio.
• Plazo mínimo. La recogida debe ser al menos 48 horas después de la solicitud (valor actual devuelto en min_notice_hours).
• Pago, a elección del socio: agency_card (su tarjeta registrada en su espacio, cobrada trayecto a trayecto), monthly_invoice (factura mensual de los trayectos terminados, pagada por adeudo SEPA o transferencia; activada por Rivelys para su cuenta, con un límite) o client_link (se envía un enlace al pasajero, que confirma y paga al conductor con tarjeta o en efectivo).
• Confirmación. El primer conductor verificado y compatible que toma el trayecto lo obtiene. Si paga el socio, el trayecto queda confirmado; con client_link, el pasajero lo confirma en su enlace.
• Nunca se cancela automáticamente. Si ningún conductor toma el trayecto, no se cancela: el dispatch de Rivelys recibe una alerta y encuentra una solución.
• Cancelación por el socio. Gratuita mientras el trayecto no esté confirmado (POST /v1/bookings/{id}/cancel). Después, contacte con el dispatch de Rivelys.
• Límite. 60 solicitudes por minuto y por dirección IP.

Obtener un precio

POST /v1/quotes: los mismos campos que una reserva (el pasajero y el pago son opcionales). No se reserva nada.

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

Respuesta:

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

price_basis: average (media de los conductores disponibles) o reference_grid (tabla de referencia).

Reservar

POST /v1/bookings: crea la reserva (respuesta 201). Con un external_ref ya enviado, se devuelve la reserva existente (respuesta 200): puede reintentar sin riesgo de duplicados tras un corte de red.

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

Respuesta:

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

Seguir una reserva

GET /v1/bookings/{id} (por ejemplo RV-4F2A9C) devuelve la reserva actualizada. GET /v1/bookings devuelve las últimas (parámetros status y limit, 100 como máximo). Consulte una reserva cada pocos minutos, no más de una vez por minuto.

En cuanto un conductor toma el trayecto, chauffeur indica su nombre y su coche; una vez confirmado el trayecto, su teléfono y la matrícula:

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

Cancelar

POST /v1/bookings/{id}/cancel: gratuito mientras el estado sea searching o awaiting_client. Para un trayecto confirmado, la respuesta es 409 (cannot_cancel): contacte con el dispatch de Rivelys.

Campos de una reserva

Estados

Errores

Un error devuelve un código HTTP y un objeto error, con un mensaje en inglés y en francés:

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

Claves de prueba

Con una clave rv_test_…, todo se comprueba como en real (campos, plazo, precio real), pero no se envía nada a los conductores ni se factura nada. Las reservas tienen una referencia TEST-… y cambian de estado solas: searching durante 1 minuto, luego un conductor de prueba las toma (confirmed si paga el socio; awaiting_client y luego confirmed un minuto después con client_link).

Ayuda

Una pregunta sobre la API: contact@rivelys.com. Para un trayecto en curso, contacte con el dispatch de Rivelys desde su espacio (botón «Ponte en contacto con la central de operaciones»).