Kelvin Qualification API

openapi: 3.2.0
info:
  title: Kelvin Qualification API
  version: '1.0'
  description: 'Operations tagged Qualification 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: Qualification
  description: Endpoints disponibles dans l'offre Qualification
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
    servers:
    - url: '{protocol}://{defaultHost}'
      variables:
        protocol:
          default: https
        defaultHost:
          default: app.go-kelvin.com
  /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'
    servers:
    - url: '{protocol}://{defaultHost}'
      variables:
        protocol:
          default: https
        defaultHost:
          default: app.go-kelvin.com
  /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
    servers:
    - url: '{protocol}://{defaultHost}'
      variables:
        protocol:
          default: https
        defaultHost:
          default: app.go-kelvin.com
  /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
    servers:
    - url: '{protocol}://{defaultHost}'
      variables:
        protocol:
          default: https
        defaultHost:
          default: app.go-kelvin.com
  /api/v3/simulations/{simulation_id}/initial-state:
    get:
      summary: Récupérer l'état initial
      tags:
      - Qualification
      description: Les informations de l'état initial.
      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.
                  initial_state:
                    type: object
                    properties:
                      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
                      energy_consumption:
                        type: integer
                        example: 201
                        description: La consommation énergétique en kWh/m²/an.
                      carbon_rating:
                        type: string
                        enum:
                        - A
                        - B
                        - C
                        - D
                        - E
                        - F
                        - G
                        example: C
                        description: La lettre GES
                      carbon_emissions:
                        type: integer
                        example: 40
                        description: Les émissions de gaz à effet de serre en kg CO2/m²/an.
                      epc_id:
                        type:
                        - string
                        - 'null'
                        example: 2169E0063000A
                        description: Le numéro du DPE s'il y a un DPE attaché à la simulation.
                      confidence_score:
                        type: number
                        format: float
                        example: 0.85
                        description: Le score de confiance concernant la lettre du DPE.
                      annual_energy_cost_range:
                        type: object
                        properties:
                          min:
                            type: integer
                            example: 500
                            description: '[Déprécié] Le minimum du prix annuel estimé de chauffage.'
                          max:
                            type: number
                            format: float
                            example: 1200
                            description: '[Déprécié] Le maximum du prix annuel estimé de chauffage.'
                      annual_energy_consumption:
                        type: integer
                        example: 150
                        description: La consommation énergétique annuelle exprimée en kWh/m²/an.
                      position_percentage_neighborhood:
                        type: number
                        format: float
                        example: 0.75
                        description: Le pourcentage de logements du quartier qui consomment plus que le logement en question.
                      energy_loss_percentage:
                        type: object
                        properties:
                          walls:
                            type: number
                            format: float
                            example: 0.15
                            description: Le pourcentage de perte d'énergie des murs.
                          openings:
                            type: number
                            format: float
                            example: 0.2
                            description: Le pourcentage de perte d'énergie des ouvrants.
                          low_floor:
                            type: number
                            format: float
                            example: 0.3
                            description: Le pourcentage de perte d'énergie des planchers bas.
                          high_floor:
                            type: number
                            format: float
                            example: 0.35
                            description: Le pourcentage de perte d'énergie des plafonds.
                      close_to_historical_monument:
                        type: boolean
                        example: false
                        description: Proximité d'un monument historique.
                      living_area:
                        type: number
                        example: 120
                        description: La surface habitable en mètres carrés.
                      exterior_walls_surface:
                        type: integer
                        example: 100
                        description: La surface extérieure des murs en mètres carrés.
                      house_number_of_levels:
                        type: integer
                        example: 1
                        description: Le nombre de niveaux dans la maison.
                      shared_walls:
                        type: boolean
                        example: true
                        description: Présence de murs mitoyens.
                      wall_material:
                        type: 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
                        example: brick
                        description: Le matériau principal des murs.
                      construction_year:
                        type: integer
                        example: 1985
                        description: L'année de construction du bâtiment.
                      number_of_windows:
                        type: integer
                        example: 8
                        description: Le nombre total de fenêtres.
                      generator_type:
                        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
                        - unknown
                        example: condensing_gas_boiler
                        description: Le type de générateur de chauffage.
                      generator_energy:
                        type: string
                        enum:
                        - electricity
                        - fuel
                        - gas
                        - biomass_wood
                        - district_heating
                        - others
                        - unknown
                        example: gas
                        description: Le type d'énergie utilisé par le générateur de chauffage.
                      hot_water_type:
                        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
                        - unknown
                        example: electric_hot_water_tank
                        description: Le type de système de production d'eau chaude sanitaire.
                      hot_water_energy:
                        type: string
                        enum:
                        - electricity
                        - fuel
                        - gas
                        - biomass_wood
                        - district_heating
                        - others
                        - unknown
                        example: electricity
                        description: Le type d'énergie utilisé pour l'eau chaude sanitaire.
                      walls_insulation:
                        type:
                        - object
    

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