API de recharge et webhooks : guide pratique d’intégration

Les données de recharge restent rarement dans la plateforme de recharge. La finance veut retrouver les coûts d’énergie dans le logiciel comptable, les gestionnaires de flotte veulent la consommation par véhicule à côté des données télématiques, et la direction veut les indicateurs de recharge dans les mêmes tableaux de bord que tout le reste. Copier des fichiers CSV chaque mois fonctionne un temps, mais ne passe pas à l’échelle.

Une API de recharge pour véhicules électriques résout ce problème : elle permet à d’autres systèmes de lire les données de recharge et de réagir automatiquement aux événements de recharge. Ce guide explique pourquoi et où intégrer, la différence entre API REST et webhooks, les données généralement disponibles, comment sécuriser les webhooks avec des signatures HMAC et comment déployer une intégration en toute sécurité. Il comprend un exemple générique en pseudo-code que vous pouvez adapter à n’importe quel langage.

Pourquoi intégrer les données de recharge ?

Un système de gestion de la recharge (CSMS) est la source de référence pour les sessions, l’énergie et l’état des bornes. D’autres systèmes ont besoin d’une partie de ces données :

• ERP et comptabilité : comptabiliser les coûts de recharge par site, service ou centre de coûts sans saisie manuelle.
• Gestion de flotte : ajouter l’énergie par véhicule et par conducteur aux fiches véhicules. Consultez notre guide de la gestion de la recharge de flotte pour comprendre le fonctionnement de l’imputation des coûts.
• Business intelligence (BI) : croiser les données d’utilisation et d’énergie avec les autres données de l’entreprise dans un même outil de reporting.
• Systèmes de gestion immobilière et technique : répartir l’énergie de recharge entre locataires, résidents ou clients d’hôtel.
• Notifications internes : prévenir un répartiteur lorsqu’un véhicule a terminé sa recharge, ou ouvrir un ticket lorsqu’une borne passe en défaut.

L’intégration supprime les tâches manuelles répétitives, réduit les erreurs de ressaisie et rend les données disponibles plus tôt.

API REST ou webhooks

La plupart des plateformes de recharge proposent deux méthodes d’intégration complémentaires.

En pratique, les intégrations robustes utilisent les deux. Les webhooks transmettent rapidement les événements, et un appel REST périodique rapproche les données et comble les éventuels trous, par exemple si votre endpoint était arrêté pour maintenance.

Données typiques d’une API de recharge

• Sessions : heure de début et de fin, borne, point de charge, énergie en kWh, identifiant (badge), conducteur et immatriculation du véhicule lorsqu’ils sont disponibles.
• Bornes et points de charge : identifiants, emplacement, version OCPP, état actuel.
• Conducteurs et badges : quel badge appartient à quel conducteur, et s’il est actif ou bloqué.
• Véhicules : immatriculations et conducteurs auxquels ils sont associés.
• Synthèses d’énergie : totaux par borne, conducteur, véhicule ou période.

Les ressources, noms de champs et filtres exacts varient d’une plateforme à l’autre : travaillez toujours à partir de la documentation officielle de l’API.

Sécurité des webhooks : signatures, idempotence et nouvelles tentatives

Un endpoint de webhook est une URL publique. Toute personne qui la connaît peut y envoyer des requêtes. Trois bonnes pratiques rendent le traitement des webhooks sûr et fiable.

1. Vérifier la signature HMAC

Avec la signature HMAC, la plateforme et votre système partagent un secret. Pour chaque livraison, la plateforme calcule une valeur HMAC-SHA256 sur le corps de la requête à l’aide de ce secret et l’envoie dans un en-tête de signature. Votre système calcule la même valeur et compare les deux. Si elles concordent, la requête provient de quelqu’un qui connaît le secret et le corps n’a pas été modifié en chemin.

• Calculez le HMAC sur le corps brut de la requête, exactement tel qu’il a été reçu. Parser puis resérialiser le JSON peut modifier les espaces ou l’ordre des clés et invalider la signature.
• Comparez les signatures avec une fonction à temps constant pour éviter les attaques temporelles (timing attacks).
• Conservez le secret comme un mot de passe : dans un gestionnaire de secrets ou une variable d’environnement, jamais dans le code source.
• Si la plateforme inclut un horodatage dans les données signées, rejetez les livraisons trop anciennes pour limiter les attaques par rejeu.

2. Rendre les gestionnaires idempotents

