Kelvin Simulateur API

openapi: 3.2.0
info:
  title: Kelvin Simulateur API
  version: '1.0'
  description: 'Operations tagged Simulateur across 2 of this provider''s published API definitions: kelvin-api-openapi.yml, kelvin-api-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: '{protocol}://{defaultHost}'
  variables:
    protocol:
      default: https
    defaultHost:
      default: app.go-kelvin.com
security:
- bearerAuth: []
tags:
- name: Simulateur
  description: Endpoints disponibles dans l'offre Simulateur
paths:
  /api/v3/simulations:
    post:
      summary: Créer une simulation
      tags:
      - Simulateur
      description: Endpoint pour créer une simulation à partir d'un ban_id et des coordonnées GPS.
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  simulation_id:
                    type: string
                    example: hjjcm1qp28
                    description: L'identifiant de la simulation créée.
                required:
                - simulation_id
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Latitude is missing, Longitude is 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
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Could not find an address for the given GPS coordinates
                    description: Error message indicating the issue.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                latitude:
                  type: number
                  example: 43.53718
                longitude:
                  type: number
                  example: 1.337797
                ban_id:
                  type: string
                  example: '31157_0790_00009'
              required:
              - latitude
              - longitude
    servers:
    - url: '{protocol}://{defaultHost}'
      variables:
        protocol:
          default: https
        defaultHost:
          default: app.go-kelvin.com
  /api/v3/simulations/{simulation_id}/housing:
    get:
      summary: Récupérer les informations de la propriété
      tags:
      - Simulateur
      description: Les informations de la propriété.
      security:
      - bearerAuth: []
      parameters:
      - name: simulation_id
        in: path
        required: true
        example: hjjcm1qp28
        description: L'identifiant de simulation renvoyé par l'appel au endpoint créer
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - pending
                    - processing
                    - completed
                    - failed
                    example: completed
                    description: Le statut de l'opération de génération de résultat.
                  housing:
                    type: object
                    properties:
                      housing_type:
                        type:
                        - string
                        - 'null'
                        enum:
                        - house
                        - apartment
                        - unknown
                        example: apartment
                        description: Le type de la propriété.
                      epc_id:
                        type:
                        - string
                        - 'null'
                        example: 2331E2555868X
                        description: Le numéro unique du DPE.
                      surface:
                        type:
                        - integer
                        - 'null'
                        example: 100
                        description: La surface de la propriété en m2.
                      floor_level:
                        type:
                        - string
                        - 'null'
                        enum:
                        - ground
                        - intermediate
                        - last
                        example: ground
                        description: La position da le propriété dans l'immeuble.
                      number_of_exterior_wall:
                        type:
                        - integer
                        - 'null'
                        example: 1
                        description: Le nombre de murs donnant sur l'extérieur.
                  address:
                    type: object
                    properties:
                      street_number:
                        type: string
                        example: '123'
                        description: Le numéro de la rue.
                      address_line_1:
                        type: string
                        example: Rue de la Paix
                        description: Le nom de la rue.
                      address_line_2:
                        type:
                        - string
                        - 'null'
                        example: Apt 4B
                        description: Complément d'adresse.
                      city:
                        type: string
                        example: Paris
                        description: La ville.
                      postal_code:
                        type: string
                        example: '75000'
                        description: Le code postal.
                      country_number:
                        type: integer
                        example: 250
                        description: Le numéro du pays, code ISO3166. France = 250
                      latitude:
                        type: number
                        example: 43.53718
                        description: La latitude.
                      longitude:
                        type: number
                        example: 1.337797
                        description: La longitude.
                required:
                - housing
                - status
                - address
        '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
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Could not find the simulation
                    description: Error message indicating the issue.
    put:
      summary: Mettre à jour les informations de la propriété
      tags:
      - Simulateur
      description: Endpoint pour mettre à jour les informations de la propriété
      security:
      - bearerAuth: []
      parameters:
      - name: simulation_id
        in: path
        required: true
        example: hjjcm1qp28
        description: L'identifiant de simulation renvoyé par l'appel au endpoint créer
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Housing type is missing or invalid
                    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
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                epc_id:
                  type: string
                  example: 2331E2555868X
                  description: Le numéro unique du DPE.
                housing_type:
                  type: string
                  enum:
                  - house
                  - apartment
                  example: apartment
                  description: Le type de propriété.
                surface:
                  type: integer
                  example: 100
                  description: La surface de la propriété en m2. Obligatoire si le housing_type est apartment.
                floor_level:
                  type: string
                  enum:
                  - ground
                  - intermediate
                  - last
                  example: ground
                  description: La position da le propriété dans l'immeuble. Obligatoire si le housing_type est apartment.
                number_of_exterior_wall:
                  type: integer
                  example: 1
                  description: Le nombre de murs donnant sur l'extérieur. Obligatoire si le housing_type est apartment.
              required:
              - simulation_id
              - post_params
    servers:
    - url: '{protocol}://{defaultHost}'
      variables:
        protocol:
          default: https
        defaultHost:
          default: app.go-kelvin.com
  /api/v3/simulations/{simulation_id}/qualification:
    put:
      summary: Qualifier le profil de l'utilisateur
      tags:
      - Simulateur
      description: '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.

        '
      security:
      - bearerAuth: []
      parameters:
      - name: simulation_id
        in: path
        required: true
        example: hjjcm1qp28
        description: L'identifiant de la simulation.
        schema:
          type: string
      responses:
        '204':
          description: Qualification enregistrée avec succès.
        '400':
          description: Bad Request - code département fiscal invalide
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Tax residence department is invalid
                    description: Le code département ne correspond à aucun département connu.
        '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
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Could not find the simulation
                    description: La simulation n'existe pas ou n'appartient pas à cette équipe.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                profile:
                  type: string
                  enum:
                  - owner_resident
                  - owner_non_resident
                  - renter
                  - lessor
                  example: owner_resident
                  description: '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:
                  type: boolean
                  example: true
                  description: 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:
                  type: integer
                  minimum: 1
                  maximum: 12
                  example: 4
                  description: Nombre de personnes dans le foyer fiscal.
                tax_residence_department:
                  type: string
                  example: '75'
                  description: '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:
                  type: string
                  enum:
                  - very_modest
                  - modest
                  - intermediate
                  - superior
                  example: modest
                  description: '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:
                  type: string
                  enum:
                  - curious
                  - searching
                  - estimated
                  - signed
                  example: curious
                  description: 'Maturité du projet de rénovation. `curious` : en phase de découverte. `searching` : en recherche active. `estimated` : devis reçu. `signed` : devis signé.'
              required:
              - profile
              - household_size
              - income_range
        required: true
    servers:
    - url: '{protocol}://{defaultHost}'
      variables:
        protocol:
          default: https
        defaultHost:
          default: app.go-kelvin.com
  /api/v3/simulations/{simulation_id}/run:
    post:
      summary: Lancer la simulation
      tags:
      - Simulateur
      description: Endpoint pour lancer la simulation.
      security:
      - bearerAuth: []
      parameters:
      - name: simulation_id
        in: path
        required: true
        example: hjjcm1qp28
        description: L'identifiant de simulation renvoyé par l'appel au endpoint créer
        schema:
          type: string
      responses:
        '201':
          description: Created
        '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
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Could not find the simulation
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Apartment information is needed
    servers:
    - url: '{protocol}://{defaultHost}'
      variables:
        protocol:
          default: https
        defaultHost:
          default: app.go-kelvin.com
  /api/v3/simulations/{simulation_id}/projected-state:
    get:
      summary: Récupérer l'état projeté
      tags:
      - Simulateur
      description: Les informations de l'état projeté.
      security:
      - bearerAuth: []
      parameters:
      - name: simulation_id
        in: path
        required: true
        example: hjjcm1qp28
        description: L'identifiant de simulation renvoyé par l'appel au endpoint créer
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - pending
                    - processing
                    - completed
                    - failed
                    example: completed
                    description: Le statut de l'opération de génération de résultat.
                  projected_state:
                    type: object
                    properties:
                      renovation_plans:
                        type: array
                        items:
                          type: object
                          description: Liste des plans de rénovation.
                          properties:
                            id:
                              type: string
                              example: hjjcm1qp28
                              description: L'identifiant du plan de rénovation.
                            name:
                              type: string
                              example: Mon plan personnalisé
                              description: Le nom du plan de rénovation.
                            type:
                              type: string
                              enum:
                              - normal
                              - customized
                              - optimized
                              example: customized
                              description: Le type de plan de rénovation.
                            overall_rating:
                              type: string
                              enum:
                              - A
                              - B
                              - C
                              - D
                              - E
                              - F
                              - G
                              example: B
                              description: La lettre DPE globale (la plus défavorable entre énergie et GES).
                            energy_rating:
                              type: string
                              enum:
                              - A
                              - B
                              - C
                              - D
                              - E
                              - F
                              - G
                              example: B
                              description: La lettre énergie après rénovation.
                            energy_consumption:
                              type: integer
                              example: 201
                              description: La consommation énergétique après rénovation en kWh/m²/an.
                            carbon_rating:
                              type: string
                              enum:
                              - A
                              - B
                              - C
                              - D
                              - E
                              - F
                              - G
                              example: C
                              description: La lettre GES après rénovation.
                            carbon_emissions:
                              type: integer
                              example: 40
                              description: Les émissions de gaz à effet de serre après rénovation en kg CO2/m²/an.
                            yearly_energy_savings:
                              type: number
                              format: float
                              description: Économies d'énergie annuelles estimées en Euros.
                              example: 600
                            yearly_energy_cost:
                              type: number
                              format: float
                              description: Coût énergétique annuel estimé en Euros.
                              example: 12000
                            budget:
                              type: number
                              format: float
                              description: Coût total estimé du plan de travaux en Euros.
                              example: 12000
                            financial_support:
                              $ref: '#/components/schemas/FinancialSupport'
                            kpi:
                              type: object
                              description: Indicateurs clés de performance du plan de rénovation.
                              properties:
                                property_value_increase:
                                  type: object
                                  description: Valorisation immobilière estimée suite aux travaux.
                                  properties:
                                    percentage:
                                      type: number
                                      format: float
                                      description: Pourcentage d'augmentation de la valeur immobilière.
                                      example: 5
                                    price_per_sqm:
                                      type: number
                                      format: float
                                      description: Valorisation estimée en €/m².
                                      example: 115
                                    area_loss_sqm:
                                      type: number
                                      format: float
                                      description: Perte de surface en m² due aux travaux.
                                      example: 0
                            renovation_plan:
                              type: object
                              description: Liste des tâches du plan de rénovation.
                              properties:
                                ventilation:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      technical_id:
                                        type: string
                                        enum:
                                        - dual_flow_ventilation
                                        - single_flow_ventilation_self_regulating
                                        - air_destratifier
                                        - mechanical_distributed_ventilation
                                        - dual_flow_ventilation_thermodynamic
                                        - single_flow_ventilation_humidity_controlled
                                        - ventilation_mechanical_insufflation
                                      name:
                                        type: string
                                        enum:
                                        - Installation d'une VMC double flux
                                        - Installation d'une VMC simple flux autoréglable
                                        - Installation d'un destratificateur d'air
                                        - Installation d'un système de ventilation mécanique répartie (VMR)
                                        - Installation d'une VMC double flux thermodynamique
                                        - Installation d'une VMC simple flux hygroréglable
                                        - Installation d'un système de ventilation mécanique par insufflation (VMI)
                                      quantity:
                                        type: integer
                                        description: Nombre d'unités
                                      budget:
                                        type: number
                                        format: float
                                        description: Coût estimé des travaux (en euros)
                                      financial_support:
                                        $ref: '#/components/schemas/GestureFinancialSupport'
                                      service_technical_id:
                                        type: string
                                        nullable: true
                                        description: L'identifiant technique de la prestation (service) du catalogue.
                                      reference_id:
                                        type: string
                                        nullable: true
                                        description: L'identifiant de la référence catalogue sélectionnée.
                                      price_per_unit:
                                        type: number
                                        format: float
                                        nullable: true
                                        description: Le prix unitaire hors taxes retenu.
                                      vat:
                                        type: number
                                        format: float
                                        nullable: true
                                        description: 'Le taux de TVA appliqué (en pourcentage, ex: 5.5).'
                                walls:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      technical_id:
                                        type: string
                                        enum:
                                        - exterior_thermal_correction
                                        - interior_thermal_insulation
                                        - exterior_thermal_insulation
                                        - exterior_thermal_insulation_historic
                                        - interior_thermal_insulation_thin
                                      name:
                                        type: string
                                        enum:
                                        - Réalisation d'une correction thermique par l'extérieur
                                        - Isolation thermique des murs par l'intérieur (ITI)
                                        - Isolation thermique des murs par l'extérieur (ITE)
                                        - Isolation thermique des murs par l'extérieur (ITE) en zone historique
                                        - Isolation thermique des murs par l'intérieur (ITI) avec isolant mince
                                      quantity:
                                        type: integer
                                        description: Surface en m²
                                      budget:
                                        type: number
                                        format: float
                                        description: Coût estimé des travaux (en euros)
                                      financial_support:
                                        $ref: '#/components/schemas/GestureFinancialSupport'
                                      service_technical_id:
                                        type: string
                                        nullable: true
                                        description: L'identifiant technique de la prestation (service) du catalogue.
                                      reference_id:
                                        type: string
                                        nullable: true
                                        description: L'identifiant de la référence catalogue sélectionnée.
                                      price_per_unit:
                                        type: number
                                        format: float
                                        nullable: true
                                        description: Le prix unitaire hors taxes retenu.
                                      vat:
                                        type: number
                                        format: float
                                        nullable: true
                                        description: 'Le taux de TVA appliqué (en pourcentage, ex: 5.5).'
                                doors_windows:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      technical_id:
                                        type: string
                                        enum:
                                        - windows_triple_glazed
                                        - doors_double_glazed
                                        - windows_double_glazed_historic
                                        - french_doors_double_glazed_historic
                                        - doors_full_historic
                                        - roof_windows_triple_glazed_historic
                                        - french_doors_triple_glazed
                                        - roof_windows_triple_glazed
                                       

# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kelvin/refs/heads/main/openapi/kelvin-simulateur-api-openapi.yml