API Version:
API docs by Redocly

kelvin API (v3)

Download OpenAPI specification:

Bienvenue dans la documentation de l'API kelvin. Cette API est conçue pour évaluer et améliorer la performance énergétique des propriétés.

API Logo

Aperçu de l'API

L'API kelvin vous permet de créer des simulations pour évaluer la performance énergétique d'un bien immobilier. Elle vous aide également à proposer des plans de travaux personnalisés pour optimiser l'efficacité énergétique de ces biens.

Objectifs Principaux

  • Création de simulations : Lancez des simulations pour obtenir la performance énergétique actuelle d'une propriété.
  • Propositions de travaux : Génération de recommandations de travaux spécifiques pour améliorer l'efficacité énergétique, basées sur les résultats de la simulation.
  • Gestion des DPE : Recherchez et gérez les Diagnostics de Performance Énergétique.

Utilisation de l'iframe de sélection de polygone

Pour créer une simulation, il faut déterminer la latitude, la longitude et l'identifiant d'interopérabilité (ban_id) de la propriété. Une carte interactive est disponible pour faciliter cette tâche: L'iframe de sélection de polygone. Cette carte permet aux utilisateurs de sélectionner visuellement leur propriété sur une carte. Vous pouvez intégrer ce composant dans vos applications en suivant la documentation de l'iframe de sélection de polygone.

Utilisez cette documentation pour explorer les endpoints disponibles, comprendre les paramètres requis, et découvrir comment intégrer efficacement l'API dans votre système.

Changelog v2 → v3

⚠️ Breaking changes

Tous les endpoints ont été migrés de /api/v2/ vers /api/v3/.

Renommage des champs de performance énergétique

dpe_class est renommé energy_rating dans l'état initial et l'état projeté. Trois nouveaux champs obligatoires sont ajoutés :

Avant Après
dpe_class energy_rating
(absent) energy_consumption (kWh/m²/an)
(absent) carbon_rating (lettre GES A–G)
(absent) carbon_emissions (kg CO₂/m²/an)

Champs d'isolation restructurés

Les champs walls_insulation_level, windows_insulation_level, high_floor_insulation_level, low_floor_insulation_level (chaînes de caractères) sont remplacés par des objets contenant un level et une u_value numérique (W/m²K) :

"walls_insulation": { "level": "partially_insulated", "u_value": 0.35 }

Aides financières restructurées

subsidies (montant total unique) est remplacé par un objet financial_support détaillé, disponible à la fois sur chaque plan de rénovation et sur chaque poste de travaux :

"financial_support": { "mpr": 4000.0, "cee": 800.0, "ecoptz": 1200.0, "local": { "Aide région Île-de-France": 1500.0 } }

Structure du plan de rénovation modifiée

Chaque catégorie de travaux dans renovation_plan est désormais un tableau d'items (au lieu d'un objet unique). Chaque item remplace id/simplified_id/label par technical_id et name.

Valeurs d'enum mises à jour

Plusieurs champs ont des valeurs d'enum entièrement révisées pour correspondre au référentiel DPE/ADEME :

  • generator_type / secondary_generator_type : 4 valeurs génériques → 26 valeurs précises (ex. condensing_gas_boiler, air_to_water_heat_pump, pellet_stove) + unknown pour les cas non identifiés
  • hot_water_type : 5 valeurs → 24 valeurs précises (ex. electric_hot_water_tank, thermodynamic_water_tank) + unknown pour les cas non identifiés
  • generator_energy / hot_water_energy / secondary_generator_energy : urban_heating_or_biomass → district_heating + biomass_wood + others + unknown
  • wall_material : 5 valeurs → 9 valeurs (ex. lightweight_concrete, hollow_or_perforated_bricks, rammed_or_cob_earth)
  • vents_type : codes renommés (ex. vmc_sf_hygro_b → sf_hygro_b_vmc)

windows renommé en doors_windows dans renovation_plan

La catégorie windows couvre désormais fenêtres, portes, portes-fenêtres et fenêtres de toit (18 valeurs de technical_id).

Champs supprimés

  • recently_renovated — supprimé de l'état initial et de l'endpoint de mise à jour du logement
  • has_vents — supprimé (remplacé par le champ vents_type)
  • subsidies — remplacé par l'objet financial_support

✨ Nouveautés

Nouvel endpoint de qualification

PUT /api/v3/simulations/{id}/qualification — Enregistre le profil de qualification de l'utilisateur (statut propriétaire/locataire, taille du foyer, tranche de revenus, département fiscal, maturité du projet). Cet appel doit être effectué avant POST /run.

