openapi: 3.0.0
info:
  title: Incident
  version: 2.0.0
  description: >
    An **Incident** represents an event or report registered in an office: an
    accident,

    a near-miss, a non-compliance, a malfunction report, or an intervention
    request.


    Belongs to an office (via `subtenant_id` = office_id) and has a workflow
    status:

    - `new`: just reported

    - `open`: being handled

    - `closed`: resolved (with closing date)


    An incident can have:

    - Involved people (IncidentPerson)

    - Involved resources (IncidentResource): equipment, environments,
    substances, work groups, materials

    - Linked corrective actions (IncidentAction)


    Use this API to:

    - Report a new incident in an office

    - Browse incidents for an office (filter by `subtenant_id`)

    - Filter by category or status

    - Manage the incident lifecycle (new → open → closed)
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/incident/index:
    post:
      summary: index
      operationId: indexIncident
      tags:
        - Incidents
      description: |
        Returns a paginated list of incidents.

        Most useful filters:
        - `subtenant_id` (office_id): all incidents in an office
        - `status`: filter by workflow status (`new`, `open`, `closed`)
        - `category`: filter by incident type
        - `tenant_id` (project_id): all incidents in a company
      requestBody:
        description: Parameters for searching incidents
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentIndexParams"
            example:
              filter:
                subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                status: open
              per-page: 20
              page: 1
              sort: -date_incident
      responses:
        "200":
          description: List of incidents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewIncident"
          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/incident/create:
    post:
      summary: create
      operationId: createIncident
      tags:
        - Incidents
      description: >
        Reports a new incident.


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

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


        After creation, add involved people via IncidentPerson, involved
        resources via

        IncidentResource, and corrective actions via IncidentAction.
      requestBody:
        description: Incident to report
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Incident"
      responses:
        "201":
          description: Incident reported successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
  /v2/incident/view/{id}:
    get:
      summary: view
      operationId: viewIncident
      tags:
        - Incidents
      description: Retrieves a single incident by its ID.
      parameters:
        - name: id
          in: path
          description: The office_incident_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Incident found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewIncident"
        "404":
          description: Incident not found
  /v2/incident/update/{id}:
    put:
      summary: update
      operationId: updateIncident
      tags:
        - Incidents
      description: >
        Updates an existing incident.


        Common use case: changing status to `open` (being handled) or `closed`
        (resolved).

        When setting `status` to `closed`, the `date_closed` field is required.
      parameters:
        - name: id
          in: path
          description: The office_incident_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Incident"
      responses:
        "200":
          description: Incident updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
        "404":
          description: Incident not found
  /v2/incident/delete/{id}:
    delete:
      summary: delete
      operationId: deleteIncident
      tags:
        - Incidents
      description: >
        Deletes an incident.


        If `force=false` (default), the response lists child entities (people,
        resources, actions).

        If `force=true`, the incident and all related entities are deleted.
      parameters:
        - name: id
          in: path
          description: The office_incident_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the incident and all child entities.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Incident deleted successfully
        "400":
          description: Preview of entities that would be deleted (returned when force=false)
components:
  schemas:
    Incident:
      type: object
      required:
        - name
        - date_incident
        - tenant_id
        - subtenant_id
      properties:
        office_incident_id:
          type: string
          format: uuid
          description: Unique identifier. Auto-generated if not provided.
        code:
          type: string
          maxLength: 50
          description: Identifier code.
        name:
          type: string
          description: Title/name of the incident.
        date_incident:
          type: string
          format: date
          description: Date when the incident occurred.
        category:
          type: string
          maxLength: 50
          enum:
            - NON_COMPLIANCE
            - ACCIDENTS
            - ACCIDENTS_AND_MISSED_INJURIES
            - REPORT_MALFUNCTION
            - REPORT_FAILURE
            - REQUEST_INSPECTION
            - REQUEST_MAINTENANCE
            - REQUEST_REPLACEMENT
            - REQUEST_INTERVENTION
          description: |
            Incident category:
            - `NON_COMPLIANCE`: non-compliance
            - `ACCIDENTS`: accident
            - `ACCIDENTS_AND_MISSED_INJURIES`: accident and near-miss
            - `REPORT_MALFUNCTION`: malfunction report
            - `REPORT_FAILURE`: failure report
            - `REQUEST_INSPECTION`: inspection request
            - `REQUEST_MAINTENANCE`: maintenance request
            - `REQUEST_REPLACEMENT`: replacement request
            - `REQUEST_INTERVENTION`: intervention request
        description_event:
          type: string
          description: Description of what happened.
        description_actions_involved:
          type: string
          description: Description of actions taken.
        deponent:
          type: string
          description: Name of the person who reported the incident.
        manager:
          type: string
          format: json
          description: Incident managers (JSON).
        assignee:
          type: string
          format: json
          description: Incident assignees (JSON).
        watcher:
          type: string
          format: json
          description: Incident watchers (JSON).
        to:
          type: object
          description: Notification recipients (JSON).
        status:
          type: string
          maxLength: 50
          enum:
            - new
            - open
            - closed
          description: |
            Workflow status:
            - `new`: just reported
            - `open`: being handled
            - `closed`: resolved (requires `date_closed`)
        external_reference_id:
          type: string
          maxLength: 50
          description: External reference number (e.g. INAIL, OSHA, CPAM case number).
        date_closed:
          type: string
          format: date
          description: Closing date. Required when `status` is `closed`.
        creator:
          type: string
          description: Username of the person who created the incident. Auto-set on
            creation.
        created_at:
          type: string
          description: Creation timestamp. Auto-set on creation.
        tenant_id:
          type: string
          format: uuid
          description: The project (company). Pass the `project_id`.
        subtenant_id:
          type: string
          format: uuid
          description: The office where the incident occurred. Pass the `office_id`.
    ViewIncident:
      type: object
      properties:
        office_incident_id:
          type: string
          format: uuid
        code:
          type: string
        name:
          type: string
        date_incident:
          type: string
          format: date
        category:
          type: string
          enum:
            - NON_COMPLIANCE
            - ACCIDENTS
            - ACCIDENTS_AND_MISSED_INJURIES
            - REPORT_MALFUNCTION
            - REPORT_FAILURE
            - REQUEST_INSPECTION
            - REQUEST_MAINTENANCE
            - REQUEST_REPLACEMENT
            - REQUEST_INTERVENTION
        description_event:
          type: string
        description_actions_involved:
          type: string
        deponent:
          type: string
        manager:
          type: string
          format: json
        assignee:
          type: string
          format: json
        watcher:
          type: string
          format: json
        to:
          type: object
        status:
          type: string
          enum:
            - new
            - open
            - closed
        external_reference_id:
          type: string
        date_closed:
          type: string
          format: date
        creator:
          type: string
        created_at:
          type: string
        tenant_id:
          type: string
          format: uuid
        subtenant_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
        totInvolvedPerson:
          type: integer
          description: Total number of people involved in the incident.
        totSicknessDays:
          type: integer
          description: Total sickness days across all involved people.
    IncidentIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewIncident"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          enum:
            - name
            - code
            - date_incident
            - status
            - category
            - office_name
            - project_name
      example:
        filter:
          subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          status: open
        per-page: 100
        page: 1
        sort: -date_incident
  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
