API et intégration technique CEE

API et intégration technique CEE : automatisez vos processus de subventions énergétiques

L'intégration technique des services de Certificats d'Économies d'Énergie représente un enjeu majeur pour les entreprises du secteur énergétique, les installateurs de solutions d'efficacité énergétique et les plateformes de gestion de travaux. Notre API CEE permet d'automatiser l'ensemble du parcours, depuis la vérification d'éligibilité jusqu'à la facturation finale, en passant par le dépôt et le suivi des dossiers.

À lire aussi : CEE grands comptes pour approfondir cet aspect.

Cette documentation technique s'adresse aux développeurs, intégrateurs et responsables IT souhaitant connecter leurs systèmes d'information aux services CEE. Nous détaillons ici les fonctionnalités disponibles, les endpoints principaux, les formats de données et les bonnes pratiques d'intégration.

Pour aller plus loin : Suivi et pilotage de projets CEE saura vous intéresser.

Architecture générale de l'API CEE

Notre API repose sur une architecture REST moderne, conçue pour offrir fiabilité, performance et simplicité d'utilisation. L'ensemble des échanges s'effectue au format JSON, avec une authentification sécurisée par tokens Bearer.

Caractéristiques techniques principales

Environnements disponibles

Nous mettons à disposition deux environnements distincts pour faciliter vos développements et tests :

• Environnement de sandbox : permet de tester l'intégralité des fonctionnalités sans impacter les données de production. Aucune transaction réelle n'est effectuée, les données sont simulées.
• Environnement de production : utilisé pour les opérations réelles avec traitement effectif des dossiers CEE et gestion financière complète.

Authentification et sécurité

La sécurité des échanges constitue une priorité absolue. Notre système d'authentification garantit la confidentialité et l'intégrité des données transmises.

Vous serez peut-être intéressé par : Offre CEE sur-mesure sur le sujet.

Obtention des credentials API

Pour accéder à l'API, vous devez d'abord créer un compte partenaire et générer vos clés d'accès depuis votre espace développeur. Chaque application connectée dispose de ses propres identifiants :

• Client ID : identifiant public de votre application
• Client Secret : clé secrète à conserver de manière sécurisée
• API Key : clé supplémentaire pour certaines opérations sensibles

Flux d'authentification OAuth 2.0

L'authentification suit le standard OAuth 2.0 avec le flux Client Credentials, particulièrement adapté aux intégrations serveur à serveur. Le processus se déroule en deux étapes :

Gestion des tokens et renouvellement

Les tokens d'accès ont une durée de vie limitée à une heure pour des raisons de sécurité. Votre application doit gérer automatiquement le renouvellement avant expiration. Nous recommandons d'implémenter un mécanisme de refresh 5 minutes avant l'expiration du token en cours.

Endpoints principaux et fonctionnalités

L'API propose un ensemble complet d'endpoints couvrant l'intégralité du cycle de vie d'un dossier CEE. Chaque endpoint est documenté avec ses paramètres, codes de retour et exemples d'utilisation.

Vérification d'éligibilité

Avant de créer un dossier, vérifiez l'éligibilité d'un projet aux différentes primes CEE disponibles. Cet endpoint analyse les critères techniques et géographiques pour déterminer les aides applicables.

Endpoint : POST /api/v1/eligibility/check

Paramètres requis :

• type_travaux : catégorie de travaux (isolation, chauffage, ventilation...)
• code_postal : localisation du projet
• surface_logement : superficie en m²
• type_logement : maison ou appartement
• energie_chauffage : type d'énergie utilisée
• revenu_fiscal : revenu fiscal de référence du bénéficiaire

Exemple de réponse :

La réponse contient la liste des primes applicables avec leur montant estimé, les conditions spécifiques à respecter et les documents nécessaires au dépôt du dossier.

Création et dépôt de dossiers

Une fois l'éligibilité confirmée, créez un nouveau dossier CEE en fournissant l'ensemble des informations requises. Le système valide automatiquement la cohérence des données et la conformité réglementaire.

Endpoint : POST /api/v1/dossiers

Données obligatoires :

• Informations bénéficiaire (identité, coordonnées, revenus)
• Caractéristiques du logement (adresse, surface, type, année construction)
• Détails des travaux (nature, équipements, performances)
• Informations installateur (SIRET, certification RGE, assurances)
• Montants (devis, prime demandée, reste à charge)

Upload de documents

Chaque dossier nécessite la transmission de justificatifs numériques. Notre système accepte les formats PDF, JPEG et PNG jusqu'à 10 Mo par fichier.

