FairePlace Rent Payments API

openapi: 3.2.0
info:
  title: FairePlace Property Management Rent Payments 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: Rent Payments
  description: Recording and reading the rent payments of a lease.
paths:
  /leases/{lease_id}/rent-payments:
    post:
      operationId: recordRentPayment
      summary: Record a rent payment
      description: 'Record a rent payment for a lease period.


        The payment status is **auto-computed** based on amounts and dates:

        - `PAID` if `paid_amount >= expected_amount`

        - `PARTIALLY_PAID` if `paid_amount > 0` but less than expected

        - `LATE` if no payment and `period_end` has passed

        - `PENDING` if no payment but period not yet ended


        **Permissions required:** `leases:write`'
      tags:
      - Rent Payments
      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:
              type: object
              required:
              - period_start
              - period_end
              - expected_amount
              - paid_amount
              properties:
                period_start:
                  type: string
                  format: date
                  description: Start of the rent period
                  example: '2025-01-01'
                period_end:
                  type: string
                  format: date
                  description: End of the rent period
                  example: '2025-01-31'
                expected_amount:
                  type: number
                  format: decimal
                  description: Expected rent amount (rent + charges)
                  example: 900
                paid_amount:
                  type: number
                  format: decimal
                  description: Amount actually paid
                  example: 900
                payment_date:
                  type:
                  - string
                  - 'null'
                  format: date
                  description: Date of payment
                  example: '2025-01-05'
                payment_method:
                  type:
                  - string
                  - 'null'
                  enum:
                  - VIREMENT_BANCAIRE
                  - PRELEVEMENT_AUTOMATIQUE
                  - CHEQUE
                  - ESPECES
                  - CARTE_BANCAIRE
                  - MANDAT_CASH
                  - AUTRE
                  - null
                  description: Payment method
                reference:
                  type:
                  - string
                  - 'null'
                  description: Payment reference (transfer number, check number)
                notes:
                  type:
                  - string
                  - 'null'
                  description: Optional notes
      responses:
        '201':
          description: Payment recorded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RentPaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Lease not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: listRentPayments
      summary: List rent payments
      description: 'List all rent payments for a lease, with optional filters by status and period.


        **Permissions required:** `leases:read`'
      tags:
      - Rent Payments
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - PENDING
          - PAID
          - PARTIALLY_PAID
          - LATE
          - UNPAID
          - IN_DISPUTE
      - name: period_start
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter payments with period_start >= this date
      - name: period_end
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter payments with period_end <= this date
      responses:
        '200':
          description: List of rent payments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RentPaymentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /leases/{lease_id}/rent-payments/balance:
    get:
      operationId: getTenantBalance
      summary: Get tenant balance
      description: 'Returns the aggregated balance for a lease: total expected, total paid, arrears, overpayment, and count of unpaid periods.


        **Permissions required:** `leases:read`'
      tags:
      - Rent Payments
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Lease balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaseBalanceResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /leases/{lease_id}/rent-payments/generate-schedule:
    post:
      operationId: generatePaymentSchedule
      summary: Generate payment schedule
      description: 'Generates expected payment entries for a date range based on the lease parameters (rent amount, frequency).

        Skips periods where a payment already exists.


        **Permissions required:** `leases:write`'
      tags:
      - Rent Payments
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - range_start
              - range_end
              properties:
                range_start:
                  type: string
                  format: date
                  example: '2025-01-01'
                range_end:
                  type: string
                  format: date
                  example: '2025-12-31'
      responses:
        '201':
          description: Payment schedule entries created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RentPaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Lease not found
  /leases/{lease_id}/rent-payments/{payment_id}:
    get:
      operationId: getRentPayment
      summary: Get a rent payment
      description: 'Retrieve a specific rent payment by ID.


        **Permissions required:** `leases:read`'
      tags:
      - Rent Payments
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: payment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RentPaymentResponse'
        '404':
          description: Payment not found
    put:
      operationId: updateRentPayment
      summary: Update a rent payment
      description: 'Update a rent payment. Status is auto-recalculated unless manually overridden.


        **Permissions required:** `leases:write`'
      tags:
      - Rent Payments
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: payment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paid_amount:
                  type: number
                  format: decimal
                payment_date:
                  type: string
                  format: date
                payment_method:
                  type: string
                  enum:
                  - VIREMENT_BANCAIRE
                  - PRELEVEMENT_AUTOMATIQUE
                  - CHEQUE
                  - ESPECES
                  - CARTE_BANCAIRE
                  - MANDAT_CASH
                  - AUTRE
                reference:
                  type: string
                status:
                  type: string
                  enum:
                  - PENDING
                  - PAID
                  - PARTIALLY_PAID
                  - LATE
                  - UNPAID
                  - IN_DISPUTE
                  description: Manually override status (otherwise auto-computed)
                receipt_id:
                  type: string
                  format: uuid
                notes:
                  type: string
      responses:
        '200':
          description: Payment updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RentPaymentResponse'
        '404':
          description: Payment not found
    delete:
      operationId: deleteRentPayment
      summary: Delete a rent payment
      description: 'Delete a rent payment.


        **Permissions required:** `leases:delete`'
      tags:
      - Rent Payments
      security:
      - BearerAuth: []
      parameters:
      - name: lease_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: payment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Payment deleted
        '404':
          description: Payment not found
components:
  responses:
    Forbidden:
      description: Forbidden
      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:
    LeaseBalanceResponse:
      type: object
      properties:
        lease_id:
          type: string
          format: uuid
        total_expected:
          type: number
          format: decimal
          description: Total expected rent across all periods
        total_paid:
          type: number
          format: decimal
          description: Total amount paid
        arrears:
          type: number
          format: decimal
          description: Amount owed (total_expected - total_paid, min 0)
        overpayment:
          type: number
          format: decimal
          description: Overpayment amount (total_paid - total_expected, min 0)
        unpaid_periods:
          type: integer
          description: Count of periods with LATE or UNPAID status
    RentPaymentResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        lease_id:
          type: string
          format: uuid
        period_start:
          type: string
          format: date
        period_end:
          type: string
          format: date
        expected_amount:
          type: number
          format: decimal
        paid_amount:
          type: number
          format: decimal
        payment_date:
          type:
          - string
          - 'null'
          format: date
        payment_method:
          type:
          - string
          - 'null'
        reference:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - PENDING
          - PAID
          - PARTIALLY_PAID
          - LATE
          - UNPAID
          - IN_DISPUTE
        receipt_id:
          type:
          - string
          - 'null'
          format: uuid
        notes:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    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
  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