openapi: 3.0.0
info:
  title: Equipment
  version: 2.0.0
  description: >
    An **Equipment** represents a piece of equipment registered in an office
    (work location).

    Examples: forklift, scaffolding, crane, drill press.


    Belongs to an office and can be subject to maintenance or check actions on
    the compliance schedule

    (ActionSubscription with `subscriber_type: EQUIPMENT`).

    Maintenance certificates reference the equipment via the `resource_id`
    field.


    Use this API to:

    - Register equipment present in an office

    - Get the `office_equipment_id` needed to create compliance schedule entries
    or certificates

    - Browse the equipment inventory for an office (filter by `office_id`)


    Supports historicization: when equipment or its parent office is
    historicized,

    the equipment and its child entities are excluded from normal queries.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/equipment/index:
    post:
      summary: index
      operationId: indexEquipment
      tags:
        - Equipments
      description: |
        Returns a paginated list of equipment.

        Most useful filters:
        - `office_id`: all equipment in a specific office
        - `name`: search by name
        - `project_id`: all equipment in a company
      requestBody:
        description: Parameters for searching equipment
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EquipmentIndexParams"
            example:
              filter:
                office_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                name: Forklift
              per-page: 20
              page: 1
              sort: name
      responses:
        "200":
          description: List of equipment
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewEquipment"
              example:
                - office_equipment_id: 1a2b3c4d-5e6f-7890-abcd-ef1234567890
                  office_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  code: FL-001
                  name: Forklift A
                  serial: SN-2024-0001
                  vendor: Toyota
                  model: 8FBN25
                  project_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
                  office_name: Rome North Site
                  project_name: Acme Construction Ltd
                  project_type: safety
                  owned_active: true
                  parent_active: true
          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/equipment/create:
    post:
      summary: create
      operationId: createEquipment
      tags:
        - Equipments
      description: |
        Registers a new piece of equipment in an office.

        Requires `office_id`, `project_id`, and `name`.
        The `office_equipment_id` is auto-generated if not provided.
      requestBody:
        description: Equipment to register
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Equipment"
            example:
              office_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              project_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
              code: FL-001
              name: Forklift A
              serial: SN-2024-0001
              vendor: Toyota
              model: 8FBN25
      responses:
        "201":
          description: Equipment registered successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Equipment"
  /v2/equipment/view/{id}:
    get:
      summary: view
      operationId: viewEquipment
      tags:
        - Equipments
      description: |
        Retrieves a single equipment entry by its ID.
      parameters:
        - name: id
          in: path
          description: The office_equipment_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Equipment found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewEquipment"
        "404":
          description: Equipment not found
  /v2/equipment/update/{id}:
    put:
      summary: update
      operationId: updateEquipment
      tags:
        - Equipments
      description: |
        Updates an existing equipment entry.
      parameters:
        - name: id
          in: path
          description: The office_equipment_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Equipment"
            example:
              name: Forklift A - Revised
              serial: SN-2024-0001-R
      responses:
        "200":
          description: Equipment updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Equipment"
        "404":
          description: Equipment not found
  /v2/equipment/delete/{id}:
    delete:
      summary: delete
      operationId: deleteEquipment
      tags:
        - Equipments
      description: |
        Deletes an equipment entry.

        If `force=false` (default), the response lists child entities.
        If `force=true`, the equipment and all related entities are deleted.
      parameters:
        - name: id
          in: path
          description: The office_equipment_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the equipment and all child entities. If false,
            returns a preview of affected entities.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Equipment deleted successfully
        "400":
          description: Preview of entities that would be deleted (returned when force=false)
components:
  schemas:
    Equipment:
      type: object
      required:
        - office_id
        - project_id
        - name
      properties:
        office_equipment_id:
          type: string
          format: uuid
          description: >
            Unique identifier. Auto-generated if not provided. Used as
            `subscriber_id` (with `subscriber_type: EQUIPMENT`) in the
            compliance schedule and as `resource_id` in certificates.
        office_id:
          type: string
          format: uuid
          description: The office this equipment belongs to. Pass the `office_id` from the
            Office API.
        equipment_id:
          type: string
          format: uuid
          description: Optional reference to an equipment model from the catalog (template).
        code:
          type: string
          maxLength: 45
          description: Identifier code.
        name:
          type: string
          maxLength: 255
          description: Name of the equipment.
        description:
          type: string
          nullable: true
          description: Optional description.
        project_id:
          type: string
          format: uuid
          description: The project (company). Pass the `project_id`.
        serial:
          type: string
          maxLength: 50
          description: Serial number.
        vendor:
          type: string
          maxLength: 50
          description: Manufacturer.
        model:
          type: string
          maxLength: 50
          description: Model name.
    ViewEquipment:
      type: object
      properties:
        office_equipment_id:
          type: string
          format: uuid
          description: Unique identifier. Used as `subscriber_id` (EQUIPMENT) or
            `resource_id`.
        office_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        equipment_id:
          type: string
          format: uuid
        code:
          type: string
        name:
          type: string
        description:
          type: string
        serial:
          type: string
        vendor:
          type: string
        model:
          type: string
        office_name:
          type: string
          description: Name of the office.
        project_name:
          type: string
          description: Name of the project (company).
        project_type:
          type: string
          enum:
            - safety
            - template
        category:
          type: string
          description: Equipment category (from the catalog if linked).
        owned_active:
          type: boolean
          nullable: true
          description: Whether this equipment is currently active.
        parent_active:
          type: boolean
          nullable: true
          description: Whether the parent office is currently active.
    EquipmentIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewEquipment"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          description: Field to sort by. Prefix with minus for descending order.
          enum:
            - code
            - name
            - office_name
            - project_name
        history:
          type: boolean
          description: If true, includes historicized (no longer active) entries. By
            default only current entries are returned.
      example:
        filter:
          office_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        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
