Schéma technique

Description du schema d'envoi des trajets par opérateur.

Schema JSON pour l'envoi des trajets sur la route POST /v2/journeys Le schéma de données est présenté au format JSON Schema Draft-07.

Le schéma complet est disponible sur la documentation technique.

Les unités utilisées pour les valeurs sont :

• montants financiers en centimes d'Euros

• distances en mètres

• durées en secondes

Trajet

* Données obligatoires

• journey_id* : générée par l'opérateur et doit être unique (couple passager-conducteur)

• operator_journey_id : générée par l'opérateur pour regrouper des trajets (plusieurs passagers avec un même conducteur)

• operator_class* : la classe de preuve correspondant au spécifications définies dans Classes de preuve de covoiturage.

Identité de l'occupant

Ces données personnelles permettent d'identifier la personne effectuant le covoiturage afin de pouvoir comptabiliser ses trajets et lui distribuer des incitations en fonction des politiques applicables.

Les propriétés suivantes sont dans les objets : passenger.identity et driver.identity

• firstname : Prénom de l'occupant

• lastname : Nom de l'occupant

• email : Email de l'occupant

• company : Nom de l'organisation / employeur

• travel_pass : Carte de transport (TCL, Navigo, Trabool, etc.) possédée par l'occupant. Le numéro est obligatoire si l'information est disponible.

Deux options sont disponibles pour la transmission du numéro de téléphone.

1. Numéro complet à 10 chiffres (ex. 06 12 34 56 78)

2. Numéro tronqué à 8 chiffres + identifiant unique de l'opérateur (ex. 06 12 34 56 + 12345)

• phone : Numéro complet à 10 chiffres au format ITU E.164 ([phone])

• phone_trunc : Numéro tronqué à 8 chiffres

• operator_user_id : Identifiant de l'utilisateur chez l'opérateur

phone_trunc et operator_user_id dépendent l'un de l'autre.

La clé suivante n'est applicable qu'au passager :

• over_18 : Le passager est majeur (TRUE) ou mineur (FALSE) ou non communiqué (NULL)

Liste des passes transport supportés

Pour le moment, seul le passe navigo est supporté.

Données géographiques

Les points de départ et d'arrivée du passager et du conducteur. passenger.start, passenger.end, driver.start, driver.end

• datetime * Date et heure du départ/arrivée au format ISO 8601 (YYYY-MM-DDThh:mm:ssZ).

  L'heure est exprimée en UTC (Coordinated Universal Time). UTC n'est pas ajusté sur l'heure d'été et hiver !

• lat Latitude comprise entre 90deg et -90deg décimaux en datum WSG-84

• lon Longitude comprise entre 180deg et -180deg décimaux en datum WSG-84

Données financières

L'objectif est de coller au plus près avec la réalité comptable (transaction usager) et d'avoir suffisamment d'informations pour recalculer le coût initial du trajet. Ceci afin de s'assurer du respect de la définition du covoiturage et de la bonne application des politiques incitatives gérées par le registre.

• passenger.contribution* : Coût réel total du service pour l’occupant passager en fonction du nombre de sièges réservés APRÈS que toutes les possibles incitations aient été versées (subventions employeurs, promotions opérateurs, incitations AOM, etc).

• driver.revenue* : La somme réellement perçue par le conducteur APRÈS que toutes les incitations (subventions employeurs, promotions opérateurs, incitations AOM, etc.), contributions des passagers aient été versées et que la commission de l’opérateur soit prise.

• passenger.seats* : Nombre de sièges réservés par l'occupant passager. Défault : 1

Incitations

• incentives * : Tableau reprenant la liste complète des incitations appliquées (ordre d'application, montant, identifiant de l'incitateur). Si aucune incitation, envoyer un tableau vide : []

{
    index: <Number> *         // ordre d'application [0,1,2]
    amount: <Number> *        // montant de l'incitation en centimes d'euros
    siret: <String> *         // Numéro SIRET de l'incitateur
}

Le SIRET est un identifiant unique par structure juridique. Toutes les entités incitatrices en possèdent un.

Ordre d'application des incitations

Par défaut, l'ordre d'application des politiques incitatives est le suivant :

1. Territoire (AOM, Région, ...)

2. Sponsors (incitations employeur, CE, etc.)

3. Opérateur (opération promotionnelle, offres, etc.)

Titre-Mobilité

La prise en charge des frais de transports personnel (carburant et forfait mobilité) pourra prendre la forme d’une solution de paiement spécifique, dématérialisée et prépayée, intitulée « titre-mobilité ». Ainsi, il apparaît comme pertinent de détailler la solution de paiement utilisée dans le cadre d'un trajet covoituré, s'il s'agit de Titre-Mobilité.

• payments : Zéro, une ou plusieurs méthodes de paiement utilisées (ex. carte employeur préchargée permettant de payer directement le covoiturage sur une application).

{
    index: <Number> *    // ordre d'application (0, 1, 2, ...)
    siret: <String> *    // n° SIRET de l'établissement payeur
    type: <String> *     // nom du titre
    amount: <Number> *   // montant en centimes d'euros
}