openapi: 3.0.0
info:
  title: Material Item
  version: 2.0.0
  description: >
    A **MaterialItem** represents an individual item (or batch) of a material.

    For example, if the Material is "Safety Helmet Model X", a MaterialItem is a
    specific

    helmet with its own serial number.


    Belongs to a Material and to an office (via `subtenant_id` = office_id).

    Can be subject to actions on the compliance schedule

    (ActionSubscription with `subscriber_type: PPE`).


    Use this API to:

    - Register individual items or batches of a material type

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

    - Browse items of a material (filter by `material_id`)


    Supports historicization.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/material-item/index:
    post:
      summary: index
      operationId: indexMaterialItem
      tags:
        - MaterialItems
      description: |
        Returns a paginated list of material items.

        Most useful filters:
        - `material_id`: all items of a specific material type
        - `subtenant_id` (office_id): all items in an office
        - `name`: search by name
      requestBody:
        description: Parameters for searching material items
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MaterialItemIndexParams"
            example:
              filter:
                material_id: 2a3b4c5d-6e7f-8901-abcd-ef2345678901
              per-page: 20
              page: 1
              sort: name
      responses:
        "200":
          description: List of material items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewMaterialItem"
          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/material-item/create:
    post:
      summary: create
      operationId: createMaterialItem
      tags:
        - MaterialItems
      description: >
        Registers a new individual item or batch.


        Requires `material_id`, `subtenant_id` (office_id), `tenant_id`
        (project_id), and `name`.

        The `material_item_id` is auto-generated if not provided.


        The Material must already exist (created via the Material API).
      requestBody:
        description: Material item to register
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MaterialItem"
      responses:
        "201":
          description: Material item registered successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MaterialItem"
  /v2/material-item/view/{id}:
    get:
      summary: view
      operationId: viewMaterialItem
      tags:
        - MaterialItems
      description: Retrieves a single material item by its ID.
      parameters:
        - name: id
          in: path
          description: The material_item_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Material item found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewMaterialItem"
        "404":
          description: Material item not found
  /v2/material-item/update/{id}:
    put:
      summary: update
      operationId: updateMaterialItem
      tags:
        - MaterialItems
      description: Updates an existing material item.
      parameters:
        - name: id
          in: path
          description: The material_item_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MaterialItem"
      responses:
        "200":
          description: Material item updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MaterialItem"
        "404":
          description: Material item not found
  /v2/material-item/delete/{id}:
    delete:
      summary: delete
      operationId: deleteMaterialItem
      tags:
        - MaterialItems
      description: |
        Deletes a material item.

        If `force=false` (default), the response lists child entities.
        If `force=true`, the item and all related entities are deleted.
      parameters:
        - name: id
          in: path
          description: The material_item_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the item and all child entities.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Material item deleted successfully
        "400":
          description: Preview of entities that would be deleted (returned when force=false)
components:
  schemas:
    MaterialItem:
      type: object
      required:
        - material_id
        - subtenant_id
        - tenant_id
        - name
      properties:
        material_item_id:
          type: string
          format: uuid
          description: >
            Unique identifier. Auto-generated if not provided. Used as
            `subscriber_id` (with `subscriber_type: PPE`) in the compliance
            schedule and as `resource_id` in certificates.
        material_id:
          type: string
          format: uuid
          description: The material type this item belongs to. Pass the `material_id` from
            the Material API.
        code:
          type: string
          maxLength: 50
          description: Identifier code.
        name:
          type: string
          maxLength: 255
          description: Name of the item.
        description:
          type: string
          nullable: true
          description: Optional description.
        serial:
          type: string
          maxLength: 50
          description: Serial number.
        vendor:
          type: string
          maxLength: 50
          description: Manufacturer.
        model:
          type: string
          maxLength: 50
          description: Model name.
        data:
          type: object
          description: Additional structured data in JSON format (may include initial
            quantity).
        subtenant_id:
          type: string
          format: uuid
          description: The office this item belongs to. Pass the `office_id`.
        tenant_id:
          type: string
          format: uuid
          description: The project (company). Pass the `project_id`.
    ViewMaterialItem:
      type: object
      properties:
        material_item_id:
          type: string
          format: uuid
          description: Unique identifier. Used as `subscriber_id` (PPE) or `resource_id`.
        material_id:
          type: string
          format: uuid
        code:
          type: string
        name:
          type: string
        description:
          type: string
        serial:
          type: string
        vendor:
          type: string
        model:
          type: string
        data:
          type: object
        subtenant_id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        office_name:
          type: string
          description: Name of the office.
        project_name:
          type: string
          description: Name of the project.
        project_type:
          type: string
          enum:
            - safety
            - template
        material_item_count:
          type: integer
          description: Available quantity (initial quantity minus items assigned via
            certificates).
        initial_quantity:
          type: integer
          description: Initial quantity of the item or batch.
        owned_active:
          type: boolean
          nullable: true
          description: Whether this item is currently active.
        parent_active:
          type: boolean
          nullable: true
          description: Whether the parent entities are currently active.
    MaterialItemIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewMaterialItem"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          enum:
            - code
            - name
            - serial
            - office_name
            - project_name
        history:
          type: boolean
          description: If true, includes historicized entries.
      example:
        filter:
          material_id: 2a3b4c5d-6e7f-8901-abcd-ef2345678901
        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
