FairePlace Energy Diagnosis API

openapi: 3.2.0
info:
  title: FairePlace Property Management Energy Diagnosis API
  description: 'Comprehensive API for managing properties, leases, tenants, and all aspects of real estate management.

    Built with Rust and Actix-web following hexagonal architecture principles.


    ## Authentication

    This API uses API keys for authentication with tenant-based isolation.


    ## Base URL

    - Production: `https://api.faireplace.com/api`'
  version: 1.0.0
  contact:
    name: FairePlace API Support
    email: api-support@faireplace.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.faireplace.com/api
  description: Production server
security:
- BearerAuth: []
tags:
- name: Energy Diagnosis
  description: Energy performance diagnostics (DPE)
paths:
  /energy-diagnoses:
    get:
      operationId: listEnergyPerformanceDiagnoses
      summary: List energy performance diagnoses
      description: 'Returns every DPE of the organisation as a **plain JSON array**: no

        pagination envelope, and no query filters on this route.


        To narrow the list, use the scoped routes:

        `GET /places/{place_id}/energy-diagnoses` or

        `GET /places/{place_id}/estates/{estate_id}/energy-diagnoses`.'
      tags:
      - Energy Diagnosis
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Energy performance diagnoses retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EnergyDiagnosis'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createEnergyPerformanceDiagnosis
      summary: Create an energy performance diagnosis
      description: Creates a new energy performance diagnosis. Must specify either estate_id or place_id, but not both
      tags:
      - Energy Diagnosis
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEnergyDiagnosis'
      responses:
        '201':
          description: Energy performance diagnosis created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnergyDiagnosis'
        '400':
          description: Invalid data (e.g., negative consumption, invalid construction year, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: Business validation error (e.g., estate_id and place_id both provided simultaneously)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /energy-diagnoses/{id}:
    get:
      operationId: getEnergyPerformanceDiagnosisID
      summary: Get energy performance diagnosis by ID
      description: Retrieves a specific energy performance diagnosis by its unique identifier
      tags:
      - Energy Diagnosis
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Energy performance diagnosis ID
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Energy performance diagnosis retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnergyDiagnosis'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      operationId: updateEnergyPerformanceDiagnosis
      summary: Update energy performance diagnosis
      description: Updates an existing energy performance diagnosis
      tags:
      - Energy Diagnosis
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Energy performance diagnosis ID
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEnergyDiagnosis'
      responses:
        '200':
          description: Energy performance diagnosis updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnergyDiagnosis'
        '400':
          description: Invalid data (e.g., negative consumption, invalid construction year, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Business validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: deleteEnergyPerformanceDiagnosis
      summary: Delete energy performance diagnosis
      description: Deletes an energy performance diagnosis
      tags:
      - Energy Diagnosis
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Energy performance diagnosis ID
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Energy performance diagnosis deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /places/{place_id}/energy-diagnoses:
    get:
      operationId: listEnergyPerformanceDiagnosesPlace
      summary: List energy performance diagnoses for a place
      description: Retrieves all energy performance diagnoses associated with a specific place
      tags:
      - Energy Diagnosis
      security:
      - BearerAuth: []
      parameters:
      - name: place_id
        in: path
        required: true
        description: Place ID
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Energy performance diagnoses for the place retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EnergyDiagnosis'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /places/{place_id}/estates/{estate_id}/energy-diagnoses:
    get:
      operationId: listEnergyPerformanceDiagnosesProperty
      summary: List energy performance diagnoses for a property
      description: Retrieves all energy performance diagnoses associated with a specific property
      tags:
      - Energy Diagnosis
      security:
      - BearerAuth: []
      parameters:
      - name: place_id
        in: path
        required: true
        description: Place ID
        schema:
          type: string
          format: uuid
      - name: estate_id
        in: path
        required: true
        description: Property ID
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Energy performance diagnoses for the property retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EnergyDiagnosis'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    UpdateEnergyDiagnosis:
      type: object
      description: 'Data for updating an existing DPE.


        **Update behavior for optional fields**:

        - **Field absent**: the existing value is preserved (no modification)

        - **Field present with `null`**: the value is removed (set to NULL in database)

        - **Field present with value**: the value is updated


        **Fields subject to this behavior**:

        - `energy_consumption`: can be set to `null` to remove the value

        - `ges_emission`: can be set to `null` to remove the value

        - `heated_area`: can be set to `null` to remove the value

        - `diagnostician_contact_id`: can be set to `null` to remove the value

        - `notes`: can be set to `null` to remove the value

        '
      properties:
        reference_number:
          type:
          - string
          - 'null'
          description: DPE reference number
          example: DPE-2024-002
          maxLength: 100
          minLength: 1
        diagnosis_date:
          type:
          - string
          - 'null'
          format: date
          description: Diagnosis date
          example: '2024-02-10'
        valid_until:
          type:
          - string
          - 'null'
          format: date
          description: Diagnosis validity date (10 years maximum)
          example: '2034-02-10'
        energy_label:
          type:
          - string
          - 'null'
          allOf:
          - $ref: '#/components/schemas/EnergyLabel'
        energy_consumption:
          type:
          - number
          - 'null'
          format: double
          description: 'Energy consumption in kWh/m²/year.


            **Update behavior**:

            - Field absent: the existing value is preserved

            - `null`: the value is removed (set to NULL in database)

            - Numeric value: the value is updated

            '
          example: 125.8
          minimum: 0
        ges_label:
          type:
          - string
          - 'null'
          allOf:
          - $ref: '#/components/schemas/GesLabel'
        ges_emission:
          type:
          - number
          - 'null'
          format: double
          description: 'GHG emission in kg CO2/m²/year.


            **Update behavior**:

            - Field absent: the existing value is preserved

            - `null`: the value is removed (set to NULL in database)

            - Numeric value: the value is updated

            '
          example: 28.7
          minimum: 0
        heated_area:
          type:
          - number
          - 'null'
          format: double
          description: 'Heated area in m².


            **Update behavior**:

            - Field absent: the existing value is preserved

            - `null`: the value is removed (set to NULL in database)

            - Numeric value: the value is updated

            '
          example: 65
          exclusiveMinimum: 0
        construction_year:
          type:
          - integer
          - 'null'
          description: Construction year of the property
          example: 2010
          minimum: 1800
          maximum: 2024
        diagnostician_contact_id:
          type:
          - string
          - 'null'
          format: uuid
          description: 'Diagnostician contact ID.


            **Update behavior**:

            - Field absent: the existing value is preserved

            - `null`: the value is removed (set to NULL in database)

            - Valid UUID: the value is updated

            '
          example: 550e8400-e29b-41d4-a716-446655440003
        notes:
          type:
          - string
          - 'null'
          description: 'Additional notes about the diagnosis.


            **Update behavior**:

            - Field absent: the existing value is preserved

            - `null`: the value is removed (set to NULL in database)

            - String value: the value is updated

            '
          example: Apartment with reinforced insulation
          maxLength: 1000
        media_id:
          type:
          - string
          - 'null'
          format: uuid
          description: 'Media ID of the uploaded DPE PDF document.


            **Update behavior**:

            - Field absent: the existing value is preserved

            - `null`: the value is removed (set to NULL in database)

            - Valid UUID: the value is updated

            '
          example: 550e8400-e29b-41d4-a716-446655440010
    CreateEnergyDiagnosis:
      type: object
      description: Data for creating a new DPE
      properties:
        estate_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Property (required if place_id is not provided) ID
          example: 550e8400-e29b-41d4-a716-446655440001
        place_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Place (required if estate_id is not provided) ID
          example: 550e8400-e29b-41d4-a716-446655440002
        reference_number:
          type: string
          description: DPE reference number
          example: DPE-2024-002
          maxLength: 100
          minLength: 1
        diagnosis_date:
          type: string
          format: date
          description: Diagnosis date
          example: '2024-02-10'
        valid_until:
          type: string
          format: date
          description: Diagnosis validity date (10 years maximum)
          example: '2034-02-10'
        energy_label:
          $ref: '#/components/schemas/EnergyLabel'
        energy_consumption:
          type:
          - number
          - 'null'
          format: double
          description: Energy consumption in kWh/m²/year
          example: 125.8
          minimum: 0
        ges_label:
          $ref: '#/components/schemas/GesLabel'
        ges_emission:
          type:
          - number
          - 'null'
          format: double
          description: GHG emission in kg CO2/m²/year
          example: 28.7
          minimum: 0
        heated_area:
          type:
          - number
          - 'null'
          format: double
          description: Heated area in m²
          example: 65
          exclusiveMinimum: 0
        construction_year:
          type: integer
          description: Construction year of the property
          example: 2010
          minimum: 1800
          maximum: 2024
        diagnostician_contact_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Diagnostician contact ID
          example: 550e8400-e29b-41d4-a716-446655440003
        notes:
          type:
          - string
          - 'null'
          description: Internal notes about the diagnosis
          example: Apartment with reinforced insulation
          maxLength: 1000
        media_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Media ID of the uploaded DPE PDF document
          example: 550e8400-e29b-41d4-a716-446655440010
    GesLabel:
      type: string
      description: DPE GHG (Greenhouse Gas) label (A to G)
      enum:
      - A
      - B
      - C
      - D
      - E
      - F
      - G
      example: B
    Error:
      type: object
      description: "The error envelope returned by every authenticated endpoint.\n\nTwo things are worth knowing before you write your error handling:\n\n- **`code` is a symbolic string, not a number.** The numeric HTTP status is\n  in `status`. Branch on `code`: it is stable, and show `message`, which\n  is written for humans and may be reworded without notice.\n- The public guest-signature endpoints use a **different, flatter shape**\n  (`{ \"error_code\": …, \"message\": … }`, no `error` wrapper), because they\n  are consumed by a page that has no session. Their responses document it\n  inline.\n\nThe `X-Request-Id` response header carries the request identifier: quote it\nwhen reporting a problem. It is a header, not a body field.\n"
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - status
          properties:
            code:
              type: string
              description: Stable symbolic code. Branch on this.
              enum:
              - NOT_FOUND
              - UNAUTHORIZED
              - VALIDATION_ERROR
              - DATABASE_ERROR
              - BUSINESS_ERROR
              - STORAGE_ERROR
              - CONFIG_ERROR
              - FORBIDDEN
              - CONFLICT
              - PARSE_ERROR
              - SERIALIZATION_ERROR
              - AUTHENTICATION_ERROR
              - AUTHORIZATION_ERROR
              - EXTERNAL_SERVICE_ERROR
              - RATE_LIMIT_EXCEEDED
              - PAYMENT_REQUIRED
              - PLAN_LIMIT_REACHED
              - GONE
              - BAD_REQUEST
              - INTERNAL_ERROR
              - INTERNAL_SERVER_ERROR
              example: NOT_FOUND
            message:
              type: string
              description: 'Human-readable explanation, most often in French. Safe to display,

                not safe to parse.

                '
              example: Lease not found
            status:
              type: integer
              description: The HTTP status code, repeated in the body.
              example: 404
            details:
              type: object
              additionalProperties: true
              description: 'Extra machine-readable context. Only present on some errors: on

                `RATE_LIMIT_EXCEEDED` it carries `retry_after_seconds`.

                '
              example:
                retry_after_seconds: 12
    EnergyDiagnosis:
      type: object
      description: Complete Energy Performance Diagnosis (DPE)
      properties:
        id:
          type:
          - string
          - 'null'
          format: uuid
          description: Unique identifier of the DPE
          example: 550e8400-e29b-41d4-a716-446655440000
        estate_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Property (if DPE for a specific property) ID
          example: 550e8400-e29b-41d4-a716-446655440001
        place_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Place (if DPE for a specific place) ID
          example: 550e8400-e29b-41d4-a716-446655440002
        reference_number:
          type:
          - string
          - 'null'
          description: DPE reference number
          example: DPE-2024-002
          maxLength: 100
        diagnosis_date:
          type:
          - string
          - 'null'
          format: date
          description: Diagnosis date
          example: '2024-02-10'
        valid_until:
          type:
          - string
          - 'null'
          format: date
          description: Diagnosis validity date (10 years maximum)
          example: '2034-02-10'
        energy_label:
          type:
          - string
          - 'null'
          allOf:
          - $ref: '#/components/schemas/EnergyLabel'
        energy_consumption:
          type:
          - number
          - 'null'
          format: double
          description: Energy consumption in kWh/m²/year
          example: 125.8
          minimum: 0
        ges_label:
          type:
          - string
          - 'null'
          allOf:
          - $ref: '#/components/schemas/GesLabel'
        ges_emission:
          type:
          - number
          - 'null'
          format: double
          description: GHG emission in kg CO2/m²/year
          example: 28.7
          minimum: 0
        heated_area:
          type:
          - number
          - 'null'
          format: double
          description: Heated area in m²
          example: 65
          exclusiveMinimum: 0
        construction_year:
          type:
          - integer
          - 'null'
          description: Construction year of the property
          example: 2010
          minimum: 1800
          maximum: 2024
        diagnostician_contact_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Diagnostician contact ID
          example: 550e8400-e29b-41d4-a716-446655440003
        notes:
          type:
          - string
          - 'null'
          description: Internal notes about the diagnosis
          example: Apartment with reinforced insulation
          maxLength: 1000
        media_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Media ID of the uploaded DPE PDF document
          example: 550e8400-e29b-41d4-a716-446655440010
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Creation date
          example: '2024-01-15T10:30:00Z'
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Last modification date
          example: '2024-01-15T10:30:00Z'
      required:
      - id
      - reference_number
      - diagnosis_date
      - valid_until
      - energy_label
      - ges_label
      - construction_year
      - created_at
      - updated_at
    EnergyLabel:
      type: string
      description: DPE energy label (A to G)
      enum:
      - A
      - B
      - C
      - D
      - E
      - F
      - G
      example: B
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key with fp_* prefix, passed as Bearer token
    WorkerApiKey:
      type: apiKey
      in: header
      name: X-API-Key
    WorkerBearer:
      type: http
      scheme: bearer
      bearerFormat: Worker