openapi: 3.1.0
info:
title: kelvin API
version: v3
description: '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.
### 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](https://app.go-kelvin.com/docs/simulator-map-iframe#/).
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) :
```json
"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 :
```json
"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²).
'
tags:
- name: Simulateur
description: Endpoints disponibles dans l'offre Simulateur
- name: Qualification
description: Endpoints disponibles dans l'offre Qualification
- name: Documents
description: Endpoints pour consulter les documents générés pour une simulation
paths:
/api/v3/catalog/enabled/gestures:
get:
summary: Lister les gestes activés pour l'équipe
tags:
- Qualification
description: '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.
'
security:
- bearerAuth: []
parameters:
- name: gesture_technical_ids
in: query
required: false
schema:
type: array
items:
type: string
explode: true
example:
- roof_windows_double_glazed
description: 'Filtre optionnel : limite le résultat aux gestes correspondant à ces identifiants techniques.'
responses:
'200':
description: Liste des gestes activés
content:
application/json:
schema:
type: object
properties:
gestures:
type: array
items:
type: object
properties:
id:
type: string
example: 3f2a1b9c-1234-4c56-89ab-0123456789ab
description: Identifiant (UUID) du geste.
technical_id:
type: string
example: roof_windows_double_glazed
description: Identifiant technique du geste.
name:
type: string
example: Fenêtres de toit double vitrage
description: Nom du geste.
category:
type: object
properties:
technical_id:
type: string
example: windows
description: Identifiant technique de la catégorie.
name:
type: string
example: Windows
description: Nom de la catégorie.
default_service:
type: object
description: Prestation par défaut du geste pour l'équipe (absent si aucune prestation par défaut).
properties:
id:
type: string
example: 7c9e6679-1234-40de-944b-0123456789ab
description: Identifiant (UUID) de la prestation.
technical_id:
type: string
example: roof_windows_double_glazed_pvc
description: Identifiant technique de la prestation.
price_unit:
type:
- string
- 'null'
example: unit
description: Unité de tarification de la prestation.
required:
- id
- technical_id
- name
- category
required:
- gestures
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: unauthorized
'403':
description: Forbidden - scope catalog:read manquant
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: missing_scope
/api/v3/catalog/enabled/references:
get:
summary: Lister les références activées pour l'équipe
tags:
- Qualification
description: '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).
'
security:
- bearerAuth: []
parameters:
- name: service_technical_ids
in: query
required: false
schema:
type: array
items:
type: string
explode: true
example:
- french_doors_double_glazed_wood_aluminium
description: Filtre par identifiants techniques de prestations.
- name: gestures_technical_ids
in: query
required: false
schema:
type: array
items:
type: string
explode: true
example:
- french_doors_double_glazed
description: Filtre par identifiants techniques de gestes.
- name: reference_ids
in: query
required: false
schema:
type: array
items:
type: string
explode: true
example:
- 919ce243-1385-46d7-afd6-41ea8629a40d
description: Filtre par identifiants (UUID) de références.
responses:
'200':
description: Liste des références activées
content:
application/json:
schema:
type: object
properties:
references:
type: array
items:
type: object
properties:
id:
type: string
example: 919ce243-1385-46d7-afd6-41ea8629a40d
description: Identifiant (UUID) de la référence.
brand:
type:
- string
- 'null'
example: Velux
description: Marque de la référence.
model:
type:
- string
- 'null'
example: GGL MK04
description: Modèle de la référence.
url:
type:
- string
- 'null'
example: https://example.com/produit
description: URL de la fiche produit.
price:
type:
- number
- 'null'
format: float
example: 350
description: Prix HT pour l'équipe, en Euros.
tax:
type:
- number
- 'null'
format: float
example: 0.055
description: Taux de TVA applicable.
default:
type: boolean
example: true
description: Indique si cette référence est la référence par défaut de l'équipe pour la prestation
(ou le groupe de références).
gesture:
type: object
properties:
technical_id:
type: string
example: french_doors_double_glazed
description: Identifiant technique du geste parent.
service:
type: object
properties:
technical_id:
type: string
example: french_doors_double_glazed_wood_aluminium
description: Identifiant technique de la prestation parente.
required:
- id
- gesture
- service
required:
- references
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: unauthorized
'403':
description: Forbidden - scope catalog:read manquant
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: missing_scope
'422':
description: Aucun filtre fourni
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: 'At least one filter is required: reference_ids, gestures_technical_ids, service_technical_ids'
/api/v3/catalog/enabled/services:
get:
summary: Lister les prestations activées pour l'équipe
tags:
- Qualification
description: '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.
'
security:
- bearerAuth: []
parameters:
- name: service_technical_ids
in: query
required: false
schema:
type: array
items:
type: string
explode: true
example:
- french_doors_double_glazed_wood_aluminium
description: 'Filtre optionnel : limite le résultat aux prestations correspondant à ces identifiants techniques.'
responses:
'200':
description: Liste des prestations activées
content:
application/json:
schema:
type: object
properties:
services:
type: array
items:
type: object
properties:
id:
type: string
example: 7c9e6679-1234-40de-944b-0123456789ab
description: Identifiant (UUID) de la prestation.
technical_id:
type: string
example: french_doors_double_glazed_wood_aluminium
description: Identifiant technique de la prestation.
name:
type: string
example: Porte-fenêtre double vitrage bois-aluminium
description: Nom de la prestation.
price_unit:
type:
- string
- 'null'
example: unit
description: Unité de tarification de la prestation.
default:
type: boolean
example: true
description: Indique si cette prestation est la prestation par défaut de l'équipe pour son geste.
gesture:
type: object
properties:
technical_id:
type: string
example: french_doors_double_glazed
description: Identifiant technique du geste parent.
category:
type: object
properties:
technical_id:
type: string
example: windows
description: Identifiant technique de la catégorie.
name:
type: string
example: Windows
description: Nom de la catégorie.
required:
- id
- technical_id
- name
- gesture
- category
required:
- services
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: unauthorized
'403':
description: Forbidden - scope catalog:read manquant
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: missing_scope
/api/v3/dpes:
get:
summary: Rechercher des DPE par clé d'interopérabilité ou par numéro DPE.
tags:
- Qualification
description: '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.'
security:
- bearerAuth: []
parameters:
- name: dpe_id
in: query
required: false
example: 2331E2555868X
schema:
type: string
- name: building_type
in: query
required: false
example: house
description: "Le type de bâtiment:\n * `apartment` \n * `house` \n * `building` \n * `unknown` \n "
schema:
type: string
enum:
- apartment
- house
- building
- unknown
- name: ban_id
in: query
required: false
example: '31157_0790_00009'
schema:
type: string
- name: surface
in: query
required: false
example: 100
schema:
type: number
- name: report_date
in: query
required: false
example: '2024-01-01'
schema:
type: string
- name: energy_class
in: query
required: false
example: E
schema:
type: string
responses:
'200':
description: successful
content:
application/json:
schema:
type: array
items:
type: object
properties:
dpe_id:
type: string
example: 2331E2555868X
description: Le numéro unique du DPE.
building_type:
type: string
example: house
enum:
- apartment
- house
- building
- unknown
description: Le type de bâtiment.
ban_id:
type: string
example: '31157_0790_00009'
description: clé d'interopérabilité.
energy_class:
type: string
example: A
description: La classe énergétique du DPE.
emission_class:
type: string
example: B
description: La classe d'émission du DPE.
surface:
type: number
example: 100
description: La surface.
report_date:
type: string
example: '2024-05-10'
description: La date à laquelle le DPE a été établi.
address:
type: string
example: 9 Rue du Vivier, Cugnaux, 31270
description: L'adresse associée au DPE
address_complement:
type: string
example: 'Escalier: Etage 3; Porte 322, Lot: 10'
description: Détails supplémentaires pour l'adresse.
dpe_version:
type: string
example: '2.4'
description: La version du dpe.
required:
- dpe_id
- ban_id
- energy_class
- emission_class
- surface
- report_date
- address
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Required dpe_id and ban_id are both missing
description: Error message indicating the issue.
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Unauthorized
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Forbidden
/api/v3/simulations:
get:
summary: Lister les simulations
description: Endpoint pour lister les simulations.
security:
- bearerAuth: []
parameters:
- name: status
in: query
required: false
example: with_contact_details
description: "Filtrer les simulations avec des informations de contact:\n * `with_contact_details` \n "
schema:
type: string
enum:
- with_contact_details
- name: page
in: query
required: false
example: 1
schema:
type: integer
responses:
'200':
description: successful
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
example: 1fh9vrmd2c
description: L'identifiant de la simulation
created_at:
type: string
format: date-time
example: '2024-10-08T10:00:54Z'
description: La date de création de la simulation
simulation_url:
type: string
format: uri
example: https://app.go-kelvin.com/simulator/4732fnd4mt/simulations/1fh9vrmd2c
description: L'adresse web du résultat de la simulation
team_id:
type: string
example: 4732fnd4mt
description: L'identifiant de l'équipe
source:
type: string
enum:
- simulator
- qualification
- api
- prospection
example: api
description: La source de la simulation
tracking_context:
type: object
description: Les informations de tracking extraites du contexte de lancement de la simulation
properties:
utm_source:
type:
- string
- 'null'
utm_medium:
type:
- string
- 'null'
utm_campaign:
type:
- string
- 'null'
utm_content:
type:
- string
- 'null'
utm_term:
type:
- string
- 'null'
gad_source:
type:
- string
- 'null'
gclid:
type:
- string
- 'null'
fbclid:
type:
- string
- 'null'
cuid:
type:
- string
- 'null'
referer:
type:
- string
- 'null'
gbraid:
type:
- string
- 'null'
msclkid:
type:
- string
- 'null'
krid:
type:
- string
- 'null'
krsrc:
type:
- string
- 'null'
ksid:
type:
- string
- 'null'
client:
type: object
description: Les informations du client
properties:
first_name:
type:
- string
- 'null'
example: Jean
description: Le prénom du client
last_name:
type:
- string
- 'null'
example: Dupont
description: Le nom de famille du client
email:
type:
- string
- 'null'
example: jean.dupont@example.com
description: L'email du client
phone_number:
type:
- string
- 'null'
example: '+33600112233'
description: Le téléphone du client
profile:
# --- truncated at 32 KB (348 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kelvin/refs/heads/main/openapi/kelvin-api-openapi.yml