openapi: 3.1.0

info:
  title: CEERM API
  version: "4.13"
  description: >
    The external API of the CEERM tool.
    For more information contact: abderrahmane.elasri@a-gile.com

servers:
  - url: https://www.caerm-api.a-gile.site/index.php
    description: CEERM API Server
  - url: https://www.ceerm-sso.a-gile.fr
    description: SSO Authentication Server

components:

  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:

    ApiError:
      type: object
      description: Standard API error format returned by the CEERM API.
      properties:
        error:
          type: string
          description: Generic safe error message (no technical details are exposed).
        code:
          type: integer
          description: HTTP status code associated with the error.
      required:
        - error
        - code
      examples:
        notFound:
          summary: Resource not found
          value:
            error: "Resource not found."
            code: 404
        invalid:
          summary: Bad request
          value:
            error: "Invalid request."
            code: 400
        forbidden:
          summary: Forbidden
          value:
            error: "Access denied."
            code: 403
        conflict:
          summary: Conflict
          value:
            error: "Conflict error."
            code: 409
        validation:
          summary: Validation error
          value:
            error: "Validation failed."
            code: 422
        gateway:
          summary: External error
          value:
            error: "External service error."
            code: 502
        internal:
          summary: Internal server error
          value:
            error: "Internal server error."
            code: 500

    ######################################################################
    # BULK EDIT SCHEMAS
    ######################################################################

    BulkEditRequest:
      type: object
      description: Payload for bulk updating multiple entities.
      required:
        - ids
        - field
        - value
      properties:
        ids:
          type: array
          description: List of IDs to update (maximum 30 items)
          maxItems: 30
          items:
            type: integer
        field:
          type: string
          description: Field to update (allowed fields depend on the target entity)
        value:
          description: New value to assign
      example:
        ids: [12, 15, 18]
        field: "status"
        value: "4 - Terminar obra"

    BulkEditResponse:
      type: object
      description: Returned after applying bulk updates.
      properties:
        updated:
          type: array
          description: List of updated entities. Each item may contain one or several updated fields.
          items:
            type: object
            additionalProperties: true
      example:
        updated:
          - id: 12
            status: "4 - Terminar obra"
            "...": "... additional entity fields ..."
          - id: 15
            status: "4 - Terminar obra"
            "...": "... additional entity fields ..."
          - id: 18
            status: "4 - Terminar obra"
            "...": "... additional entity fields ..."

paths:

  ######################################################################
  # AUTHENTICATION ENDPOINT (SSO Token Exchange)
  ######################################################################

  /realms/Enership/protocol/openid-connect/token:
    post:
      tags:
        - Authentication
      summary: Obtain a token from CEERM SSO
      description: >
        Use the external SSO to obtain an access token using client credentials.

      externalDocs:
        description: SSO Token Endpoint
        url: https://www.ceerm-sso.a-gile.fr/realms/Enership/protocol/openid-connect/token

      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - client_id
                - client_secret
              properties:
                grant_type:
                  type: string
                  example: client_credentials
                client_id:
                  type: string
                  example: ceerm-external-api
                client_secret:
                  type: string
                  example: your_client_secret_here

      responses:
        "200":
          description: Token successfully obtained
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token: { type: string }
                  token_type: { type: string }
                  expires_in: { type: integer }
                  scope: { type: string }

  ######################################################################
  # GLOBAL SEARCH ENDPOINT
  ######################################################################

  /api/search:
    get:
      tags:
        - Search
      summary: Global search across application entities
      description: |
        Performs a keyword search across all entities marked with `#[Searchable]`.
        Returns grouped results by entity type.

      security:
        - Bearer: []

      parameters:
        - name: keyword
          in: query
          required: true
          schema:
            type: string
            minLength: 2
          example: test

      responses:

        "200":
          description: Successful search
          content:
            application/json:
              schema:
                type: object
                properties:
                  keyword: { type: string }
                  results:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: object

        "400":
          description: Invalid keyword
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: "Invalid request."
                code: 400

        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: "Access denied."
                code: 403

        "409":
          description: Business logic conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: "Conflict error."
                code: 409

        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: "Internal server error."
                code: 500

  ######################################################################
  # BULK EDIT
  ######################################################################

  /api/{entity}/bulk-edit:
    patch:
      tags:
        - Bulk Edit
      summary: Bulk update fields of multiple entities
      description: |
        Allows bulk editing of up to **30 items** at once.
        Only allowed fields can be updated depending on the entity type.

      security:
        - Bearer: []

      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
            enum:
              - project
              - potential
              - quotation
              - operation
              - payment
              - service
              - contract
              - business-referral
              - contract-segment
              - account
              - prospect

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkEditRequest"

      responses:

        "200":
          description: Bulk edit applied successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkEditResponse"

        "400":
          description: Invalid payload (invalid field, too many items…)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: "Invalid request."
                code: 400

        "403":
          description: Access denied
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: "Access denied."
                code: 403

        "409":
          description: Conflict (invalid field, business constraint)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: "Conflict error."
                code: 409

        "500":
          description: Unexpected internal error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: "Internal server error."
                code: 500
