FairePlace Amendment Validations API

openapi: 3.2.0
info:
  title: FairePlace Property Management Amendment Validations 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: Amendment Validations
  description: Validation steps an amendment must clear before it takes effect.
paths:
  /leases/{lease_id}/amendments/{amendment_id}/validations:
    post:
      operationId: createAmendmentValidation
      summary: Create a validation entry
      description: 'Add a validation requirement to an amendment. Each validator role can only appear once per amendment.


        **Auto-created validations:** For `TENANT_MODIFICATION`, `GUARANTOR_MODIFICATION`, and `EARLY_TERMINATION` amendments,

        a mandatory `OWNER` validation is automatically created at amendment creation (Art. 12 & 15 Loi 89-462).'
      tags:
      - Amendment Validations
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: amendment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAmendmentValidationDto'
      responses:
        '201':
          description: Validation entry created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmendmentValidationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: A validation entry for this role already exists on this amendment
    get:
      operationId: listAmendmentValidations
      summary: List all validations for an amendment
      description: Returns all validation entries for a specific amendment, ordered by `validation_order`.
      tags:
      - Amendment Validations
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: amendment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: List of validation entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AmendmentValidationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /leases/{lease_id}/amendments/{amendment_id}/validations/status:
    get:
      operationId: computeAmendmentValidationStatus
      summary: Compute aggregate validation status
      description: 'Computes the aggregate validation status from all mandatory validation entries:

        - `FULLY_VALIDATED`: All mandatory validators approved (or no mandatory validators exist)

        - `REJECTED`: At least one mandatory validator rejected

        - `PENDING`: Some mandatory validations still pending


        **Important:** The amendment cannot be activated (`Signed → Active`) unless the aggregate status is `FULLY_VALIDATED`.'
      tags:
      - Amendment Validations
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: amendment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Computed validation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /leases/{lease_id}/amendments/{amendment_id}/validations/{validation_id}:
    get:
      operationId: getAmendmentValidation
      summary: Get a specific validation entry
      tags:
      - Amendment Validations
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: amendment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: validation_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Validation entry details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmendmentValidationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateAmendmentValidation
      summary: Update a validation entry (approve/reject)
      description: 'Update the status of a validation entry. Typically used to approve or reject.

        Set `status` to `APPROVED` or `REJECTED`, and provide `validated_by` with the user ID.'
      tags:
      - Amendment Validations
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: amendment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: validation_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAmendmentValidationDto'
      responses:
        '200':
          description: Validation entry updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmendmentValidationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteAmendmentValidation
      summary: Delete a validation entry
      tags:
      - Amendment Validations
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: amendment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: validation_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Validation entry deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    UpdateAmendmentValidationDto:
      type: object
      description: Data for updating a validation entry (approve/reject)
      properties:
        status:
          type: string
          description: New validation status
          enum:
          - PENDING
          - APPROVED
          - REJECTED
        validated_by:
          type:
          - string
          - 'null'
          format: uuid
          description: ID of the user performing the validation
        validation_date:
          type:
          - string
          - 'null'
          format: date-time
          description: Validation date (defaults to now)
        comments:
          type:
          - string
          - 'null'
          description: Validator comments
          maxLength: 1000
    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
    AmendmentValidationResponse:
      type: object
      description: 'Amendment validation entry: tracks approval by a specific role'
      required:
      - id
      - amendment_id
      - validator_role
      - validation_order
      - is_mandatory
      - status
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the validation entry
        amendment_id:
          type: string
          format: uuid
          description: Associated amendment ID
        validator_role:
          type: string
          description: Role of the validator
          enum:
          - LEGAL
          - FINANCIAL
          - PROPERTY_MANAGER
          - OWNER
          - TENANT
          example: OWNER
        validation_order:
          type: integer
          description: Order in the validation workflow (1 = first)
          example: 1
        is_mandatory:
          type: boolean
          description: Whether this validation is required for amendment activation
          example: true
        status:
          type: string
          description: Current validation status
          enum:
          - PENDING
          - APPROVED
          - REJECTED
          example: PENDING
        validation_date:
          type:
          - string
          - 'null'
          format: date-time
          description: When the validation was performed
        validated_by:
          type:
          - string
          - 'null'
          format: uuid
          description: ID of the user who validated
        comments:
          type:
          - string
          - 'null'
          description: Validator comments
          maxLength: 1000
    CreateAmendmentValidationDto:
      type: object
      description: Data for creating a new validation entry
      required:
      - validator_role
      - validation_order
      properties:
        validator_role:
          type: string
          description: Role of the validator
          enum:
          - LEGAL
          - FINANCIAL
          - PROPERTY_MANAGER
          - OWNER
          - TENANT
        validation_order:
          type: integer
          description: Order in the validation workflow
          example: 1
        is_mandatory:
          type:
          - boolean
          - 'null'
          description: Whether this validation is required (defaults to true)
        comments:
          type:
          - string
          - 'null'
          description: Initial comments
          maxLength: 1000
    ValidationStatusResponse:
      type: object
      description: Computed aggregate validation status for an amendment
      required:
      - status
      properties:
        status:
          type: string
          description: 'Computed from all mandatory validations:

            - `FULLY_VALIDATED`: All mandatory validators approved (or no mandatory validators)

            - `REJECTED`: At least one mandatory validator rejected

            - `PENDING`: Some mandatory validations still pending

            '
          enum:
          - FULLY_VALIDATED
          - REJECTED
          - PENDING
          example: PENDING
  responses:
    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'
  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