Nouveaux champs dans l'état initial

  • epc_id — numéro du DPE attaché à la simulation, le cas échéant
  • secondary_generator_type / secondary_generator_energy — système de chauffage secondaire
  • collective_heating / collective_hot_water — indicateurs de systèmes collectifs
  • high_floor_surface, low_floor_surface, windows_surface — surfaces en m²
  • high_floor_kinds / low_floor_kinds — tableaux remplaçant les anciens high_floor_type / low_floor_type
  • sources — indique pour chaque champ si la valeur provient de ai, user ou dpe

Nouvelles catégories de travaux dans renovation_plan

En plus de ventilation, walls, doors_windows, low_floor, high_floor, les catégories suivantes sont désormais retournées : heating, hot_water, renewable_energy, summer_comfort, winter_comfort, thermal_bridge_treatment, lighting, sobriety

Nouveau bloc KPI

Chaque plan de rénovation inclut désormais un objet kpi avec property_value_increase (valorisation immobilière estimée exprimée en pourcentage, en €/m² et en perte de surface m²).

Simulateur

Endpoints disponibles dans l'offre Simulateur

Créer une simulation

Endpoint pour créer une simulation à partir d'un ban_id et des coordonnées GPS.

Authorizations:
bearerAuth
Request Body schema: application/json
latitude
required
number
longitude
required
number
ban_id
string

Responses

Request samples

Content type
application/json
{
  • "latitude": 43.53718,
  • "longitude": 1.337797,
  • "ban_id": "31157_0790_00009"
}

Response samples

Content type
application/json
{
  • "simulation_id": "hjjcm1qp28"
}

Récupérer les informations de la propriété

Les informations de la propriété.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "housing": {
    },
  • "address": {
    }
}

Mettre à jour les informations de la propriété

Endpoint pour mettre à jour les informations de la propriété

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Request Body schema: application/json
epc_id
string

Le numéro unique du DPE.

housing_type
string
Enum: "house" "apartment"

Le type de propriété.

surface
integer

La surface de la propriété en m2. Obligatoire si le housing_type est apartment.

floor_level
string
Enum: "ground" "intermediate" "last"

La position da le propriété dans l'immeuble. Obligatoire si le housing_type est apartment.

number_of_exterior_wall
integer

Le nombre de murs donnant sur l'extérieur. Obligatoire si le housing_type est apartment.

Responses

Request samples

Content type
application/json
{
  • "epc_id": "2331E2555868X",
  • "housing_type": "apartment",
  • "surface": 100,
  • "floor_level": "ground",
  • "number_of_exterior_wall": 1
}

Response samples

Content type
application/json
{
  • "error": "Housing type is missing or invalid"
}

Qualifier le profil de l'utilisateur

Enregistre les informations de qualification du profil utilisateur.

Comportement de primary_residence selon profile :

  • owner_resident : primary_residence est automatiquement défini à true (la valeur fournie est ignorée).
  • owner_non_resident : primary_residence est automatiquement défini à false (la valeur fournie est ignorée).
  • renter ou lessor : primary_residence est obligatoire ; son absence retourne une erreur 400.

Effet sur la simulation : Après une mise à jour réussie, les résultats de simulation existants ne sont plus à jour. Appelez POST /api/v3/simulations/{simulation_id}/run pour obtenir des résultats recalculés.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de la simulation.

Request Body schema: application/json
required
profile
required
string
Enum: "owner_resident" "owner_non_resident" "renter" "lessor"

Le profil de l'utilisateur. owner_resident : propriétaire occupant (primary_residence forcé à true). owner_non_resident : propriétaire non-occupant (primary_residence forcé à false). renter : locataire (primary_residence requis). lessor : bailleur (primary_residence requis).

primary_residence
boolean

Indique si le logement est la résidence principale. Obligatoire pour les profils renter et lessor. Ignoré (auto-calculé) pour les profils owner_resident et owner_non_resident.

household_size
required
integer [ 1 .. 12 ]

Nombre de personnes dans le foyer fiscal.

tax_residence_department
string

Code du département de résidence fiscale (ex : "75", "13", "2A"). Doit correspondre à un code de département français valide. Utilisé pour calculer les plafonds de revenus ANAH.

income_range
required
string
Enum: "very_modest" "modest" "intermediate" "superior"

Tranche de revenus du foyer selon le barème ANAH. very_modest : très modeste. modest : modeste. intermediate : intermédiaire. superior : supérieure aux plafonds ANAH.