La livraison des webhooks suit généralement le principe « au moins une fois ». Un même événement peut arriver deux fois, par exemple lorsque votre réponse s’est perdue sur le réseau. Enregistrez un identifiant de chaque événement traité, comme un ID d’événement si la charge utile en fournit un, ou une combinaison de l’ID de session et du type d’événement, et ignorez les doublons.

3. Répondre vite et gérer les nouvelles tentatives

Renvoyez rapidement un statut de succès (un code 2xx) et effectuez les traitements lourds dans une tâche en arrière-plan. Des gestionnaires trop lents peuvent dépasser le délai d’attente et déclencher de nouvelles livraisons. Vérifiez dans la documentation de la plateforme sa politique de nouvelles tentatives, et utilisez des appels REST planifiés pour rattraper tout ce qui aurait été manqué.

Exemple de flux en pseudo-code

L’exemple suivant montre un gestionnaire de webhook générique qui vérifie la signature, élimine les doublons et place en file d’attente un événement « session arrêtée » pour traitement. Le nom de l’en-tête, les noms d’événements et les champs de la charge utile sont des exemples génériques ; utilisez les valeurs indiquées dans la documentation de l’API de votre plateforme.

function handle_webhook(request):    raw_body  = request.raw_body            # octets, avant tout parsing JSON    received  = request.header(SIGNATURE_HEADER)   # voir la documentation de l’API    secret    = env("WEBHOOK_SECRET")    expected  = hex(hmac_sha256(key = secret, message = raw_body))    if not constant_time_equals(expected, received):        return response(status = 401)    event = json_parse(raw_body)    event_key = event.id or (event.session_id + ":" + event.type)    if processed_events.contains(event_key):        return response(status = 200)       # doublon, déjà traité    processed_events.add(event_key)    queue.push(event)                       # le traitement lourd se fait plus tard    return response(status = 200)function worker(event):    if is_session_stopped(event):        cost_center = lookup_cost_center(event.driver, event.vehicle)        erp.post_energy(cost_center, event.energy_kwh, event.ended_at)function nightly_reconciliation():    sessions = api.get_sessions(date = yesterday)   # REST API, API key    for session in sessions:        if not erp.has_session(session.id):            erp.post_energy(...)

La plupart des langages proposent une fonction HMAC-SHA256 et une fonction de comparaison à temps constant dans leur bibliothèque standard ou dans une bibliothèque de cryptographie reconnue. Utilisez-les plutôt que d’écrire les vôtres.

Intégration avec Üreticy

Üreticy fournit une API REST avec des clés d’API que vous créez et gérez dans le tableau de bord, ainsi que des webhooks signés HMAC pour des événements comme le démarrage et l’arrêt d’une session. La documentation publique de l’API décrit les ressources, les types d’événements, les charges utiles et l’en-tête de signature utilisé pour la vérification.

Comme Üreticy gère les bornes OCPP 1.6J, 2.0.1 et 2.1 dans un seul tableau de bord, une seule intégration peut couvrir un parc de bornes hétérogène. Pour en savoir plus, consultez la page API de recharge et webhooks.

Conseils de déploiement

1. Commencez par un seul cas d’usage. Par exemple, l’énergie mensuelle par centre de coûts transmise à l’ERP.
2. Utilisez une clé d’API distincte par intégration. Vous pourrez ainsi révoquer une intégration sans affecter les autres.
3. Accordez uniquement les droits nécessaires. Une intégration de reporting ne doit pas pouvoir modifier la configuration.
4. Testez avec des sessions réelles. Comparez les résultats de l’API avec le tableau de bord et les rapports exportés avant la mise en production.
5. Journalisez chaque livraison de webhook. Enregistrez l’heure, le type d’événement et le résultat de la vérification de signature pour faciliter le dépannage.
6. Anticipez la rotation des clés. Sachez comment remplacer les clés d’API et les secrets de webhook sans interruption de service.
7. Supervisez l’intégration. Déclenchez une alerte lorsqu’aucun webhook n’arrive pendant une durée inhabituelle ou lorsque le rapprochement détecte des trous.

Lorsque vous comparez des plateformes de recharge, la qualité de l’API et des webhooks mérite sa place dans la check-list. Consultez comment choisir un logiciel OCPP pour une grille d’évaluation complète.

Questions fréquentes

Reliez vos sessions de recharge à votre ERP, à vos outils de gestion de flotte ou de BI grâce à une API REST et à des webhooks signés HMAC. Découvrez l’API de recharge Üreticy ou consultez la documentation de l’API.