API Thervy (Vulcain)
Intégrez la puissance du moteur 3CL réglementaire dans vos applications. Simulation DPE, calcul des aides, annuaire RGE et enrichissement de biens : 12 domaines accessibles via une API REST unique.
12 domaines, une API
Chaque domaine couvre un aspect clé de la rénovation énergétique : DPE, aides, artisans, biens, simulations, enrichissement, webhooks et plus encore.
/accountInfos compte, quotas et usage
/simulationsCRUD simulations DPE, profil bâtiment, travaux recommandés
/leadsCRUD leads, notes, suivi pipeline
/dossiersCRUD dossiers CEE/MaPrimeRénov', changement statut
/webhooksCRUD webhooks, test ping, evenements temps réel
/usersGestion équipe et accès API
/agenciesGestion agences du réseau
/companiesAnnuaire 60 000+ entreprises certifiées RGE
/marAnnuaire Mon Accompagnateur Renov, matching
/works, /energiesTravaux, énergies, barèmes aides officiels
/calculateCalcul simplifie, simulation après travaux, aides
/ademeDonnées DPE ADEME par adresse ou numéro
Démarrage rapide
Trois étapes pour passer votre premier appel API et obtenir une estimation DPE programmatique.
Créez votre compte
Inscrivez-vous en 2 minutes depuis la page d'inscription entreprise. Votre clé API est générée automatiquement et accessible depuis votre espace pro.
Authentifiez-vous
Ajoutez votre clé API dans le header Authorization (Bearer). Toutes les requêtes sont authentifiées et trackees avec des quotas par plan.
Appelez l'API
Lancez votre premier appel vers /api/vulcain/v1/simulation pour obtenir une estimation DPE. La réponse JSON inclut la lettre, les consommations et les aides disponibles.
curl -sS "https://www.thervy.com/api/vulcain/v1/account" \
-H "X-API-Key: tv_votre_cle"Exemples de code
Des exemples prêts à copier en cURL, JavaScript, Python et PHP pour démarrer en quelques minutes.
curl -X POST https://www.thervy.com/api/vulcain/v1/simulations \
-H "X-API-Key: tv_votre_cle" \
-H "Content-Type: application/json" \
-d '{
"address": "12 rue de la Paix, 75002 Paris",
"propertyType": "apartment",
"area": 65,
"rooms": 3,
"constructionYear": 1985
}'{
"id": "sim_a1b2c3d4",
"status": "completed",
"address": "12 rue de la Paix, 75002 Paris",
"dpe": {
"letter": "D",
"value": 231,
"ges": "E",
"gesValue": 58
},
"estimatedWorks": [
{ "type": "isolation_murs", "gain": 45, "cost": 12000 },
{ "type": "pompe_chaleur", "gain": 38, "cost": 9500 }
],
"estimatedAids": {
"maprimerenov": 5500,
"cee": 3200,
"total": 8700
}
}Webhooks temps réel
Recevez des notifications en temps réel quand une simulation est terminée, un lead généré ou un dossier d'aides mis à jour. Configurez vos endpoints depuis votre espace pro.
lead.createdUn prospect arrive, quelle que soit son origine : widget, tunnel public, API ou saisie manuellelead.updatedUne coordonnée du prospect changelead.status_changedLe lead passe de nouveau à attribué, contacté, converti ou perdulead.assignedLe prospect est confié à une entreprise, par le réseau, par une agence ou par la répartition automatiquesimulation.createdUne simulation est enregistrée, avant même que le calcul soit disponiblesimulation.completedLe résultat 3CL est disponible : étiquettes avant et après travaux connuesclient.createdUne fiche client est ouverte, y compris par conversion d'un leadclient.updatedUne donnée de la fiche client changebien.createdUn bien entre au portefeuillebien.updatedPrix, statut ou caractéristiques du bien changentdemande_devis.createdUn particulier demande un devis, depuis le tunnel, l'annuaire ou l'APIdevis.createdUn devis est ouvert, encore en brouillon et sans numérodevis.sentLe devis part au client. C'est à ce moment qu'il reçoit son numéro définitifdevis.acceptedLe client signe. Les autres devis de la même demande passent alors à refusédevis.refusedLe client écarte la proposition, ou une autre a été retenuefacture.createdUne facture, un acompte ou un avoir est ouvert, encore en brouillon et sans numérofacture.emittedLa pièce est émise. C'est à ce moment qu'elle reçoit son numéro définitif et devient immuablefacture.paidLe reste dû tombe à zéro, par encaissement ou par imputation d'un avoirfacture.overdueL'échéance est passée et la facture reste dueavoir.emittedUn avoir est émis et s'impute sur la facture qu'il corrigereglement.createdUn encaissement est enregistré sur une facturechantier.createdUn chantier est ouvertchantier.status_changedLe chantier avance d'une étapedossier.createdUn dossier MaPrimeRénov', CEE ou éco-PTZ est ouvertdossier.status_changedLe dossier change d'état d'instructionsollicitation.createdUne demande arrive depuis l'annuaire ou un espace partenairesollicitation.status_changedLa demande est acceptée, refusée ou clôturéecarnet.createdUn carnet d'information du logement est ouvertSécurité des webhooks
- Signature
X-Thervy-Signature= HMAC_SHA256(body, secret) - Headers utiles :
X-Thervy-Event,X-Thervy-Timestamp - Répondez 2xx rapidement — timeout court cote Thervy
- Endpoint de test :
POST /webhooks/{id}/test
Authentification et sécurité
API Key
Header X-API-Key sur chaque requête. Les clés sont préfixées tv_ et peuvent être révoquées a tout moment.
Rate limiting
100 requêtes par 1 minute. Code 429 avec header Retry-After en cas de dépassement.
CORS
Configurable par clé API. Recommandation : appels serveur à serveur pour ne pas exposer la clé.
Erreurs JSON
Format standard : { "error": "message", "code": 422 }. Codes HTTP semantiques (400, 401, 403, 404, 422, 429).
Référence technique
Documentation OpenAPI complète avec schémas, exemples de requêtes/réponses et codes d'erreur pour chaque endpoint.
Questions fréquentes
Prêt à intégrer Thervy ?
Créez votre compte, générez votre clé API et passez votre premier appel en moins de 5 minutes. Documentation complète et exemples de code disponibles.
API de rénovation énergétique pour les développeurs
L'API Vulcain de Thervy est la première API REST française dédiée à la rénovation énergétique. Elle couvre l'ensemble de la chaîne de valeur : simulation DPE avec la méthode 3CL, calcul des aides (MaPrimeRénov', CEE, éco-PTZ), annuaire des artisans RGE, enrichissement de biens immobiliers et génération de rapports PDF.
Pensée pour les développeurs, l'API est documentée en OpenAPI 3.0, accessible en JSON, sécurisée par clé API et disponible en sandbox. Les webhooks permettent de recevoir des notifications en temps réel. Idéale pour les portails immobiliers, les CRM bâtiment, les comparateurs d'énergie et les applications de gestion de patrimoine.