Une API REST en JSON, à l'adresse https://api.floweet.com/v1. Ces règles valent pour toutes les opérations ; la référence de chaque ressource les rappelle au besoin.
Format des requêtes et des réponses
- JSON seulement : envoyez
Content-Type: application/jsonavec un corps. - Champs en
camelCase; identifiants en UUID (un établissement, par son SIRET de 14 chiffres) ; instants en ISO 8601, en UTC. Une valeur absente vautnull, une liste vide[]: les champs d'un objet de réponse sont toujours présents. - Une ressource est rendue telle quelle ; une liste, sous la forme
{ "data": [...], "nextCursor": "…", "hasMore": true }; une recherche, sous la forme{ "results": [...] }(voir pagination).
Unités
| Grandeur | Unité | Exemple |
|---|---|---|
| Prix d'un carburant | Entier, millièmes d'euro par litre | 2252 = 2,252 €/L |
| Montants (surcoût, économies, ETS2) | Entier, centimes d'euro | 1013800 = 10 138 € |
| Distances, durées | Kilomètres, minutes | distanceKm, durationMin |
| Coordonnées | Degrés décimaux (WGS 84) | { "lat": 45.7485, "lng": 4.8467 } |
| CO2 | Tonnes par an | co2Tonnes |
Statuts de succès
| Statut | Quand | Corps |
|---|---|---|
200 OK | Lecture, calcul, modification | L'objet, une page ou des résultats |
201 Created | Création (prospect, simulation) | L'objet créé, et l'en-tête Location |
200 OK | Suppression | { "ok": true } |
Soyez tolérant
De nouveaux champs, de nouvelles valeurs d'énumération (un statut, une enseigne, un type de véhicule) et de nouveaux codes d'erreur peuvent apparaître sans préavis dans /v1. Ignorez les champs que vous ne connaissez pas et traitez une valeur inconnue comme un cas générique. Voir versions.
En-têtes
| En-tête | Sens | Rôle |
|---|---|---|
Authorization | requête | Bearer fw_live_… ou fw_test_… (authentification) |
Idempotency-Key | requête | Un UUID par opération POST, réutilisé à chaque nouvelle tentative (idempotence) |
Accept-Language | requête | Langue des messages d'erreur : en, fr, es, it, de, pt ; français sans en-tête |
X-Request-Id | les deux | Votre identifiant, renvoyé tel quel (généré sinon) ; citez-le si vous nous contactez |
Floweet-Version | réponse | Version du contrat qui a servi la requête (versions) |
Floweet-Environment | réponse | test ou live : l'environnement de la clé |
Location | réponse | Chemin de la ressource créée par un 201 |
RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset | réponse | Votre fenêtre de limite en cours (limites) |
Retry-After | réponse | Secondes à attendre, sur 429 |
Idempotent-Replayed | réponse | true quand la réponse rejoue une réponse antérieure |
Sources et réutilisation
| Données | Source | Licence |
|---|---|---|
| Prix et stations carburant | prix-carburants.gouv.fr | Licence Ouverte 2.0 |
| Bornes de recharge | Fichier consolidé IRVE (data.gouv.fr) | Licence Ouverte 2.0 |
| Entreprises | Répertoire SIRENE (Insee) | Licence Ouverte 2.0 |
| Adresses (France) | Base Adresse Nationale | Licence Ouverte 2.0 |
| Adresses et itinéraires (ailleurs) | OpenStreetMap | ODbL |
Toute réutilisation publique doit citer ces sources. Un prix compte s'il a moins de 7 jours. La flotte d'une entreprise est une estimation (secteur NAF × tranche d'effectif), jamais une donnée réelle. Chaque appel est inscrit dans un journal d'usage (route, statut, durée ; ni adresse IP, ni contenu), conservé 12 mois.