Endpoint : POST /api/v1/dossiers/{id}/documents

Types de documents acceptés :

Suivi et statut des dossiers

Consultez en temps réel l'état d'avancement de vos dossiers. Le système fournit un tracking détaillé avec historique complet des actions et modifications.

Endpoint : GET /api/v1/dossiers/{id}

Statuts possibles :

• DRAFT : dossier en cours de création, non soumis
• SUBMITTED : dossier déposé, en attente de vérification
• UNDER_REVIEW : en cours d'analyse par nos équipes
• ADDITIONAL_INFO_REQUIRED : informations complémentaires demandées
• APPROVED : dossier validé, en attente de paiement
• PAID : prime versée au bénéficiaire
• REJECTED : dossier refusé avec motif détaillé
• CANCELLED : annulé à la demande du partenaire ou bénéficiaire

Webhooks et notifications

Recevez automatiquement des notifications lors des changements de statut importants. Configurez vos URLs de callback pour être informé en temps réel sans polling constant de l'API.

Configuration : POST /api/v1/webhooks

Événements disponibles :

• dossier.submitted : dossier soumis avec succès
• dossier.approved : validation du dossier
• dossier.rejected : refus du dossier
• dossier.additional_info : demande d'informations complémentaires
• payment.initiated : paiement lancé
• payment.completed : paiement effectué
• document.validated : document approuvé
• document.rejected : document refusé

Gestion de la facturation via API

Notre système intègre une gestion complète de la facturation entre partenaires et SubventionPrime.com. Automatisez le calcul de vos commissions et la génération de vos factures.

Calcul automatique des commissions

Pour chaque dossier validé, une commission est calculée selon les conditions négociées dans votre contrat partenaire. L'API expose ces informations de manière transparente.

Endpoint : GET /api/v1/dossiers/{id}/commission

La réponse détaille le montant de la prime CEE, le pourcentage de commission applicable, le montant HT et TTC de votre rémunération, ainsi que la date prévisionnelle de règlement.

Génération de factures

Générez automatiquement vos factures de commissions selon une périodicité définie (mensuelle, hebdomadaire ou à la demande).

Endpoint : POST /api/v1/invoices/generate

Paramètres :

• period_start : date de début de période
• period_end : date de fin de période
• format : PDF ou JSON

Consultation des paiements

Suivez l'état de vos paiements et rapprochez-les de vos factures grâce à l'endpoint dédié.

Endpoint : GET /api/v1/payments

Filtrez par date, statut ou montant pour faciliter votre gestion comptable. Chaque paiement est référencé avec l'identifiant de facture correspondant.

Formats de données et standards

L'API utilise des formats standardisés pour garantir l'interopérabilité et faciliter l'intégration dans vos systèmes existants.

Format des dates

Toutes les dates sont exprimées au format ISO 8601 (YYYY-MM-DD pour les dates, YYYY-MM-DDTHH:mm:ssZ pour les timestamps avec timezone UTC).

Format des montants

Les montants sont toujours exprimés en centimes d'euros (nombre entier) pour éviter les problèmes d'arrondis. Par exemple, 125,50 € est représenté par la valeur 12550.

Codes postaux et adresses

Les codes postaux français sont validés selon le format 5 chiffres. Les adresses suivent la norme postale française avec découpage en champs structurés (numéro, type de voie, nom de voie, complément, code postal, ville).

Numéros de téléphone

Les numéros de téléphone sont stockés au format E.164 international (+33XXXXXXXXX) mais acceptés en entrée avec différents formatages (espaces, points, tirets supprimés automatiquement).

Gestion des erreurs et codes retour

L'API utilise les codes HTTP standards et fournit des messages d'erreur détaillés pour faciliter le débogage.

Codes HTTP principaux

Structure des messages d'erreur

Chaque erreur renvoie un objet JSON structuré contenant un code d'erreur spécifique, un message explicite, et éventuellement des détails supplémentaires sur les champs concernés.

Les erreurs de validation incluent un tableau détaillant chaque champ en erreur avec le message correspondant, facilitant ainsi la correction côté client.

Bonnes pratiques d'intégration

Pour garantir une intégration robuste et performante, nous recommandons de suivre ces bonnes pratiques éprouvées.

Gestion de la résilience

Implémentez une stratégie de retry avec backoff exponentiel pour gérer les erreurs temporaires. Nous recommandons 3 tentatives maximum avec des délais de 1s, 3s puis 9s entre chaque tentative.

Stockez localement les données critiques avant envoi à l'API pour pouvoir rejouer les opérations en cas d'échec réseau.

