openapi: 3.0.3
info:
  title: Traceability APIs
  description: >-
    These APIs support the containment and release functionalities of the Traceability application. They enable integration with external systems by providing access to headers and items that are either contained or released. Additionally, two dedicated APIs handle the acknowledgment action, which confirms the reading of containment or release requests.
  version: 1.0.0
servers:
  - url: /api/traceabilityapi/v3/
tags:
  - name: oData
    description: This service provides access to Traceability APIs to apply the application's main functionalities such as containment and release.
paths:
  /api/traceabilityapi/v3/ContainmentRequest/action/SearchBySequence:
    post:
      tags:
        - oData
      summary: >-
      description: This API returns information about containment request headers starting from the sequence specified in the input request.
      requestBody: 
        content:
            application/json:
                schema:
                    type: object
                    properties:
                        sequence:
                            description: This sequence number indicates where to begin returning details about containment request headers.
                            type: number
                    required:
                         - sequence
      responses:
        '200':
          description: OK. The API request was successful and the server returned the requested data.
          content:
            application/json; charset=utf-8:
              examples:
                Response:
                  value: |- 
                    [
                        { 
                            "ContainmentRequestId": "36b13868-f86d-703d-7f9f-df55090911a4",
                            "Name": "ContainmentRequest_20251126180923Batch", 
                            "EventDateTime": "2025-11-26T12:39:54.706Z", 
                            "Comment": "ContainmentRequest_20251126180923Batch", 
                            "Author": "name.surname@siemens.com", 
                            "Sequence": 44, 
                            "IsValid": true 
                        }, 
                        { 
                            "ContainmentRequestId": "d829a971-184e-0f82-7533-c45e364a6271",
                            "Name": "ContainmentRequest_20251126163235_20k", 
                            "EventDateTime": "2025-11-26T15:34:35.866Z", 
                            "Comment": "teesti", 
                            "Author": "name.surname@siemens.com", 
                            "Sequence": 49, 
                            "IsValid": true
                        },
                        { 
                            "ContainmentRequestId": "0482c274-0200-cf60-a43c-31e43ace8711", 
                            "Name": "ContainmentRequest_20251127161819", 
                            "EventDateTime": "2025-11-27T10:48:57.757Z", 
                            "Comment": "ContainmentRequest_20251127161819 test", 
                            "Author": "name.surname@siemens.com", 
                            "Sequence": 50, 
                            "IsValid": true 
                        }
                    ] 
        '204':
          description: No content. The request was successful, but the server did not return any data.
        '400':
          description: Bad request. The server could not understand the request because one or more required parameters are missing or are not valid.
        '403':
          description: User is not authorized. The client is authenticated but does not have permission to access the requested resource. The Tenant is missing, or the token has expired, or the token is empty.
        '503':
          description: Service is unavailable. The server is temporarily unable to handle requests. The containment is not enabled, or the server is unable to retrieve the domain page size, or to retrieve the contained items.
  /api/traceabilityapi/v3/ContainmentRequest/action/SearchByTime:
    post:
      tags:
        - oData
      summary: >-
        
      description: This API returns details about containment request headers created within a specified time interval.
      requestBody: 
        content:
            application/json:
                schema:
                    type: object
                    properties:
                        from:
                            description: Interval start time.
                            type: string
                        to:
                            description: Interval end time.
                            type: string
                    required:
                         - from
                         - to
      responses:
        '200':
          description: OK. The API request was successful and the server returned the requested data.
          content:
            application/json; charset=utf-8:
              examples:
                Response:
                  value: |- 
                    [
                        { 
                            "ContainmentRequestId": "36b13868-f86d-703d-7f9f-df55090911a4",
                            "Name": "ContainmentRequest_20251126180923Batch", 
                            "EventDateTime": "2025-11-26T12:39:54.706Z", 
                            "Comment": "ContainmentRequest_20251126180923Batch", 
                            "Author": "name.surname@siemens.com", 
                            "Sequence": 44, 
                            "IsValid": true 
                        }, 
                        { 
                            "ContainmentRequestId": "d829a971-184e-0f82-7533-c45e364a6271",
                            "Name": "ContainmentRequest_20251126163235_20k", 
                            "EventDateTime": "2025-11-26T15:34:35.866Z", 
                            "Comment": "testt", 
                            "Author": "name.surname@siemens.com", 
                            "Sequence": 49, 
                            "IsValid": true
                        },
                        { 
                            "ContainmentRequestId": "0482c274-0200-cf60-a43c-31e43ace8711", 
                            "Name": "ContainmentRequest_20251127161819", 
                            "EventDateTime": "2025-11-27T10:48:57.757Z", 
                            "Comment": "ContainmentRequest_20251127161819 test", 
                            "Author": "name.surname@siemens.com", 
                            "Sequence": 50, 
                            "IsValid": true 
                        }
                    ] 
        '204':
          description: No content. The request was successful, but the server did not return any data.
        '400':
          description: Bad request. The server could not understand the request because one or more required parameters are missing or are not valid.
        '403':
          description: User is not authorized. The client is authenticated but does not have permission to access the requested resource. The Tenant is missing, or the token has expired, or the token is empty.
        '503':
          description: Service is unavailable. The server is temporarily unable to handle requests. The containment is not enabled, or the server is unable to retrieve the domain page size, or to retrieve the contained items.
  /api/traceabilityapi/v3/ContainmentRequestDetail/action/Search:
    post:
      tags:
        - oData
      summary: >-
        
      description: This API returns an array of production tracking items that were contained by means of a specific containment request.
      requestBody: 
        content:
            application/json:
                schema:
                    type: object
                    properties:
                        ContainmentRequestId:
                            description: The containment request Id to search for.
                            type: string
                        ActionExecutionId:
                            description: Action execution Id of the containment request. The value of the first call is -1.
                            type: string
                        Offset:
                            description: Offset indicating where to start the detail search. The value of the first call is -1.
                            type: string
                    required:
                         - ContainmentRequestId
                         - ActionExecutionId
                         - Offset
      responses:
        '200':
          description: OK. The API request was successful and the server returned the requested data.
          content:
            application/json; charset=utf-8:
              examples:
                Response:
                  value: |- 
                    { 
                        "ContainmentRequestId": "221bc7a6-31a7-4876-a60e-9aa90bd7fe94", 
                        "ActionExecutionId": 1764242410528, 
                        "Offset": -1, 
                        "ContainedProductionTrackingItems": [ 
                            { 
                                "Key": "MaterialTrackingUnitNId" 
                            },
                            {
                                "Key": "1_MTU300K000013D2-3E09-4C1D-8455-2C4B977DB99C", 
                                "EntityType": "MTU" 
                            }, 
                            { 
                                "Key": "1_MTU300K00005CD8-BD68-42CC-BC2D-8C9E678C7AA1",
                                "EntityType": "MTU" 
                            },
                            { 
                                "Key": "1_MTU300K00006F26-D613-490A-A426-285ECF875310", 
                                "EntityType": "MTU" 
                            }, 
                            { 
                                "Key": "1_MTU300K00009CC5-D922-4E22-A991-D9459865EBC6", 
                                "EntityType": "MTU" 
                            }
                        ] 
                    }
        '400':
          description: Bad request. The server could not understand the request because one or more required parameters are missing or are not valid.
        '403':
          description: User is not authorized. The client is authenticated but does not have permission to access the requested resource. The Tenant is missing, or the token has expired, or the token is empty.
        '503':
          description: Service is unavailable. The server is temporarily unable to handle requests. The containment is not enabled, or the server is unable to retrieve the domain page size, or to retrieve the contained items.
  /api/traceabilityapi/v3/ContainmentRequest/action/Acknowledge:
    post:
      tags:
        - oData
      summary: >-
        
      description: Endpoint used to send the acknowledgement of a single containment request to the Traceability application.
      requestBody: 
        content:
            application/json:
                schema:
                    type: object
                    properties:
                        ContainmentRequestId:
                            description: Acknowledged containment request Id.
                            type: string
                        EventDateTime:
                            description: Date and time when the acknowledgement was completed.
                            type: string
                        Comment'403'::
                            description: Acknowledgement comment.
                            type: string
                        Author_System:
                            description: Author of the acknowledgement (system or personnel).
                            type: string
                    required:
                         - ContainmentRequestId
                         - Author_System
      responses:
        '200':
          description: OK. The API request was successful and the server returned the requested data.
        '403':
          description: User is not authorized. The client is authenticated but does not have permission to access the requested resource. The Tenant is missing, or the token has expired, or the token is empty.
        '422':
          description: Invalid format. The request is semantically invalid or not well-formed.
        '503':
          description: Service is unavailable. The server is temporarily unable to handle requests. The containment is not enabled, or the server is unable to retrieve the domain page size, or to retrieve the contained items.
  /api/traceabilityapi/v3/ReleaseRequest/action/SearchBySequence:
    post:
      tags:
        - oData
      summary: >-
      description: This API returns information about release request headers starting from the sequence specified in the input request.
      requestBody: 
        content:
            application/json:
                schema:
                    type: object
                    properties:
                        sequence:
                            description: Sequence number indicating where to begin returning details about release request headers.
                            type: number
                    required:
                         - sequence
      responses:
        '200':
          description: OK. The API request was successful and the server returned the requested data.
          content:
            application/json; charset=utf-8:
              examples:
                Response:
                  value: |- 
                    [
                        { 
                            "ReleaseRequestId" : "49eab402-e228-7fb0-39ae-33d578af5bc7",
                            "ContainmentRequestId": "36b13868-f86d-703d-7f9f-df55090911a4",
                            "Name": "ContainmentRequest_20251126180923Batch", 
                            "EventDateTime": "2025-11-26T12:39:54.706Z", 
                            "Comment": "ContainmentRequest_20251126180923Batch", 
                            "Author": "name.surname@siemens.com", 
                            "Sequence": 66
                        }, 
                        { 
                            "ReleaseRequestId" : "51eab402-e228-8as9-39ae-33d578af4jfd",
                            "ContainmentRequestId": "d829a971-184e-0f82-7533-c45e364a6271",
                            "Name": "ContainmentRequest_20251126163235_20k", 
                            "EventDateTime": "2025-11-26T15:34:35.866Z", 
                            "Comment": "test", 
                            "Author": "name.surname@siemens.com", 
                            "Sequence": 67
                        }
                    ] 
        '204':
          description: No content. The request was successful, but the server did not return any data.
        '400':
          description: Bad request. The server could not understand the request because one or more required parameters are missing or are not valid.
        '403':
          description: User is not authorized. The client is authenticated but does not have permission to access the requested resource. The Tenant is missing, or the token has expired, or the token is empty.
        '503':
          description: Service is unavailable. The server is temporarily unable to handle requests. The containment is not enabled, or the server is unable to retrieve the domain page size, or to retrieve the contained items.
  /api/traceabilityapi/v3/ReleaseRequest/action/SearchByTime:
    post:
      tags:
        - oData
      summary: >-
        
      description: This API returns information about release request headers created within a specified time interval.
      requestBody: 
        content:
            application/json:
                schema:
                    type: object
                    properties:
                        from:
                            description: Start time of the interval.
                            type: string
                        to:
                            description: End time of the interval.
                            type: string
                    required:
                         - from
                         - to
      responses:
        '200':
          description: OK. The API request was successful and the server returned the requested data.
          content:
            application/json; charset=utf-8:
              examples:
                Response:
                  value: |- 
                    [
                        { 
                            "ReleaseRequestId" : "49eab402-e228-7fb0-39ae-33d578af5bc7",
                            "ContainmentRequestId": "36b13868-f86d-703d-7f9f-df55090911a4",
                            "Name": "ContainmentRequest_20251126180923Batch", 
                            "EventDateTime": "2025-11-26T12:39:54.706Z", 
                            "Comment": "ContainmentRequest_20251126180923Batch", 
                            "Author": "name.surname@siemens.com", 
                            "Sequence": 66
                        }, 
                        { 
                            "ReleaseRequestId" : "51eab402-e228-8as9-39ae-33d578af4jfd",
                            "ContainmentRequestId": "d829a971-184e-0f82-7533-c45e364a6271",
                            "Name": "ContainmentRequest_20251126163235_20k", 
                            "EventDateTime": "2025-11-26T15:34:35.866Z", 
                            "Comment": "test", 
                            "Author": "name.surname@siemens.com", 
                            "Sequence": 67
                        }
                    ] 
        '204':
          description: No content. The request was successful, but the server did not return any data.
        '400':
          description: Bad request. The server could not understand the request because one or more required parameters are missing or are not valid.
        '403':
          description: User is not authorized. The client is authenticated but does not have permission to access the requested resource. The Tenant is missing, or the token has expired, or the token is empty.
        '503':
          description: Service is unavailable. The server is temporarily unable to handle requests. The containment is not enabled, or the server is unable to retrieve the domain page size, or to retrieve the contained items.
  /api/traceabilityapi/v3/ReleaseRequestDetail/action/Search:
    post:
      tags:
        - oData
      summary: >-
        
      description: This API returns an array of the production tracking items released by means of a specific release request.
      requestBody: 
        content:
            application/json:
                schema:
                    type: object
                    properties:
                        ReleaseRequestId:
                            description: Release request Id to search for.
                            type: string
                        ActionExecutionId:
                            description: Action execution Id of the release request. The value of the first call is -1.
                            type: string
                        Offset:
                            description: Offset indicating where to start the detail search. The value of the first call is -1.
                            type: string
                    required:
                         - ReleaseRequestId
                         - ActionExecutionId
                         - Offset
      responses:
        '200':
          description: OK. The API request was successful and the server returned the requested data.
          content:
            application/json; charset=utf-8:
              examples:
                Response:
                  value: |- 
                    { 
                        "ReleaseRequestId": "221bc7a6-31a7-4876-a60e-9aa90bd7fe94", 
                        "ActionExecutionId": 1764242410528, 
                        "Offset": 1968160, 
                        "ReleasedProductionTrackingItems": [ 
                            { 
                                "Key": "MaterialTrackingUnitNId" 
                            },
                            {
                                "Key": "1_MTU300K000013D2-3E09-4C1D-8455-2C4B977DB99C", 
                                "EntityType": "MTU" 
                            }, 
                            { 
                                "Key": "1_MTU300K00005CD8-BD68-42CC-BC2D-8C9E678C7AA1",
                                "EntityType": "MTU" 
                            },
                            { 
                                "Key": "1_MTU300K00006F26-D613-490A-A426-285ECF875310", 
                                "EntityType": "MTU" 
                            }, 
                            { 
                                "Key": "1_MTU300K00009CC5-D922-4E22-A991-D9459865EBC6", 
                                "EntityType": "MTU" 
                            }
                        ] 
                    }
        '400':
          description: Bad request. The server could not understand the request because one or more required parameters are missing or are not valid.
        '403':
          description: User is not authorized. The client is authenticated but does not have permission to access the requested resource. The Tenant is missing, or the token has expired, or the token is empty.
        '503':
          description: Service is unavailable. The server is temporarily unable to handle requests. The containment is not enabled, or the server is unable to retrieve the domain page size, or to retrieve the contained items.
  /api/traceabilityapi/v3/ReleaseRequest/action/Acknowledge:
    post:
      tags:
        - oData
      summary: >-
        
      description: Endpoint used to send the acknowledgement of a single release request to the Traceability application.
      requestBody: 
        content:
            application/json:
                schema:
                    type: object
                    properties:
                        ReleaseRequestId:
                            description: Acknowledged release request Id.
                            type: string
                        EventDateTime:
                            description: Date and time when the acknowledgement was completed.
                            type: string
                        Comment:
                            description: Acknowledgement comment.
                            type: string
                        Author_System:
                            description: Author of the acknowledgement (system or personnel).
                            type: string
                    required:
                         - ReleaseRequestId
                         - Author_System
      responses:
        '200':
          description: OK. The API request was successful and the server returned the requested data.
        '403':
          description: User is not authorized. The client is authenticated but does not have permission to access the requested resource. The Tenant is missing, or the token has expired, or the token is empty.
        '422':
          description: Invalid format. The request is semantically invalid or not well-formed.
        '503':
          description: Service is unavailable. The server is temporarily unable to handle requests. The containment is not enabled, or the server is unable to retrieve the domain page size, or to retrieve the contained items.
