Documentation de l'API

Reliez vos boîtiers GPS, votre plateforme télématique ou vos logiciels internes. Spécification complète au format OpenAPI 3.1 : openapi.json

L'API d'intégration est disponible dans les offres qui incluent le module Intégrations. Voir les tarifs

Authentification

L'administrateur de l'entreprise crée une clé dans Paramètres → Intégrations et choisit ses droits. La clé n'est affichée qu'une fois ; elle peut être révoquée à tout moment. Elle désigne l'entreprise : aucun autre en-tête n'est nécessaire.

Authorization: Bearer fk_xxxxxxxxxx.votre-secret

`telemetrie.ecrire`	Envoyer des positions / relevés (boîtier GPS, télématique)
`vehicules.lire`	Lire la liste des véhicules et leur état

Limite : 120 appels par minute et par clé (réponse 429 au-delà). Une entreprise dont l'essai est terminé reçoit 402 sur les envois.

Envoyer des positions et des relevés

POST/api/v1/integrations/telemetrie

Jusqu'à 500 relevés par appel. Le véhicule est désigné par son immatriculation, son N° de parc ou son identifiant. Chaque relevé contient au moins une mesure : position (lat et lng), compteur ou niveau de carburant (carburant_pct). Le compteur suit la nature du véhicule : km pour un véhicule routier, heures pour les heures moteur d'un engin (un km envoyé pour un engin est conservé sans mettre à jour son compteur).

curl -X POST https://mbinkap.com/api/v1/integrations/telemetrie \
  -H "Authorization: Bearer fk_xxxxxxxxxx.votre-secret" \
  -H "Content-Type: application/json" \
  -d '{"releves": [{"vehicule": "LT-1234-AB", "horodatage": "2026-10-09T08:15:00+01:00",
                   "lat": 4.0511, "lng": 9.7679, "km": 125300, "carburant_pct": 62},
                  {"vehicule": "PELLE-07", "horodatage": "2026-10-09T08:15:00+01:00", "heures": 3250}]}'

HTTP/1.1 202 Accepted
{"acceptes": 1, "doublons": 0, "refuses": []}

Renvoyer un lot (après une coupure réseau) ne crée pas de doublon : un relevé déjà reçu pour le même véhicule et la même heure est compté dans « doublons ».
Un relevé supérieur au compteur connu (km d'un véhicule routier, heures d'un engin) met à jour le compteur du véhicule ; un relevé inférieur ne le fait jamais reculer.
Refusés (détail dans « refuses ») : véhicule inconnu, horodatage dans le futur ou de plus de 30 jours, aucune mesure.

Lister les véhicules

GET/api/v1/integrations/vehicules : identifiants, statut, compteur et dernière position connue.

Webhooks

Déclarez une adresse HTTPS dans Paramètres → Intégrations et choisissez les événements. Chaque événement est envoyé en POST JSON :

{"id": "5b0c…", "evenement": "rapport_journalier.soumis", "cree_le": "2026-10-09T18:02:11+01:00",
 "donnees": {"rapport_id": "…", "date": "2026-10-09", "vehicule_id": "…", "km_parcourus": 182, "unite_compteur": "km", "incident": false}}

Pour un engin, unite_compteur vaut « heures » et km_parcourus contient des heures moteur.

`vehicule.cree`	Un véhicule est créé
`vehicule.statut_change`	Le statut d'un véhicule change (disponible, en mission, en maintenance…)
`rapport_journalier.soumis`	Un chauffeur soumet son rapport journalier
`sinistre.declare`	Un sinistre est déclaré
`maintenance.terminee`	Une maintenance est terminée
`carburant.anomalie`	Une anomalie de consommation est détectée sur un plein

Vérifier la signature

L'en-tête X-Flotte-Signature vaut t={horodatage},v1={signature}. Calculez HMAC-SHA256 du texte « horodatage.corps brut » avec le secret du webhook, comparez en temps constant et refusez un horodatage de plus de 5 minutes.

// PHP
[$t, $v1] = sscanf($_SERVER['HTTP_X_FLOTTE_SIGNATURE'], 't=%d,v1=%s');
$attendu = hash_hmac('sha256', $t . '.' . file_get_contents('php://input'), $secret);
if (! hash_equals($attendu, $v1) || abs(time() - $t) > 300) { http_response_code(401); exit; }

Répondez par un code 2xx sous 10 secondes. Sinon, la livraison est retentée après 1 minute, 5 minutes puis 30 minutes. Après 20 échecs consécutifs, le webhook est désactivé (réactivable depuis l'écran Intégrations). Utilisez le champ « id » pour ignorer un événement déjà traité.

Application mobile et routes métier

L'application des chauffeurs utilise /api/v1/auth et /api/v1/mobile avec un jeton par appareil et les en-têtes X-Tenant et X-App-Version. Ces routes sont décrites dans la spécification OpenAPI.

Les routes métier (/api/v1/fuel, /api/v1/incident, /api/v1/maintenance) utilisent le même jeton utilisateur avec l'en-tête X-Tenant et appliquent les droits du rôle de l'utilisateur.