project_maturity
string
Enum: "curious" "searching" "estimated" "signed"

Maturité du projet de rénovation. curious : en phase de découverte. searching : en recherche active. estimated : devis reçu. signed : devis signé.

Responses

Request samples

Content type
application/json
{
  • "profile": "owner_resident",
  • "primary_residence": true,
  • "household_size": 4,
  • "tax_residence_department": "75",
  • "income_range": "modest",
  • "project_maturity": "curious"
}

Response samples

Content type
application/json
{
  • "error": "Tax residence department is invalid"
}

Lancer la simulation

Endpoint pour lancer la simulation.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthorized"
}

Récupérer l'état projeté

Les informations de l'état projeté.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "projected_state": {
    }
}

Qualification

Endpoints disponibles dans l'offre Qualification

Lister les gestes activés pour l'équipe

Retourne la liste des gestes de rénovation activés pour l'équipe.

Un geste est considéré comme activé tant qu'il n'a pas été explicitement désactivé pour l'équipe (ou l'une de ses équipes parentes) dans les paramètres du catalogue.

Chaque geste inclut, le cas échéant, sa prestation par défaut (default_service) ainsi que la référence par défaut associée pour l'équipe.

Authorizations:
bearerAuth
query Parameters
gesture_technical_ids
Array of strings
Example: gesture_technical_ids=roof_windows_double_glazed

Filtre optionnel : limite le résultat aux gestes correspondant à ces identifiants techniques.

Responses

Response samples

Content type
application/json
{
  • "gestures": [
    ]
}

Lister les références activées pour l'équipe

Retourne la liste des références (produits) activées pour l'équipe.

Au moins un filtre est requis parmi service_technical_ids, gestures_technical_ids ou reference_ids. Ce endpoint s'inscrit dans le parcours de qualification : récupérer les gestes activés, puis les prestations activées, puis les références activées pour la prestation choisie.

Chaque référence inclut son prix pour l'équipe (héritant de la hiérarchie d'équipes le cas échéant).

Authorizations:
bearerAuth
query Parameters
service_technical_ids
Array of strings
Example: service_technical_ids=french_doors_double_glazed_wood_aluminium

Filtre par identifiants techniques de prestations.

gestures_technical_ids
Array of strings
Example: gestures_technical_ids=french_doors_double_glazed

Filtre par identifiants techniques de gestes.

reference_ids
Array of strings
Example: reference_ids=919ce243-1385-46d7-afd6-41ea8629a40d

Filtre par identifiants (UUID) de références.

Responses

Response samples

Content type
application/json
{
  • "references": [
    ]
}

Lister les prestations activées pour l'équipe

Retourne la liste des prestations (services) activées pour l'équipe.

Une prestation est considérée comme activée tant qu'elle n'a pas été explicitement désactivée pour l'équipe (ou l'une de ses équipes parentes) dans les paramètres du catalogue.

Chaque prestation inclut, le cas échéant, sa référence par défaut (default_reference) pour l'équipe.

Authorizations:
bearerAuth
query Parameters
service_technical_ids
Array of strings
Example: service_technical_ids=french_doors_double_glazed_wood_aluminium

Filtre optionnel : limite le résultat aux prestations correspondant à ces identifiants techniques.

Responses

Response samples

Content type
application/json
{
  • "services": [
    ]
}

Rechercher des DPE par clé d'interopérabilité ou par numéro DPE.

Cet endpoint permet de rechercher des DPE par clé d'interopérabilité ou par numéro de DPE.

Fonctionnalités : Il est obligatoire de fournir au moins un des deux paramètres "ban_id" ou "dpe_id".

  • Recherche par clé d'interopérabilité : Il est possible de rechercher les DPE par la clé d'interopérabilité (ban_id) d'une adresse. Par exemple "31157_0790_00009".
  • Recherche par Numéro de DPE : Il est également possible de rechercher un DPE en utilisant son numéro unique. Cela permet de récupérer rapidement les informations d'un DPE spécifique, par exemple "2331E2555868X".

Filtres : En plus des paramètres principaux, cet endpoint permet d'appliquer des filtres supplémentaires :

  • Surface : Filtrer les DPE en fonction de la surface du bien à 10% près.
  • Date du du diagnostic : Filtrer les DPE selon la date à laquelle ils ont été établis.
  • Classe Énergétique : Filtrer par la classe énergétique du DPE.

Réponse : En cas de succès, l'endpoint retourne une liste de DPE correspondant aux critères de recherche spécifiés.

