API Rivelys

Começar

1. Crie uma conta de parceiro em rivelys.com e peça a validação do seu processo.
2. No seu espaço, separador API, crie uma chave de teste (rv_test_…): as reservas são simuladas e nunca enviadas aos motoristas.
3. Quando a sua integração funcionar, crie uma chave real (rv_live_…): as reservas tornam-se viagens reais.

Endereço da API: https://api.rivelys.com/v1. Envie a chave no cabeçalho Authorization: Bearer rv_…. As trocas fazem-se em JSON (UTF-8) e as datas no formato ISO 8601. Guarde a chave no seu servidor: nunca a coloque numa página visível pelos seus clientes.

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

As regras

• Preço fixo. A Rivelys calcula o preço de cada viagem: a média dos preços dos motoristas disponíveis e compatíveis (cada um com as suas tarifas), sem o mais alto nem o mais baixo; com poucos motoristas, a grelha de referência do tipo de veículo. Peça-o com POST /v1/quotes e depois reserve reenviando esse preço em expected_price: se entretanto tiver mudado, a reserva é recusada com o novo preço (código price_changed). Depois de reservada, a viagem mantém o seu preço.
• Antecedência mínima. A recolha deve ser pelo menos 48 horas após o pedido (valor atual devolvido em min_notice_hours).
• Pagamento, à escolha do parceiro: agency_card (o seu cartão registado no seu espaço, cobrado viagem a viagem), monthly_invoice (fatura mensal das viagens concluídas, paga por débito direto SEPA ou transferência; ativada pela Rivelys para a sua conta, com um limite) ou client_link (é enviado um link ao passageiro, que confirma e paga ao motorista com cartão ou em numerário).
• Confirmação. O primeiro motorista verificado e compatível que aceita a viagem fica com ela. Se o parceiro pagar, a viagem fica então confirmada; com client_link, o passageiro confirma-a no seu link.
• Nunca cancelada automaticamente. Se nenhum motorista aceitar a viagem, ela não é cancelada: o dispatch Rivelys é alertado e encontra uma solução.
• Cancelamento pelo parceiro. Gratuito enquanto a viagem não estiver confirmada (POST /v1/bookings/{id}/cancel). Depois, contacte o dispatch Rivelys.
• Limite. 60 pedidos por minuto e por endereço IP.

Obter um preço

POST /v1/quotes: os mesmos campos de uma reserva (o passageiro e o pagamento são facultativos). Nada é reservado.

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

Resposta:

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

price_basis: average (média dos motoristas disponíveis) ou reference_grid (grelha de referência).

Reservar

POST /v1/bookings: cria a reserva (resposta 201). Com um external_ref já enviado, é devolvida a reserva existente (resposta 200): pode tentar de novo sem risco de duplicados após uma falha de rede.

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

Resposta:

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

Acompanhar uma reserva

GET /v1/bookings/{id} (por exemplo RV-4F2A9C) devolve a reserva atualizada. GET /v1/bookings devolve as últimas (parâmetros status e limit, 100 no máximo). Consulte uma reserva de poucos em poucos minutos, não mais do que uma vez por minuto.

Assim que um motorista aceita a viagem, chauffeur indica o seu nome e o seu carro; depois de confirmada a viagem, o seu telefone e a 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 enquanto o estado for searching ou awaiting_client. Para uma viagem confirmada, a resposta é 409 (cannot_cancel): contacte o dispatch Rivelys.

Campos de uma reserva

Estados

Erros

Um erro devolve um código HTTP e um objeto error, com uma mensagem em inglês e em 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"
  }
}

Chaves de teste

Com uma chave rv_test_…, tudo é verificado como em real (campos, antecedência, preço real), mas nada é enviado aos motoristas nem faturado. As reservas têm uma referência TEST-… e mudam de estado sozinhas: searching durante 1 minuto, depois um motorista de teste aceita-as (confirmed se o parceiro pagar; awaiting_client e depois confirmed um minuto mais tarde com client_link).

Ajuda

Uma pergunta sobre a API: contact@rivelys.com. Para uma viagem em curso, contacte o dispatch Rivelys a partir do seu espaço (botão «Contactar a central de operações»).