FairePlace Security Deposits API

openapi: 3.2.0
info:
  title: FairePlace Property Management Security Deposits 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: Security Deposits
  description: 'Security deposit (dépôt de garantie) management.


    Per Art. 22 of Loi 89-462:

    - Restitution within 1 month (conformity) or 2 months (non-conformity) after lease end

    - Maximum 20% retention for co-ownership charge provisions

    - Late penalty: 10% of monthly rent (HC) per month of delay

    - One deposit per lease (unique constraint)'
paths:
  /leases/{lease_id}/deposit:
    post:
      operationId: recordSecurityDeposit
      summary: Record a security deposit
      description: 'Record the collection of a security deposit for a lease.


        Only one deposit is allowed per lease. If a deposit already exists, returns a business error.


        The deposit amount should match the `deposit_amount` field on the lease, which is validated

        against French legal limits per lease type:

        - Residential empty: max 1 month rent

        - Furnished/student: max 2 months rent

        - Commercial: max 3 months rent

        - Mobility lease: deposit forbidden (Art. 25-13 ALUR)


        **Permissions required:** `leases:write`'
      tags:
      - Security Deposits
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        description: Lease ID
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordDeposit'
      responses:
        '201':
          description: Deposit recorded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityDeposit'
        '400':
          description: 'Validation error. Examples:

            - "Le montant du dépôt de garantie doit être positif"

            '
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: 'Business error. Examples:

            - "Un dépôt de garantie existe déjà pour ce bail"

            '
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      operationId: getSecurityDepositDetails
      summary: Get security deposit details
      description: 'Retrieve the security deposit details for a lease.


        Returns the full deposit information including status, amounts retained,

        restitution dates, and any late penalties.


        **Permissions required:** `leases:read`'
      tags:
      - Security Deposits
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        description: Lease ID
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Security deposit details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityDeposit'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No security deposit found for this lease
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: deleteSecurityDeposit
      summary: Delete a security deposit
      description: 'Delete the security deposit record for a lease.


        **Permissions required:** `leases:delete`'
      tags:
      - Security Deposits
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        description: Lease ID
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Deposit deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /leases/{lease_id}/deposit/return:
    post:
      operationId: returnSecurityDeposit
      summary: Return a security deposit
      description: 'Record the return (restitution) of a security deposit.


        **Art. 22 Loi 89-462** compliance:


        **Restitution deadline:**

        - Exit inspection conformity → **1 month** after lease end

        - Exit inspection non-conformity → **2 months** after lease end


        **Retention limits:**

        - Charge provisions (co-ownership): max **20%** of deposit amount

        - Damages and unpaid rent: justified amounts, total cannot exceed deposit


        **Late penalty:**

        - If `restitution_date` exceeds the calculated deadline, a penalty of

        **10% of monthly rent (HC) per full month of delay** is automatically computed.


        The system calculates:

        - `restitution_due_date` from `lease_end_date` + conformity status

        - `amount_returned` = deposit - (charges + damages + unpaid rent)

        - `penalty_amount` if return is late

        - `status`: `FULLY_RETURNED` or `PARTIALLY_RETURNED` (if only charges retained for co-ownership)


        **Permissions required:** `leases:write`'
      tags:
      - Security Deposits
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        description: Lease ID
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnDeposit'
      responses:
        '200':
          description: Deposit return recorded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityDeposit'
        '400':
          description: 'Validation error. Examples:

            - "Les montants de retenue ne peuvent pas être négatifs"

            '
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No security deposit found for this lease
          $ref: '#/components/responses/NotFound'
        '422':
          description: 'Business error. Examples:

            - "Ce dépôt de garantie a déjà été intégralement restitué"

            - "La retenue pour charges (250.00 €) ne peut excéder 20% du dépôt (200.00 €)"

            - "Le total des retenues (1100.00 €) ne peut excéder le montant du dépôt (1000.00 €)"

            '
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Unprocessable Entity
      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'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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
    ReturnDeposit:
      type: object
      description: 'Request to record the return of a security deposit.


        The system automatically:

        - Calculates the restitution deadline (1 or 2 months based on exit inspection)

        - Validates that charge retention does not exceed 20% (Art. 22)

        - Validates that total retentions do not exceed the deposit amount

        - Computes the late return penalty if applicable (10% of monthly rent per month)

        '
      properties:
        exit_inspection_conformity:
          type: boolean
          description: true = conformity (1-month deadline), false = non-conformity (2-month deadline)
          example: true
        lease_end_date:
          type: string
          format: date
          description: End date of the lease (used to calculate restitution deadline)
          example: '2026-03-31'
        restitution_date:
          type: string
          format: date
          description: Actual date of deposit return
          example: '2026-04-15'
        retained_for_charges:
          type:
          - number
          - 'null'
          format: decimal
          description: Amount retained for co-ownership charges (max 20% of deposit)
          example: 150
        retained_for_damages:
          type:
          - number
          - 'null'
          format: decimal
          description: Amount retained for property damages
          example: 0
        retained_for_unpaid_rent:
          type:
          - number
          - 'null'
          format: decimal
          description: Amount retained for unpaid rent
          example: 0
        copro_accounts_approval_date:
          type:
          - string
          - 'null'
          format: date
          description: Date of syndic account approval (if retaining for charges)
        notes:
          type:
          - string
          - 'null'
          description: Additional notes about the return
      required:
      - exit_inspection_conformity
      - lease_end_date
      - restitution_date
    RecordDeposit:
      type: object
      description: Request to record a security deposit collection
      properties:
        amount:
          type: number
          format: decimal
          description: Deposit amount
          example: 750
        paid_date:
          type:
          - string
          - 'null'
          format: date
          description: Date the deposit was collected
          example: '2026-01-15'
      required:
      - amount
    SecurityDeposit:
      type: object
      description: 'A security deposit (dépôt de garantie) attached to a lease.


        Per Art. 22 of Loi 89-462:

        - Restitution within 1 month (conformity exit inspection) or 2 months (non-conformity)

        - Maximum retention of 20% for co-ownership charge provisions

        - Penalty: 10% of monthly rent (HC) per month of delay

        '
      properties:
        id:
          type: string
          format: uuid
        lease_id:
          type: string
          format: uuid
        amount:
          type: number
          format: decimal
          description: Deposit amount collected
          example: 750
        paid_date:
          type:
          - string
          - 'null'
          format: date
          description: Date the deposit was collected
          example: '2026-01-15'
        status:
          type: string
          description: Current status (COLLECTED, PENDING_RETURN, PARTIALLY_RETURNED, FULLY_RETURNED, DISPUTED)
          example: COLLECTED
        restitution_due_date:
          type:
          - string
          - 'null'
          format: date
          description: Deadline for restitution (1 or 2 months after lease end)
        restitution_date:
          type:
          - string
          - 'null'
          format: date
          description: Actual date the deposit was returned
        amount_returned:
          type:
          - number
          - 'null'
          format: decimal
          description: Amount returned to the tenant
        retained_for_charges:
          type:
          - number
          - 'null'
          format: decimal
          description: Amount retained for co-ownership charge provisions (max 20% per Art. 22)
        retained_for_damages:
          type:
          - number
          - 'null'
          format: decimal
          description: Amount retained for property damages
        retained_for_unpaid_rent:
          type:
          - number
          - 'null'
          format: decimal
          description: Amount retained for unpaid rent
        penalty_amount:
          type:
          - number
          - 'null'
          format: decimal
          description: Late return penalty (10% of monthly rent HC per month of delay)
        exit_inspection_conformity:
          type: boolean
          description: Whether the exit inspection was conformity-compliant (affects restitution deadline)
          example: true
        copro_accounts_approval_date:
          type:
          - string
          - 'null'
          format: date
          description: Date of syndic account approval (triggers release of retained charges)
        notes:
          type:
          - string
          - 'null'
          description: Additional notes
      required:
      - id
      - lease_id
      - amount
      - status
      - exit_inspection_conformity
  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