Authorizations:
bearerAuth
query Parameters
dpe_id
string
Example: dpe_id=2331E2555868X
building_type
string
Enum: "apartment" "house" "building" "unknown"
Example: building_type=house

Le type de bâtiment:

  • apartment
  • house
  • building
  • unknown
ban_id
string
Example: ban_id=31157_0790_00009
surface
number
Example: surface=100
report_date
string
Example: report_date=2024-01-01
energy_class
string
Example: energy_class=E

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Récupérer l'état initial

Les informations de l'état initial.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "initial_state": {
    }
}

Mettre à jour l'état initial

Endpoint pour mettre à jour les informations de l'état initial

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Request Body schema: application/json
housing_type
string
Enum: "house" "apartment"

Type de logement.

close_to_historical_monument
boolean

Proximité d'un monument historique.

floor_level
string
Enum: "ground" "intermediate" "last"

Niveau de l'étage (rez-de-chaussée, intermédiaire, dernier étage).

living_area
number

La surface habitable en mètres carrés.

number_of_exterior_wall
integer

Nombre de murs extérieurs.

house_number_of_levels
integer

Le nombre de niveaux dans la maison.

shared_walls
boolean

Présence de murs mitoyens.

object

L'année de construction du bâtiment.

wall_material
string
Enum: "lightweight_concrete" "insulating_concrete" "stone" "brick" "hollow_or_perforated_bricks" "wood" "wood_with_insulating_infill" "rammed_or_cob_earth" "traditional_old_material" "others"

Le matériau principal des murs.

high_floor_kinds
Array of strings
Items Enum: "apartment" "converted_attic" "lost_attic" "not_heated_space" "office" "roof_terrace" "unknown"

Les types de plancher haut.

low_floor_kinds
Array of strings
Items Enum: "apartment" "crawl_space" "not_heated_space" "office" "slab_on_grade" "underground_garage" "unknown"

Les types de plancher bas.

windows
string
Enum: "high_class" "middle_class" "low_class"

Le type de fenêtre.

number_of_windows
integer

Le nombre total de fenêtres.

generator_energy
string
Enum: "electricity" "fuel" "gas" "biomass_wood" "district_heating" "others"

Le type d'énergie utilisé par le générateur de chauffage.

generator_type
string
Enum: "air_to_air_heat_pump" "air_to_water_heat_pump" "classic_gas_boiler" "closed_fireplace_insert" "coal_boiler" "condensing_gas_boiler" "electric_boiler_or_underfloor_heating" "electric_convector_heater" "electric_radiator" "fossil_fueled_district_heating_network" "fuel_boiler" "fuel_stove" "geothermal_heat_pump" "hybrid_heat_pump" "insulated_district_heating_network" "lpg_propane_butane_boiler_with_external_tank" "low_temperature_gas_boiler" "misc_system" "other_gas_generators" "pellet_boiler" "pellet_stove" "radiant_panel_heater" "standard_gas_boiler" "uninsulated_district_heating_network" "wood_boiler" "wood_stove"

Le type de générateur de chauffage.

secondary_generator_energy
string
Enum: "electricity" "fuel" "gas" "biomass_wood" "district_heating" "others"

Le type d'énergie utilisé par le chauffage secondaire.

secondary_generator_type
string
Enum: "air_to_air_heat_pump" "air_to_water_heat_pump" "classic_gas_boiler" "closed_fireplace_insert" "coal_boiler" "condensing_gas_boiler" "electric_boiler_or_underfloor_heating" "electric_convector_heater" "electric_radiator" "fossil_fueled_district_heating_network" "fuel_boiler" "fuel_stove" "geothermal_heat_pump" "hybrid_heat_pump" "insulated_district_heating_network" "lpg_propane_butane_boiler_with_external_tank" "low_temperature_gas_boiler" "misc_system" "other_gas_generators" "pellet_boiler" "pellet_stove" "radiant_panel_heater" "standard_gas_boiler" "uninsulated_district_heating_network" "wood_boiler" "wood_stove"

Le type de générateur de chauffage secondaire.

hot_water_energy
string
Enum: "electricity" "fuel" "gas" "biomass_wood" "district_heating" "others"

Le type d'énergie utilisé pour l'eau chaude sanitaire.

