FairePlace Syndic Fund Calls API

openapi: 3.2.0
info:
  title: FairePlace Property Management Syndic Fund Calls 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: Syndic Fund Calls
  description: Fund calls (appels de fonds) issued by a syndic.
paths:
  /syndics/{syndic_id}/fund-calls:
    get:
      operationId: listFundCalls
      summary: List fund calls for a syndic
      description: Returns all fund calls for a syndic, optionally filtered by year.
      tags:
      - Syndic Fund Calls
      security:
      - BearerAuth: []
      parameters:
      - name: syndic_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: year
        in: query
        required: false
        schema:
          type: integer
        description: Filter by fiscal year
      responses:
        '200':
          description: List of fund calls
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FundCallResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createFundCall
      summary: Create a fund call with lines
      description: 'Creates a new fund call for a syndic with its line items in a single request.


        **Validation rules:**

        - `quarter` must be between 1 and 4

        - `due_date` must be after `call_date`

        - `total_amount` must be > 0

        - Each line must have a non-empty `category` and `amount` > 0'
      tags:
      - Syndic Fund Calls
      security:
      - BearerAuth: []
      parameters:
      - name: syndic_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFundCallDto'
      responses:
        '201':
          description: Fund call created with lines
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundCallWithLinesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /syndics/{syndic_id}/fund-calls/{call_id}:
    get:
      operationId: getFundCall
      summary: Get a fund call with its lines
      tags:
      - Syndic Fund Calls
      security:
      - BearerAuth: []
      parameters:
      - name: syndic_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Fund call with lines
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundCallWithLinesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteFundCall
      summary: Delete a fund call
      description: Deletes the fund call and all associated lines and allocations.
      tags:
      - Syndic Fund Calls
      security:
      - BearerAuth: []
      parameters:
      - name: syndic_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Fund call deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /syndics/{syndic_id}/fund-calls/{call_id}/payment:
    post:
      operationId: recordFundCallPayment
      summary: Record a payment for a fund call
      description: 'Records a payment against a fund call. The status is automatically computed:

        - `Paid` if `paid_amount >= total_amount`

        - `PartiallyPaid` if `paid_amount > 0`

        - `Pending` otherwise'
      tags:
      - Syndic Fund Calls
      security:
      - BearerAuth: []
      parameters:
      - name: syndic_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordPaymentDto'
      responses:
        '200':
          description: Payment recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundCallResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    FundCallWithLinesResponse:
      type: object
      description: Fund call with its line items (flattened)
      allOf:
      - $ref: '#/components/schemas/FundCallResponse'
      - type: object
        properties:
          lines:
            type: array
            items:
              $ref: '#/components/schemas/FundCallLineResponse'
    CreateFundCallLineDto:
      type: object
      description: Line item for a new fund call
      required:
      - category
      - amount
      - is_recoverable
      properties:
        category:
          type: string
          description: Charge category name (must not be empty)
        charge_category_id:
          type:
          - string
          - 'null'
          format: uuid
        amount:
          type: number
          format: decimal
          description: Must be > 0
          exclusiveMinimum: 0
        is_recoverable:
          type: boolean
        notes:
          type:
          - string
          - 'null'
    FundCallResponse:
      type: object
      description: Syndic fund call response
      required:
      - id
      - syndic_id
      - year
      - quarter
      - call_date
      - due_date
      - total_amount
      - paid_amount
      - status
      - created_at
      - updated_at
      properties:
        id:
          type: string
          format: uuid
        syndic_id:
          type: string
          format: uuid
        year:
          type: integer
          description: Fiscal year
        quarter:
          type: integer
          description: Quarter (1-4)
          minimum: 1
          maximum: 4
        call_date:
          type: string
          format: date
          description: Date the fund call was issued
        due_date:
          type: string
          format: date
          description: Payment due date
        total_amount:
          type: number
          format: decimal
          description: Total amount of the fund call
        paid_amount:
          type: number
          format: decimal
          description: Amount already paid
        payment_date:
          type:
          - string
          - 'null'
          format: date
          description: Date of last payment
        status:
          type: string
          description: Computed status based on payment state
        document_url:
          type:
          - string
          - 'null'
          description: URL to the fund call document
        notes:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateFundCallDto:
      type: object
      description: Data for creating a fund call with its lines
      required:
      - year
      - quarter
      - call_date
      - due_date
      - total_amount
      - lines
      properties:
        year:
          type: integer
          description: Fiscal year
        quarter:
          type: integer
          description: Quarter (1-4)
          minimum: 1
          maximum: 4
        call_date:
          type: string
          format: date
        due_date:
          type: string
          format: date
        total_amount:
          type: number
          format: decimal
          description: Must be > 0
          exclusiveMinimum: 0
        document_url:
          type:
          - string
          - 'null'
        notes:
          type:
          - string
          - 'null'
        lines:
          type: array
          items:
            $ref: '#/components/schemas/CreateFundCallLineDto'
          minItems: 1
    FundCallLineResponse:
      type: object
      description: Line item within a fund call
      required:
      - id
      - fund_call_id
      - category
      - amount
      - is_recoverable
      - created_at
      properties:
        id:
          type: string
          format: uuid
        fund_call_id:
          type: string
          format: uuid
        category:
          type: string
          description: Charge category name
        charge_category_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Link to a charge category
        amount:
          type: number
          format: decimal
        is_recoverable:
          type: boolean
          description: Whether this line is recoverable from tenants
        notes:
          type:
          - string
          - 'null'
        created_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
    RecordPaymentDto:
      type: object
      description: Record a payment against a fund call
      required:
      - paid_amount
      - payment_date
      properties:
        paid_amount:
          type: number
          format: decimal
        payment_date:
          type: string
          format: date
  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