openapi: 3.0.0
info:
  title: WorkGroupSupplier
  version: 2.0.0
  description: >
    A **WorkGroupSupplier** represents the assignment of a supplier to a work
    group.

    Links a Unit (supplier) to a WorkGroup.


    Use this API to:

    - Assign suppliers to a job role, work phase, or homogeneous group

    - Find all suppliers in a work group (filter by `work_group_id`)

    - Find all work groups a supplier belongs to (filter by `unit_id`)


    Supports historicization.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/work-group-supplier/index:
    post:
      summary: index
      operationId: indexWorkGroupSupplier
      tags:
        - WorkGroupSuppliers
      description: |
        Returns a paginated list of supplier-work group assignments.

        Most useful filters:
        - `work_group_id`: all suppliers in a specific work group
        - `unit_id`: all work groups a supplier belongs to
      requestBody:
        description: Parameters for searching
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkGroupSupplierIndexParams"
            example:
              filter:
                work_group_id: 3a4b5c6d-7e8f-9012-abcd-ef3456789012
              per-page: 20
              page: 1
              sort: name
      responses:
        "200":
          description: List of supplier-work group assignments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewWorkGroupSupplier"
          headers:
            X-Pagination-Current-Page:
              schema:
                type: integer
              description: Current page
            X-Pagination-Page-Count:
              schema:
                type: integer
              description: Total number of pages
            X-Pagination-Per-Page:
              schema:
                type: integer
              description: Number of items per page
            X-Pagination-Total-Count:
              schema:
                type: integer
              description: Total number of items
  /v2/work-group-supplier/create:
    post:
      summary: create
      operationId: createWorkGroupSupplier
      tags:
        - WorkGroupSuppliers
      description: |
        Assigns a supplier to a work group.

        Requires `work_group_id` and `unit_id`.
        The `work_group_supplier_id` is auto-generated if not provided.
      requestBody:
        description: Assignment to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkGroupSupplier"
      responses:
        "201":
          description: Supplier assigned to work group successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkGroupSupplier"
  /v2/work-group-supplier/view/{id}:
    get:
      summary: view
      operationId: viewWorkGroupSupplier
      tags:
        - WorkGroupSuppliers
      description: Retrieves a single assignment by its ID.
      parameters:
        - name: id
          in: path
          description: The work_group_supplier_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Assignment found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewWorkGroupSupplier"
        "404":
          description: Assignment not found
  /v2/work-group-supplier/update/{id}:
    put:
      summary: update
      operationId: updateWorkGroupSupplier
      tags:
        - WorkGroupSuppliers
      description: Updates an existing assignment.
      parameters:
        - name: id
          in: path
          description: The work_group_supplier_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkGroupSupplier"
      responses:
        "200":
          description: Assignment updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkGroupSupplier"
        "404":
          description: Assignment not found
  /v2/work-group-supplier/delete/{id}:
    delete:
      summary: delete
      operationId: deleteWorkGroupSupplier
      tags:
        - WorkGroupSuppliers
      description: |
        Deletes a supplier-work group assignment.

        If `force=false` (default), the response lists child entities.
        If `force=true`, the assignment is deleted.
      parameters:
        - name: id
          in: path
          description: The work_group_supplier_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the assignment.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Assignment deleted successfully
        "400":
          description: Preview of entities that would be deleted (returned when force=false)
components:
  schemas:
    WorkGroupSupplier:
      type: object
      required:
        - work_group_id
        - unit_id
      properties:
        work_group_supplier_id:
          type: string
          format: uuid
          description: Unique identifier. Auto-generated if not provided.
        work_group_id:
          type: string
          format: uuid
          description: The work group. Pass the `work_group_id` from the WorkGroup API.
        unit_id:
          type: string
          format: uuid
          description: The supplier. Pass the `unit_id` from the Unit API.
    ViewWorkGroupSupplier:
      type: object
      properties:
        work_group_supplier_id:
          type: string
          format: uuid
        work_group_id:
          type: string
          format: uuid
        unit_id:
          type: string
          format: uuid
        code:
          type: string
          description: Supplier code.
        name:
          type: string
          description: Supplier name.
        created_at:
          type: integer
          description: Creation timestamp.
        updated_at:
          type: integer
          description: Last modification timestamp.
        work_group_code:
          type: string
        work_group_name:
          type: string
        work_group_type:
          type: string
          enum:
            - WORK_PLACE
            - HGROUP
            - JOB
        work_group_description:
          type: string
          nullable: true
        office_name:
          type: string
        office_code:
          type: string
        project_name:
          type: string
        project_type:
          type: string
          enum:
            - safety
            - template
        owned_active:
          type: boolean
          nullable: true
          description: Whether this assignment is currently active.
        parent_active:
          type: boolean
          nullable: true
          description: Whether the parent entities are currently active.
    WorkGroupSupplierIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewWorkGroupSupplier"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          enum:
            - name
            - code
            - work_group_name
            - work_group_code
        history:
          type: boolean
          description: If true, includes historicized entries.
      example:
        filter:
          work_group_id: 3a4b5c6d-7e8f-9012-abcd-ef3456789012
        per-page: 100
        page: 1
        sort: name
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
          scopes: {}
    AccessToken:
      type: apiKey
      in: query
      name: access-token