hot_water_type
string
Enum: "air_to_water_heat_pump" "classic_gas_boiler" "coal_boiler" "condensing_gas_boiler" "electric_boiler" "electric_hot_water_tank" "electric_water_heater" "fossil_fueled_district_heating_network" "fuel_boiler" "gas_water_tank" "geothermal_heat_pump" "hybrid_heat_pump" "insulated_district_heating_network" "instant_gas_water_heater" "instant_lpg_propane_butane_water_heater" "lpg_propane_butane_boiler_external_tank" "lpg_propane_butane_storage_hot_water_tank" "low_temperature_gas_boiler" "other_gas_generators" "pellet_boiler" "standard_gas_boiler" "thermodynamic_water_tank" "uninsulated_district_heating_network" "wood_boiler"

Le type de système de production d'eau chaude sanitaire.

vents_type
string
Enum: "window_opening_ventilation" "high_low_air_inlet_ventilation" "natural_ventilation_duct" "mechanical_ventilation_existing_duct" "sf_self_regulating_vmc" "sf_hygro_a_vmc" "sf_hygro_b_vmc" "sf_gas_vmc" "low_pressure_vmc" "hybrid_ventilation" "individual_df_vmc" "collective_df_vmc" "climatic_well"

Le type de ventilation.

garage
boolean

Présence d'un garage.

collective_heating
boolean

Chauffage collectif.

collective_hot_water
boolean

Eau chaude sanitaire collective.

walls_insulation_level
string
Enum: "no_insulation" "partially_insulated" "moderately_insulated" "well_insulated"

Le niveau d'isolation des murs.

high_floor_insulation_level
string
Enum: "no_insulation" "partially_insulated" "moderately_insulated" "well_insulated"

Le niveau d'isolation du plancher haut.

low_floor_insulation_level
string
Enum: "no_insulation" "partially_insulated" "moderately_insulated" "well_insulated"

Le niveau d'isolation du plancher bas.

high_floor_surface
integer

La surface du plancher haut en mètres carrés.

low_floor_surface
integer

La surface du plancher bas en mètres carrés.

exterior_walls_surface
integer

La surface extérieure des murs en mètres carrés.

windows_surface
integer

La surface totale des fenêtres en mètres carrés.

Responses

Request samples

Content type
application/json
{
  • "housing_type": "apartment",
  • "close_to_historical_monument": true,
  • "floor_level": "ground",
  • "living_area": 120,
  • "number_of_exterior_wall": 3,
  • "house_number_of_levels": 1,
  • "shared_walls": true,
  • "construction_year": {
    },
  • "wall_material": "brick",
  • "high_floor_kinds": [
    ],
  • "low_floor_kinds": [
    ],
  • "windows": "middle_class",
  • "number_of_windows": 8,
  • "generator_energy": "gas",
  • "generator_type": "condensing_gas_boiler",
  • "secondary_generator_energy": "gas",
  • "secondary_generator_type": "condensing_gas_boiler",
  • "hot_water_energy": "electricity",
  • "hot_water_type": "electric_hot_water_tank",
  • "vents_type": "sf_self_regulating_vmc",
  • "garage": false,
  • "collective_heating": false,
  • "collective_hot_water": false,
  • "walls_insulation_level": "partially_insulated",
  • "high_floor_insulation_level": "partially_insulated",
  • "low_floor_insulation_level": "partially_insulated",
  • "high_floor_surface": 60,
  • "low_floor_surface": 60,
  • "exterior_walls_surface": 85,
  • "windows_surface": 10
}

Response samples

Content type
application/json
{
  • "error": "Generator type n'est pas valide"
}

Créer un plan de rénovation personnalisé

Crée un plan de rénovation basé sur une sélection spécifique de gestes. L'opération est asynchrone : l'API retourne immédiatement une réponse confirmant la création, mais le plan complet n'est pas disponible dans l'instant. Pour consulter le plan généré une fois le traitement terminé, utilisez le endpoint 'Récupérer le plan de rénovation personnalisé'.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Request Body schema: application/json
required
name
string

Le nom du plan de rénovation personnalisé.

required
object

Responses

Request samples

Content type
application/json
{
  • "name": "Mon plan personnalisé",
  • "renovation_plan": {
    }
}

Response samples

Content type
application/json
{
  • "renovation_plan_id": "hjjcm1qp28"
}

Récupérer le plan de rénovation personnalisé

Les informations du plan de rénovation personnalisé.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

renovation_plan_id
required
string
Example: hjjcm1qp28