Optimisation des performances

• Pagination : utilisez les paramètres de pagination pour les listes volumineuses (limite de 100 éléments par page recommandée)
• Filtrage : privilégiez les filtres côté serveur plutôt que de récupérer toutes les données
• Compression : activez la compression gzip pour réduire la bande passante
• Cache : mettez en cache les données peu volatiles (listes de référence, barèmes)
• Requêtes groupées : utilisez les endpoints batch quand disponibles pour réduire le nombre d'appels

Sécurité et confidentialité

Ne stockez jamais vos credentials dans le code source. Utilisez des variables d'environnement ou un système de gestion de secrets dédié.

Chiffrez les données sensibles avant stockage local et lors des transmissions non HTTPS (logs, fichiers temporaires).

Limitez la durée de rétention des données personnelles au strict nécessaire conformément au RGPD.

Monitoring et logging

Mettez en place un système de logging complet enregistrant les appels API, les temps de réponse et les erreurs rencontrées. Ces logs sont précieux pour diagnostiquer les problèmes et optimiser les performances.

Configurez des alertes sur les métriques clés : taux d'erreur supérieur à 5%, temps de réponse dépassant 1 seconde, rate limiting atteint.

Exemples d'intégration

Nous proposons des exemples de code dans les langages les plus utilisés pour accélérer votre intégration.

Cas d'usage : parcours complet d'un dossier

Voici le flux typique d'intégration pour traiter un dossier CEE de bout en bout :

1. Authentification et récupération du token d'accès
2. Vérification de l'éligibilité du projet
3. Création du dossier avec les informations bénéficiaire et projet
4. Upload des documents justificatifs requis
5. Soumission du dossier pour validation
6. Écoute du webhook de validation ou polling du statut
7. Récupération des informations de commission
8. Notification au bénéficiaire du versement de la prime

Intégration avec les CRM et ERP

Notre API s'intègre facilement avec les solutions CRM et ERP du marché. Nous proposons des connecteurs prêts à l'emploi pour Salesforce, Microsoft Dynamics, SAP et Odoo.

Pour les solutions propriétaires, utilisez nos endpoints REST standards compatibles avec tous les outils d'intégration (Zapier, Make, n8n, etc.).

Support et documentation développeur

Nous mettons à disposition des développeurs un ensemble complet de ressources pour faciliter l'intégration et le maintien de vos applications.

Documentation interactive

Notre documentation API est disponible au format OpenAPI 3.0 (anciennement Swagger) avec une interface interactive permettant de tester directement les endpoints depuis votre navigateur.

Chaque endpoint dispose d'exemples de requêtes et réponses, de la description complète des paramètres et des cas d'erreur possibles.

Bibliothèques clientes

Nous maintenons des SDK officiels dans les langages suivants :

• JavaScript / TypeScript (Node.js et navigateur)
• Python 3.8+
• PHP 7.4+
• Java 11+
• C# .NET Core 3.1+

Ces bibliothèques gèrent automatiquement l'authentification, la sérialisation JSON, la gestion des erreurs et le retry automatique.

Support technique

Notre équipe technique est disponible pour vous accompagner dans votre intégration :

Changelog et versioning

L'API suit un versioning sémantique strict. Les versions mineures garantissent la rétrocompatibilité, seules les versions majeures peuvent introduire des changements cassants.

Consultez régulièrement le changelog pour être informé des nouvelles fonctionnalités, corrections de bugs et améliorations de performance.

Nous maintenons les versions majeures pendant 24 mois minimum après la sortie de la version suivante, vous laissant le temps de migrer vos intégrations.

Conformité et certifications

Notre API et notre infrastructure respectent les standards de sécurité et de conformité les plus exigeants du marché.

Protection des données

Conformité RGPD totale avec chiffrement des données sensibles au repos (AES-256) et en transit (TLS 1.3). Les données personnelles sont hébergées exclusivement en France sur des datacenters certifiés ISO 27001.

Audits de sécurité

Notre infrastructure fait l'objet d'audits de sécurité semestriels réalisés par des cabinets indépendants. Les tests de pénétration réguliers garantissent la robustesse de nos systèmes.

Disponibilité et SLA

Nous garantissons contractuellement une disponibilité de 99,9% de l'API avec compensation financière en cas de non-respect. Notre infrastructure redondée assure la continuité de service même en cas de défaillance d'un datacenter.

Les interventions de maintenance sont planifiées en dehors des heures ouvrées avec notification 7 jours à l'avance minimum.