Intégrer le calcul tarifaire CRE dans le CRM de votre cabinet via l'API REST EDP

L'API REST publique d'Energy Data Platform permet d'appeler le moteur de calcul tarifaire CRE (gaz et électricité) directement depuis le CRM ou les outils internes d'un cabinet courtier. Ce guide pratique présente l'authentification, le throttle, l'endpoint principal, deux exemples d'appel concrets et les cas d'usage cabinet les plus fréquents.

À qui s'adresse l'API EDP

L'API est principalement utilisée par les cabinets de courtage qui veulent automatiser une étape récurrente de leur process - typiquement la simulation tarifaire à la création d'un dossier client - sans passer par l'interface web. Elle est également utilisée par quelques ETI clientes en direct, qui pilotent leur portefeuille énergie depuis leurs propres outils internes.

Authentification : X-API-Key

Toutes les requêtes vers l'API EDP s'authentifient avec une clé API transmise dans le header HTTP X-API-Key. Une clé API est rattachée à une organisation cabinet et hérite de ses droits (portefeuille accessible, plan tarifaire actif).

• La clé est générée depuis l'espace cabinet dans EDP, section « API ».
• Elle se présente sous la forme edp_ suivi de 32 caractères hexadécimaux.
• Une clé peut être révoquée à tout moment sans impact sur les autres clés actives de l'organisation.

Throttle : 60 requêtes par minute

L'API applique une limite de débit standard de 60 requêtes par minutepar clé API. Cette limite couvre largement les usages cabinet typiques (création de dossier client en temps réel, refresh d'un dashboard portefeuille). Pour des traitements batch très volumineux, EDP recommande l'usage du module batch CSV dédié plutôt qu'un appel boucle sur l'API.

Lorsque la limite est atteinte, l'API répond avec un code HTTP 429 Too Many Requests et un header Retry-After indiquant le délai de réessai. Tout client API correctement implémenté doit gérer ce cas avec un backoff.

Documentation Swagger publique

La documentation interactive complète de l'API est accessible publiquement sur/api/docs/ - c'est la source de référence à jour, générée automatiquement à partir du schéma OpenAPI du backend. Elle permet de tester chaque endpoint depuis le navigateur, de visualiser les schémas de requête et de réponse, et de récupérer les exemples de payload.

Endpoint principal : POST /api/v1/simulator/calculate

Le cœur de l'API courtier est l'endpoint de calcul de simulation tarifaire. Il accepte une description de site (gaz ou électricité) et renvoie le détail de la facture annuelle prévisionnelle, avec ventilation par composante (réseau, fourniture, taxes).

Exemple 1 - Simulation gaz PITD T3

Cas typique : un cabinet crée un dossier pour un nouveau site tertiaire, on connaît la zone PITD du site (code commune INSEE), la consommation annuelle estimée et le tarif PITD.

curl -X POST https://api.energydataplatform.fr/api/v1/simulator/calculate \
  -H "X-API-Key: $EDP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "commodity": "gas",
    "pitd_code": "GD0312345",
    "tarif": "T3",
    "annual_consumption_mwh": 2500,
    "fournisseur_offre": {
      "abonnement_eur_mois": 95,
      "molecule_eur_mwh": 32.5
    }
  }'

La réponse renvoie le détail de la facture annuelle, ventilée entre :

• Acheminement distribution (terme fixe + terme proportionnel ATRD)
• Acheminement transport (quote-part ATRT pour T3)
• Composantes de fourniture (abonnement + molécule)
• TICGN et CTA
• Total HT et total TTC

Exemple 2 - Simulation électricité C3 (HTA courte utilisation)

Cas typique : un site tertiaire raccordé HTA, courte utilisation, dont on connaît la puissance souscrite et la répartition horosaisonnière de la consommation annuelle.

curl -X POST https://api.energydataplatform.fr/api/v1/simulator/calculate \
  -H "X-API-Key: $EDP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "commodity": "electricity",
    "segment": "C3",
    "puissance_souscrite_kva": 250,
    "consommation_horosaisonniere_kwh": {
      "HPH": 320000,
      "HCH": 180000,
      "HPE": 240000,
      "HCE": 150000,
      "Pointe": 35000
    },
    "fournisseur_offre": {
      "abonnement_eur_mois": 0,
      "energie_eur_mwh": {
        "base": 95.0
      }
    }
  }'

La réponse intègre les composantes TURPE 7 (CRE 2025-78) classe par classe, la CTA appliquée correctement sur les seules parts fixes, l'accise sur l'électricité et la composante de fourniture telle que définie dans l'offre.

Cas d'usage cabinet

Automatiser la simulation à la création d'un dossier client

Dans le CRM cabinet (HubSpot, Pipedrive, Zoho, ou outil maison), un nouveau dossier client est créé avec ses informations site (PCE, PRM, conso annuelle, tarif PITD ou segment Enedis). Un workflow déclenche automatiquement un appel à l'API EDP pour produire la simulation de référence, qui est rattachée au dossier dans le CRM. Bénéfice cabinet : un consultant n'ouvre plus l'interface EDP manuellement pour chaque dossier - la simulation est prête au moment où il consulte le dossier.

Alimenter un dashboard portefeuille avec les coûts réseau prévisionnels

Un cabinet qui suit 100 à 200 PCE/PRM peut centraliser dans un dashboard interne (Looker Studio, Metabase, Tableau, ou dashboard maison) le coût réseau prévisionnel de chaque site, mis à jour automatiquement par appel à l'API EDP à fréquence hebdomadaire ou mensuelle. Le dashboard fait apparaître les sites en hausse, les sites mal classés, l'effet d'une révision tarifaire CRE sur la facture cumulée du portefeuille. Bénéfice cabinet : reporting client automatisé et démonstration de valeur récurrente.

Recalcul rétroactif intégré au workflow d'audit

L'endpoint accepte un paramètre de date d'effet, qui permet de recalculer une facture sur un barème historisé (cf. l'article méthodologie audit rétroactif). Cela permet d'industrialiser la phase de recalcul d'un audit rétroactif : chargement des factures historiques côté CRM cabinet, appel API par PCE/PRM et par exercice, agrégation des écarts dans un livrable client.

Bonnes pratiques d'intégration

• Idempotence : un même payload produit la même simulation, on peut donc en cacher le résultat côté CRM tant que ni les barèmes officiels ni les paramètres du site n'ont évolué.
• Gestion d'erreurs : prévoir un retry exponentiel sur 5xx, et un respect strict du Retry-After sur 429.
• Versioning : l'API est versionnée (/api/v1/) ; la stabilité des contrats est garantie pour la durée de vie d'une version majeure.
• Logs côté cabinet : conserver dans le CRM la corrélation « dossier client → date d'appel API → version barème CRE utilisée ». Indispensable pour la traçabilité des audits.

Roadmap d'extension

EDP prévoit une extension de la surface API pour intégrer davantage de cas d'usage cabinet (gestion programmatique du portefeuille, déclenchement d'audits batch, webhook de notification de révision tarifaire CRE). Ces extensions seront publiées au fil de l'eau dans la documentation Swagger et annoncées en avant-première aux cabinets clients sur les plans Pro et Enterprise.

Conclusion

L'API REST EDP est conçue pour s'intégrer simplement aux outils existants d'un cabinet courtier. Authentification X-API-Key, throttle clair, endpoint unique pour le calcul tarifaire CRE gaz et électricité, doc Swagger publique : un développeur côté cabinet peut câbler une première intégration en moins d'une journée et passer en production sur ses premiers dossiers clients dans la foulée.