L'identifiant du plan de rénovation personnalisé.

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "id": "hjjcm1qp28",
  • "name": "Mon plan personnalisé",
  • "type": "customized",
  • "overall_rating": "B",
  • "energy_rating": "B",
  • "energy_consumption": 201,
  • "carbon_rating": "C",
  • "carbon_emissions": 40,
  • "yearly_energy_savings": 600,
  • "yearly_energy_cost": 12000,
  • "budget": 400,
  • "financial_support": {
    },
  • "kpi": {
    },
  • "renovation_plan": {
    }
}

Modifier un plan de rénovation personnalisé

Modifie un plan de rénovation existant en mode avancé (choix de la prestation et de la référence catalogue). Un nouveau plan est créé à partir de l'original afin de conserver l'historique. L'opération est asynchrone : consultez le plan via le endpoint 'Récupérer le plan de rénovation personnalisé' une fois le traitement terminé.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

renovation_plan_id
required
string
Example: hjjcm1qp28

L'identifiant du plan de rénovation personnalisé à modifier.

Request Body schema: application/json
required
name
string

Le nom du plan de rénovation personnalisé.

required
object

Responses

Request samples

Content type
application/json
{
  • "name": "Mon plan personnalisé",
  • "renovation_plan": {
    }
}

Response samples

Content type
application/json
{
  • "renovation_plan_id": "hjjcm1qp28"
}

Lancer la génération du rapport PDF

Endpoint pour démarrer la génération asynchrone du rapport PDF de la simulation. Le rapport peut optionnellement inclure les informations du client.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Request Body schema: application/json
object

Les informations du client (nom, prénom, email, téléphone)

Responses

Request samples

Content type
application/json
{
  • "client": {
    }
}

Response samples

Content type
application/json
{
  • "error": "Unauthorized"
}

Récupérer le statut du rapport PDF

Le statut de la génération du rapport PDF et l'URL de téléchargement.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Responses

Response samples

Content type
application/json
{}

Documents

Endpoints pour consulter les documents générés pour une simulation

Lister les documents de la simulation

