VTC Dispatch Developer API

Developer API and webhooks for VTC Dispatch: REST/HMAC integrations, real-time status callbacks, and GPS telemetry. Built for engineering teams.

https://vtcdispatch.fr/docs/api

Aller au contenu

    VTC Dispatch

    Documentation API et webhooks

    VTC Dispatch expose deux webhooks : un webhook entrant qui crée les courses dans le planning à partir des réservations d'un site web, et un webhook sortant qui prévient votre outil lorsqu'une course change d'état. Chaque société dispose de son propre identifiant et de son propre secret ; les données ne sont jamais mélangées entre sociétés. Toutes les requêtes sont en JSON et signées par HMAC SHA-256.

    Webhook entrant : réservations

    Le site de réservation envoie ses événements en POST JSON vers l'URL propre à la société. Le paramètrefleet est l'identifiant de la société dans VTC Dispatch. L'URL complète et le secret sont fournis lors de l'activation de l'intégration ; le secret peut être régénéré à tout moment.

    POST https://<projet>.supabase.co/functions/v1/webhook-rbs?fleet=<ID_SOCIETE>
    Content-Type: application/json
    X-RBS-Signature: t=<horodatage>,v1=<signature>

    Signature

    La signature est un HMAC SHA-256 en hexadécimal. Pour le format t=...,v1=..., le message signé est l'horodatage, un point, puis le corps brut de la requête. Le format « plugin » est aussi accepté : l'en-tête contient directement le HMAC SHA-256 hexadécimal du corps brut (préfixe sha256= possible). Une requête dont la signature est invalide est refusée avec un code 401.

    v1 = HMAC_SHA256(secret, t + "." + corps_brut)   // en hexadécimal

    Événements acceptés

    Le type d'événement est lu dans le champ event (ou event_type, ou type) du corps.

    ÉvénementEffet dans VTC Dispatch
    booking.created, created, new_bookingCrée la course (statut en attente). Une réservation déjà reçue n'est pas dupliquée.
    booking.cancelled, cancelledPasse la course en annulée.
    booking.completed, reservation.completed, completed, trip_completedMet à jour le paiement de la course ; elle reste dans les missions actives.
    tout autre événementAccusé de réception, sans effet.

    Format de la réservation

    La réservation est lue dans data.booking (à défaut booking, puis data, puis le corps entier). Pour chaque information, le premier champ présent est utilisé. Si l'adresse de départ ou d'arrivée est absente, la course est créée avec la mention « à confirmer ». Si la date est absente, elle est fixée à deux heures après la réception.

    {
      "event": "booking.created",
      "data": {
        "booking": {
          "id": "RES-1042",
          "guest_contact": { "first_name": "Camille", "last_name": "Martin", "phone": "+33600000000", "email": "camille@example.com" },
          "pickup_address": "Paris 8e",
          "dropoff_address": "Aéroport Roissy CDG T2",
          "pickup_at": "2026-10-12T08:30:00",
          "vehicle_category": { "label": "Berline" },
          "pax": 2,
          "bags": 2,
          "flight_number": "AF1234",
          "amount_total": 85,
          "payment_method": "card",
          "payment_status": "paid",
          "notes": "Siège bébé"
        }
      }
    }
    InformationChamps reconnusDans la course
    Référenceid, booking_id, referenceidentifiant externe
    Clientguest_contact.first_name + last_name, client_name, customer_name, passenger_namenom du client
    Téléphone, e-mailguest_contact.phone, client_phone, phone ; guest_contact.email, client_email, emailcontact du client
    Départpickup_address, departure, from, origin, pickup_locationadresse de départ
    Destinationdropoff_address, destination, to, dropoff, dropoff_locationadresse d'arrivée
    Date et heurepickup_at, pickup_date, pickup_datetime, datetime, dateprise en charge (fuseau du site, Europe/Paris par défaut)
    Véhiculevehicle_category.label, vehicle_class, vehicle_type, categorytype de véhicule (berline par défaut)
    Passagers, bagagespax, passengers ; bags, luggagenombres
    Volflight_number, flightnuméro de vol
    Prixamount_total, pricing.total, price, total, amountprix client
    Paiementpayment_method, payment_statusmode de paiement
    Remarquesnotes, commentsnotes de la course

    Codes de réponse

    CodeSignification
    200Requête traitée ou événement accusé. Le corps contient success, et course_id pour une création.
    400Paramètre fleet manquant.
    401Signature invalide.
    403Intégration désactivée pour cette société.
    404Société introuvable.
    405Méthode autre que POST.

    Webhook sortant : événements de course

    VTC Dispatch peut appeler votre outil lorsqu'une course change d'état. La société renseigne l'URL de réception et un secret (8 caractères minimum), active l'envoi et choisit les événements voulus. Par défaut, les six événements ci-dessous sont envoyés. Chaque appel est un POST JSON avec un délai maximal de 12 secondes ; un code 2xx indique que l'appel a réussi.

    ÉvénementDéclencheur
    course.createdUne course est créée.
    course.dispatchedUne course est envoyée aux chauffeurs (statut en attente ou dispatchée).
    course.acceptedUn chauffeur accepte la course.
    course.status_changedTout autre changement de statut.
    course.completedLa course est terminée.
    course.cancelledLa course est annulée.
    POST <votre URL>
    Content-Type: application/json
    X-RBS-Signature: t=<horodatage>,v1=<signature>
    X-RBS-Signature-Hex: <signature_du_corps>
    User-Agent: VTCDispatch-Outbound/<version>

    La signature v1 se calcule comme pour le webhook entrant : HMAC SHA-256 de « horodatage.corps_brut », en hexadécimal. L'en-tête X-RBS-Signature-Hex contient le HMAC SHA-256 hexadécimal du corps brut seul. Vérifiez l'une des deux avant de traiter l'appel.

    {
      "id": "evt_1791000000000",
      "event": "course.accepted",
      "created_at": "2026-10-03T08:00:00.000Z",
      "data": {
        "course": {
          "id": "<uuid>",
          "status": "accepted",
          "mission_number": 1042,
          "client_name": "Camille Martin",
          "client_phone": "+33600000000",
          "client_email": "camille@example.com",
          "pickup_date": "2026-10-12T06:30:00Z",
          "departure_location": "Paris 8e",
          "destination_location": "Aéroport Roissy CDG T2",
          "vehicle_type": "berline",
          "passengers_count": 2,
          "luggage_count": 2,
          "flight_number": "AF1234",
          "notes": null,
          "client_price": 85,
          "payment_type": "card",
          "driver_id": "<uuid>",
          "driver_name": "Chauffeur",
          "company_id": "<uuid>",
          "external_booking_id": "RES-1042",
          "external_source": "rbs_web",
          "created_at": "2026-10-03T07:59:00Z",
          "updated_at": "2026-10-03T08:00:00Z"
        },
        "old_status": "pending",
        "new_status": "accepted"
      }
    }

    Limites et contact

    Cette documentation couvre les deux webhooks. VTC Dispatch ne propose pas, à ce jour, d'API REST publique pour lire ou modifier les courses depuis un outil tiers : seuls les échanges décrits ci-dessus sont ouverts aux intégrations.

    Pour activer l'intégration pour votre société, contactez-nous.