openapi: 3.0.0
info:
  title: CertificateAction
  version: 2.0.0
  description: >
    A **CertificateAction** links a certificate to a specific action, proving
    that the certificate

    satisfies that compliance requirement. It is the connection between the
    proof of compliance

    (the certificate) and the required action.


    Requires an existing certificate and an existing action within the same
    project.


    After creation, the system automatically recalculates the compliance status
    of matching

    compliance schedule entries (ActionSubscription) for the same action and the
    same resource

    as the certificate. Without this link, the certificate exists but has no
    effect on the

    compliance schedule.


    The `date_expire` field is the expiration date specific to this link. If not
    provided,

    it is inherited from the certificate's expiration date. The
    `is_date_inherited` field

    in responses indicates whether the date belongs to this link or is inherited
    from the certificate.


    Use this API to:

    - Link a certificate to an action after creating the certificate

    - Find all certificate-action links for a certificate or an action

    - Check which certificate covers which action for a resource
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
webhooks:
  CERTIFICATE_ACTION::CREATE:
    post:
      summary: Certificate-action created
      security: []
      description: |
        Triggered when a new certificate-action link is created.
      requestBody:
        description: The newly created certificate-action link
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CertificateAction"
            example:
              certificate_action_id: a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d
              certificate_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
              action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
              date_expire: 2029-01-15
              tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
      responses:
        "200":
          description: Acknowledgment of the webhook event
  CERTIFICATE_ACTION::UPDATE:
    post:
      summary: Certificate-action updated
      security: []
      description: >
        Triggered when a certificate-action link is updated. Provides old/new
        values for changed fields.
      requestBody:
        description: Updated certificate-action with old and new values for changed fields
        content:
          application/json:
            schema:
              type: object
              properties:
                entity_id:
                  type: string
                  format: uuid
                  description: The certificate_action_id of the updated link.
                updated_fields:
                  type: object
                  additionalProperties:
                    type: object
                    properties:
                      old: {}
                      new: {}
                  description: Each key is an updated field name, with its old and new values.
              required:
                - entity_id
                - updated_fields
            example:
              entity_id: a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d
              updated_fields:
                date_expire:
                  old: 2029-01-15
                  new: 2030-01-15
      responses:
        "200":
          description: Acknowledgment of the webhook event
  CERTIFICATE_ACTION::DELETE:
    post:
      summary: Certificate-action deleted
      security: []
      description: |
        Triggered when a certificate-action link is deleted.
      requestBody:
        description: The deleted certificate-action link
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CertificateAction"
            example:
              certificate_action_id: a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d
              certificate_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
              action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
              tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
      responses:
        "200":
          description: Acknowledgment of the webhook event