Liste paginée des documents générés pour la simulation (rapports PDF, offres commerciales, cadres de contribution, notes de dimensionnement, attestations sur l'honneur). Par défaut, seul le dernier document est renvoyé. Utilisez full=true pour tous les documents, id pour un document précis, type pour filtrer par type de document, et begin/end pour filtrer par date de génération.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

query Parameters
full
boolean

Renvoie tous les documents au lieu du seul dernier document.

id
integer

Renvoie uniquement le document correspondant à cet identifiant.

type
string

Ne renvoie que les documents du type donné.:

  • report
  • commercial_offer
  • contribution_framework
  • dimensioning_note
  • sworn_statement
begin
string

Ne renvoie que les documents générés à partir de cette date (ISO 8601).

end
string

Ne renvoie que les documents générés jusqu'à cette date (ISO 8601).

page
integer

Numéro de page.

per_page
integer

Nombre de documents par page (par défaut 1000).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Lancer la génération du document : Rapport complet

Lance la génération asynchrone du document PDF « Rapport complet » pour la simulation. Renvoie l'identifiant de la génération à utiliser pour interroger son statut. Répond 403 si le document dépend d'une configuration d'équipe désactivée, et 422 si les données de la simulation ne permettent pas de produire le document.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Request Body schema: application/json
scenario_ids
Array of strings

Optionnel. Identifiants des plans de rénovation à inclure (par défaut : tous les plans éligibles). Utilisé uniquement pour les documents liés à un scénario.

Responses

Request samples

Content type
application/json
{
  • "scenario_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "operation_id": "op1a2b3c4d",
  • "document_type": "report"
}

Lancer la génération du document : Cadre de contribution

Lance la génération asynchrone du document PDF « Cadre de contribution » pour la simulation. Renvoie l'identifiant de la génération à utiliser pour interroger son statut. Répond 403 si le document dépend d'une configuration d'équipe désactivée, et 422 si les données de la simulation ne permettent pas de produire le document.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Request Body schema: application/json
scenario_ids
Array of strings

Optionnel. Identifiants des plans de rénovation à inclure (par défaut : tous les plans éligibles). Utilisé uniquement pour les documents liés à un scénario.

Responses

Request samples

Content type
application/json
{
  • "scenario_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "operation_id": "op1a2b3c4d",
  • "document_type": "report"
}

Lancer la génération du document : Note de dimensionnement

Lance la génération asynchrone du document PDF « Note de dimensionnement » pour la simulation. Renvoie l'identifiant de la génération à utiliser pour interroger son statut. Répond 403 si le document dépend d'une configuration d'équipe désactivée, et 422 si les données de la simulation ne permettent pas de produire le document.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Request Body schema: application/json
scenario_ids
Array of strings

Optionnel. Identifiants des plans de rénovation à inclure (par défaut : tous les plans éligibles). Utilisé uniquement pour les documents liés à un scénario.

Responses

Request samples

Content type
application/json
{
  • "scenario_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "operation_id": "op1a2b3c4d",
  • "document_type": "report"
}

Lancer la génération du document : Attestation sur l'honneur

Lance la génération asynchrone du document PDF « Attestation sur l'honneur » pour la simulation. Renvoie l'identifiant de la génération à utiliser pour interroger son statut. Répond 403 si le document dépend d'une configuration d'équipe désactivée, et 422 si les données de la simulation ne permettent pas de produire le document.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Request Body schema: application/json
scenario_ids
Array of strings

Optionnel. Identifiants des plans de rénovation à inclure (par défaut : tous les plans éligibles). Utilisé uniquement pour les documents liés à un scénario.

Responses

Request samples

Content type
application/json
{
  • "scenario_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "operation_id": "op1a2b3c4d",
  • "document_type": "report"
}

Lancer la génération du document : Offre commerciale

Crée un devis à partir d'un plan de rénovation, puis lance la génération asynchrone du PDF « Offre commerciale ». Renvoie l'identifiant de la génération à utiliser pour interroger son statut, ainsi que l'identifiant du devis créé. Répond 403 si les devis sont désactivés pour l'équipe, et 422 si le plan de rénovation est inconnu.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Request Body schema: application/json
required
renovation_plan_id
required
string

Identifiant du plan de rénovation (sqid du scénario) à partir duquel créer le devis.

Responses

Request samples

Content type
application/json
{
  • "renovation_plan_id": "rp1a2b3c4d"
}

Response samples

Content type
application/json
{
  • "operation_id": "op1a2b3c4d",
  • "document_type": "commercial_offer",
  • "quotation_id": "quo1a2b3c4d"
}

Récupérer le statut d'une génération de document

Récupère le statut de la génération d'un document et l'URL de téléchargement lorsqu'il est prêt.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

id
required
string
Example: op1a2b3c4d

L'identifiant de génération renvoyé par le endpoint de lancement

Responses

Response samples

Content type
application/json
{}

Webhooks

kelvin envoie des événements métier en POST JSON vers une URL HTTPS que vous configurez (administration kelvin). Ce ne sont pas des endpoints que vous appelez : kelvin appelle votre serveur.

Sécurité

  • Chaque requête est signée avec un secret affiché une seule fois à la création de la destination.
  • Headers : Kelvin-Webhook-Id, Kelvin-Webhook-Timestamp, Kelvin-Webhook-Signature (v1= + HMAC-SHA256 hex de timestamp + "." + raw_body).
  • La destination peut aussi recevoir des en-têtes HTTP supplémentaires configurés côté administration kelvin ; le corps JSON reste inchangé.
  • Vérifiez la signature sur le corps brut avant de parser le JSON ; comparez en temps constant ; tolérance de timestamp recommandée : 5 minutes ; le header Kelvin-Webhook-Id doit égaler le champ id du JSON.
  • Transport au moins une fois : dédupliquez avec le champ id authentifié.
  • Répondez 2xx pour confirmer ; les redirections ne sont pas suivies ; kelvin retente une fois en cas d'échec de destination.

Actions

  • simulation/create_lead : premier envoi réussi des coordonnées d'un prospect.
  • simulation/update_lead : recalcul des scénarios après création du prospect (ex. POST /api/v3/simulations/{id}/run ou visite workplans quand la simulation est outdated). Même bloc data que la création.
  • simulation/create_document : génération réussie d'un document. data.document contient id (génération), simulation_id (simulation mère) et document_type. Détails : GET /api/v3/simulations/{simulation_id}/documents/{id}.

Création d'un prospect Webhook

Émis lors du premier envoi réussi des coordonnées d'un prospect.

kelvin envoie ce POST vers votre URL HTTPS, pas vers une route kelvin.

Le bloc data est identique pour simulation/create_lead et simulation/update_lead.

header Parameters
Kelvin-Webhook-Id
required
string

Identifiant stable de l'événement (SQID), égal au champ id

Kelvin-Webhook-Timestamp
required
string

Timestamp Unix décimal utilisé pour la signature

Kelvin-Webhook-Signature
required
string

Signature HMAC-SHA256 préfixée par v1=

Request Body schema: application/json
required
id
required
string

SQID de l'événement (égal à Kelvin-Webhook-Id)

action
required
string
Enum: "simulation/create_lead" "simulation/update_lead"
version
required
integer
occurred_at
required
string <date-time>
required
object
required
object (WebhookLeadData)

Snapshot métier partagé par simulation/create_lead et simulation/update_lead

Responses

Request samples

Content type
application/json
{
  • "id": "fhxd453xh6",
  • "action": "simulation/create_lead",
  • "version": 1,
  • "occurred_at": "2026-07-15T10:32:00Z",
  • "team": {
    },
  • "data": {
    }
}

Mise à jour d'un prospect Webhook

Émis lorsque les scénarios sont recalculés après création du prospect (par ex. POST /api/v3/simulations/{id}/run ou visite de la page workplans alors que la simulation est outdated).

kelvin envoie ce POST vers votre URL HTTPS, pas vers une route kelvin.

Le bloc data est identique pour simulation/create_lead et simulation/update_lead.

header Parameters
Kelvin-Webhook-Id
required
string

Identifiant stable de l'événement (SQID), égal au champ id

Kelvin-Webhook-Timestamp
required
string

Timestamp Unix décimal utilisé pour la signature

Kelvin-Webhook-Signature
required
string

Signature HMAC-SHA256 préfixée par v1=

Request Body schema: application/json
required
id
required
string

SQID de l'événement (égal à Kelvin-Webhook-Id)

action
required
string
Enum: "simulation/create_lead" "simulation/update_lead"
version
required
integer
occurred_at
required
string <date-time>
required
object
required
object (WebhookLeadData)

Snapshot métier partagé par simulation/create_lead et simulation/update_lead

Responses

Request samples

Content type
application/json
{
  • "id": "fhxd453xh6",
  • "action": "simulation/create_lead",
  • "version": 1,
  • "occurred_at": "2026-07-15T10:32:00Z",
  • "team": {
    },
  • "data": {
    }
}

Génération d'un document Webhook

Émis lorsqu'un document est généré avec succès (rapport, offre commerciale, cadre de contribution, note de dimensionnement, attestation sur l'honneur).

Cela inclut POST /api/v3/simulations/{id}/documents/{type} et les exports depuis l'interface kelvin (rapport ou offre commerciale). Un export UI qui regroupe des pages CEE ou de dimensionnement reste un document_type report.

kelvin envoie ce POST vers votre URL HTTPS, pas vers une route kelvin.

data.document identifie la génération. Récupérez le statut et l'URL de téléchargement via GET /api/v3/simulations/{simulation_id}/documents/{id}.

header Parameters
Kelvin-Webhook-Id
required
string

Identifiant stable de l'événement (SQID), égal au champ id

Kelvin-Webhook-Timestamp
required
string

Timestamp Unix décimal utilisé pour la signature

Kelvin-Webhook-Signature
required
string

Signature HMAC-SHA256 préfixée par v1=

Request Body schema: application/json
required
id
required
string

SQID de l'événement (égal à Kelvin-Webhook-Id)

action
required
string
Value: "simulation/create_document"
version
required
integer
occurred_at
required
string <date-time>
required
object
required
object (WebhookDocumentData)

Pointeur vers une génération de document (simulation/create_document)

Responses

Request samples

Content type
application/json
{
  • "id": "fhxd453xh6",
  • "action": "simulation/create_document",
  • "version": 1,
  • "occurred_at": "2026-07-15T10:32:00Z",
  • "team": {
    },
  • "data": {
    }
}

Lister les simulations

Endpoint pour lister les simulations.

Authorizations:
bearerAuth
query Parameters
status
string
Value: "with_contact_details"
Example: status=with_contact_details

Filtrer les simulations avec des informations de contact:

  • with_contact_details
page
integer
Example: page=1

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Récupérer une simulation

Endpoint pour récupérer une simulation par son identifiant. Seules les simulations complétées accessibles à l'équipe (propriétaire ou partagée) sont retournées, comme dans la liste.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1fh9vrmd2c

L'identifiant (SQID) de la simulation

Responses

Response samples

Content type
application/json
{
  • "id": "1fh9vrmd2c",
  • "created_at": "2024-10-08T10:00:54Z",
  • "simulation_url": "https://app.go-kelvin.com/simulator/4732fnd4mt/simulations/1fh9vrmd2c",
  • "team_id": "4732fnd4mt",
  • "source": "api",
  • "tracking_context": {
    },
  • "client": {
    },
  • "housing": {
    },
  • "initial_state": {
    },
  • "projected_state": {
    }
}