paths:
  /v2/certificate-action/index:
    post:
      summary: index
      operationId: indexCertificateAction
      tags:
        - CertificateActions
      description: |
        Returns a paginated list of certificate-action links.

        Most useful filters:
        - `certificate_id`: all links for a specific certificate
        - `action_id`: all certificates linked to an action
        - `action_type`: filter by requirement type
        - `resource_id`: all links for a specific resource
      requestBody:
        description: Parameters for searching certificate-action links
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CertificateActionIndexParams"
            example:
              filter:
                action_type: TRAINING
                certificate_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
              per-page: 10
              page: 1
              sort: action_name
      responses:
        "200":
          description: List of certificate-action links
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewCertificateAction"
              example:
                - certificate_action_id: a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d
                  certificate_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
                  action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
                  date_expire: 2029-01-15
                  tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
                  action_name: Fire Safety Training Medium Risk
                  action_code: FST-01
                  action_type: TRAINING
                  resource_id: e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a
                  certificate_name: Fire Safety Training Certificate
                  date_release: 2024-01-15
                  is_date_inherited: 0
                  office_name: Rome North Site
                  office_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          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/certificate-action/create:
    post:
      summary: create
      operationId: createCertificateAction
      tags:
        - CertificateActions
      description: >
        Creates a new certificate-action link.


        Requires `certificate_id`, `action_id`, and `tenant_id` (project_id).

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


        After creation, the system automatically updates the compliance status
        of matching

        schedule entries. This is the step that actually transitions a
        subscription from

        `NEW` or `EXPIRED` to `VALID`.


        The `date_expire` field is optional: if not provided, the expiration is
        inherited

        from the certificate.
      requestBody:
        description: Certificate-action link to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CertificateAction"
            example:
              certificate_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
              action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
              tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
      responses:
        "201":
          description: Certificate-action link created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CertificateAction"
              example:
                certificate_action_id: a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d
                certificate_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
                action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
                date_expire: 2029-01-15
                tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
  /v2/certificate-action/view/{id}:
    get:
      summary: view
      operationId: viewCertificateAction
      tags:
        - CertificateActions
      description: |
        Retrieves a single certificate-action link by its ID.
      parameters:
        - name: id
          in: path
          description: The certificate_action_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Certificate-action link found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewCertificateAction"
              example:
                certificate_action_id: a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d
                certificate_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
                action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
                date_expire: 2029-01-15
                tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
                action_name: Fire Safety Training Medium Risk
                action_code: FST-01
                action_type: TRAINING
                resource_id: e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a
                certificate_name: Fire Safety Training Certificate
                date_release: 2024-01-15
                is_date_inherited: 0
                office_name: Rome North Site
                office_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        "404":
          description: Certificate-action link not found
  /v2/certificate-action/update/{id}:
    put:
      summary: update
      operationId: updateCertificateAction
      tags:
        - CertificateActions
      description: |
        Updates an existing certificate-action link.

        Typical use case: changing the `date_expire` specific to this link.
      parameters:
        - name: id
          in: path
          description: The certificate_action_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CertificateAction"
            example:
              date_expire: 2030-01-15
      responses:
        "200":
          description: Certificate-action link updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CertificateAction"
              example:
                certificate_action_id: a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d
                date_expire: 2030-01-15
        "404":
          description: Certificate-action link not found
  /v2/certificate-action/delete/{id}:
    delete:
      summary: delete
      operationId: deleteCertificateAction
      tags:
        - CertificateActions
      description: >
        Deletes a certificate-action link.


        After deletion, the system automatically recalculates the compliance
        status of matching

        schedule entries. This may cause a subscription to revert to `EXPIRED`
        or `NEW`.


        If `force=false` (default), the response lists related entities.

        If `force=true`, the link is deleted.
      parameters:
        - name: id
          in: path
          description: The certificate_action_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the link. If false, returns a preview of affected
            entities.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Certificate-action link deleted successfully
        "400":
          description: Preview of entities that would be affected (returned when
            force=false)
components:
  schemas:
    CertificateAction:
      type: object
      properties:
        certificate_action_id:
          type: string
          format: uuid
          description: Unique identifier of the link. Auto-generated if not provided on
            creation.
        certificate_id:
          type: string
          format: uuid
          description: The certificate being linked. Pass the `certificate_id` obtained
            from the Certificate API.
        action_id:
          type: string
          format: uuid
          description: The action the certificate is linked to. Pass the `action_id`
            obtained from the Action API.
        date_expire:
          type: string
          format: date
          description: Expiration date specific to this link. If not provided, inherited
            from the certificate's expiration date.
        tenant_id:
          type: string
          format: uuid
          description: The project (company) this link belongs to. Pass the `project_id`.
      required:
        - certificate_id
        - action_id
        - tenant_id
    ViewCertificateAction:
      type: object
      properties:
        certificate_action_id:
          type: string
          format: uuid
          description: Unique identifier of the link.
        certificate_id:
          type: string
          format: uuid
          description: The linked certificate.
        action_id:
          type: string
          format: uuid
          description: The linked action.
        date_expire:
          type: string
          format: date
          description: Expiration date. May be inherited from the certificate if not set
            on this link.
        tenant_id:
          type: string
          format: uuid
          description: The project (company) this link belongs to.
        action_name:
          type: string
          description: Name of the linked action.
        action_code:
          type: string
          description: Code of the linked action.
        action_type:
          type: string
          enum:
            - TRAINING
            - HEALTH
            - PER
            - CHECK
            - MAINTENANCE
          description: Type of the linked action.
        resource_id:
          type: string
          format: uuid
          description: The resource the certificate is issued to (from the certificate).
        certificate_name:
          type: string
          description: Name of the linked certificate.
        is_date_inherited:
          type: integer
          description: Whether `date_expire` is inherited from the certificate (`1`) or
            set on this link (`0`).
        date_release:
          type: string
          format: date
          description: Issue date of the linked certificate.
        office_name:
          type: string
          description: Name of the office where the action is defined.
        office_id:
          type: string
          format: uuid
          description: ID of the office where the action is defined.
    CertificateActionIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewCertificateAction"
        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 (e.g.
            "-date_expire").
          enum:
            - certificate_action_id
            - action_code
            - action_name
            - action_type
            - resource_id
            - certificate_name
            - date_expire
            - date_release
            - office_name
      example:
        filter:
          action_type: TRAINING
          certificate_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
        per-page: 100
        page: 1
        sort: action_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
