openapi: "3.0.3"

#
# THE MASTER FILE FOR THIS API IS STORED INSIDE MSOA. MODIFICATIONS TO THIS
# API SPECIFICATION ARE ONLY ALLOWED IN THE MASTER FILE. ALL COPIES OF THIS FILE
# ARE MEANT TO BE READ-ONLY FOR CODE GENERATION PURPOSES.
#

info:
  title: Transport Order API
  description: >
    This API allows to create new transport orders.
    The orders will be executed by AGVs connected to SYNA.OS.
    Also its possible to update existing transport orders. In
    addition, information on existing transport orders can be queried.

  version: "1.8"
servers:
  - url: /v1
    description: Local server url
paths:
  /api/transport-orders:
    get:
      summary: Returns all transport orders for a given filter
      description: >
        This endpoint returns transport orders that match a given filter.
        If no filter is set it returns all transport orders.
      operationId: readAll
      tags:
        - Transport Order
      parameters:
        - in: query
          name: state
          schema:
            type: string
          required: false
          description: >
            Comma separated list of states (no whitespaces).
            Only transport orders in one of those states are returned.
            Supported values are: Pending, Started, Completed, Failed
        - in: query
          name: loadType
          schema:
            type: string
          required: false
          description: >
            Return only transport orders with the given load type.
            Supported values are: Full, Empty
        - in: query
          name: externalId
          schema:
            type: string
          required: false
          description: The external id of the transport order
        - in: query
          name: externalLoadId
          schema:
            type: string
          required: false
          description: The external id of the load that is transported by the transport order
        - in: query
          name: associatedFullOrderId
          schema:
            type: string
            format: uuid
          required: false
          description: The id of the full order that is associated to the searched (empty) transport order
      responses:
        200:
          description: All transport orders that match the given filter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArrayOfReadTransportOrders"
      security:
        - oauthToken:
            - FPOS_ADMIN
            - FPOS_EXTERNAL_API
    post:
      summary: Creates a new transport order
      description: >
        This will create and return a new transport order.
        The returned transport order contains all values that were automatically set by SYNA.OS upon creation.
      operationId: create
      tags:
        - Transport Order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTransportOrder"
      responses:
        200:
          description: New transport order created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadTransportOrder"
        400:
          description: Invalid request body
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problems"
        500:
          description: Creating new order not possible due internal server error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problems"
      security:
        - oauthToken:
            - FPOS_ADMIN
            - FPOS_EXTERNAL_API

  /api/transport-orders/{id}:
    get:
      summary: Returns the transport order
      description: >
        Finds a transport order for the given id and returns all information
        for this specific order.
      operationId: readByInternalId
      tags:
        - Transport Order
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
            minimum: 1
          description: The id of the transport order
      responses:
        200:
          description: Found transport order with the given id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadTransportOrder"
        404:
          description: No transport order found with the given id
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problems"
      security:
        - oauthToken:
            - FPOS_ADMIN
            - FPOS_EXTERNAL_API
    patch:
      summary: Updates the transport order
      description: >
        This endpoint allows the modification of attributes in an existing transport
        order. For a given id also a request body with required attributes is needed.
      operationId: update
      tags:
        - Transport Order
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
            minimum: 1
          description: The id of the transport order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateTransportOrder"
      responses:
        200:
          description: Updated transport order with the given id
        400:
          description: Invalid patch message
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problems"
        404:
          description: No transport order found with the given id
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problems"
        500:
          description: Update not possible due to internal server error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problems"
      security:
        - oauthToken:
            - FPOS_ADMIN
            - FPOS_EXTERNAL_API
  /api/transport-orders/{id}/cancel:
    post:
      summary: Cancels the transport order
      description: >
        Cancels the transport order. The exact behaviour is subject to change in future versions. Currently sets the transport order to be finished and removes it from scheduling. When an AGV is currently executing the transport order the execution will be cancelled and the AGV will be put into manual order mode.
      operationId: cancel
      tags:
        - Transport Order
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
            minimum: 1
          description: The id of the transport order
      responses:
        200:
          description: The cancellation was successfully initiated.
        400:
          description: Invalid cancellation request
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problems"
        404:
          description: No transport order found with the given id
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problems"
        500:
          description: Cancellation not possible due to internal server error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problems"
      security:
        - oauthToken:
            - FPOS_ADMIN
            - FPOS_EXTERNAL_API
components:
  schemas:
    UpdateTransportOrder:
      type: object
      properties:
        finishedManually:
          type: boolean
          description: TRUE, when the transport order was finished manually, otherwise FALSE.
          example: false
        dropStation:
          type: string
          description: >
            The name of the handling station group or handling station where the vehicle has
            to drop off the load. Must be a valid handling station group or handling station on the map
          example: HS01
        pickStation:
          type: string
          description: >
            The name of the handling station group or handling station where the vehicle has
            to pick up the load. Must be a valid handling station group or handling station on the map.
          example: HS01
        earliestPickTime:
          type: string
          format: date-time
          description: The earliest allowed pick-up time as RFC-3339 timestamp.
          example: "2020-08-06T15:45:00Z"
        latestPickTime:
          type: string
          format: date-time
          description: The latest allowed pick-up time as RFC-3339 timestamp.
          example: "2020-08-06T15:50:00Z"
        earliestDropTime:
          type: string
          format: date-time
          description: The earliest allowed drop-off time as RFC-3339 timestamp.
          example: "2020-08-06T15:50:00Z"
        latestDropTime:
          type: string
          format: date-time
          description: The latest allowed drop-off time as RFC-3339 timestamp.
          example: "2020-08-06T16:05:00Z"
        customAttributes:
          type: object
          description: A Field for customer specific attributes.
          additionalProperties:
            type: string
          example:
            customAttributeName1: customAttributeValue1
            customAttributeName2: customAttributeValue2

    ReadTransportOrder:
      type: object
      required:
        - id
        - externalId
        - loadId
        - externalLoadId
        - priority
        - status
        - statusUpdated
        - orderType
        - cancelable
        - loaded
        - finishedManually
        - customAttributes
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the transport order.
          example: b2d83800-4e44-4818-a252-61c5a90948c9
        externalId:
          type: string
          description: The external identifier of the transport order.
          example: Order-123
        loadId:
          type: string
          format: uuid
          description: The unique identifier of the load of the transport order.
          example: fbfacd5e-82d7-4915-b3fe-00c70c9fcda8
        externalLoadId:
          type: string
          description: The external unique identifier of the load of the transport order.
          example: Load-123
        priority:
          type: integer
          description: The priority of the transport order. Higher priority is represented by a lower number, so 0 is highest.
          example: 1
        status:
          type: string
          enum: [ RECEIVED, STARTED, FINISHED_SUCCESS, FINISHED_FAILURE ]
          description: The status of the transport order.
          example: RECEIVED
        statusUpdated:
          type: string
          format: date-time
          description: The time when the status of the transport order was last updated.
          example: "2020-08-06T15:50:00Z"
        partNumber:
          type: string
          description: The name of the part that is transported with that transport order.
          example: Part-123
        containerType:
          type: string
          description: The type of the container the payload is packed up in.
          example: Container-1234
        orderType:
          type: string
          enum: [ FULL, EMPTY ]
          description: The order type specifies if this a full or empty order. Default is `full`.
          example: FULL
        cancelable:
          type: boolean
          description: TRUE, when the transport order can be cancelled manually, otherwise FALSE.
          example: false
        loaded:
          type: boolean
          description: TRUE, when the pickup of the transport has happened, otherwise FALSE.
          example: false
        finishedManually:
          type: boolean
          description: TRUE, when the transport order was finished manually, otherwise FALSE.
          example: false
        associatedFullTransportOrderId:
          type: string
          format: uuid
          description: The internal id of the full transport order which is prepared by this empty transport order.
          example: 6dc5f471-ebe8-424f-96b3-5ef35c434346
        precedingTransportOrderInSequenceId:
          type: string
          format: uuid
          description: The id of the transport order that is previous in the sequence of delivery.
          example: ae47c394-b78e-4480-bf42-0283fc791c89
        pickStationId:
          type: string
          format: uuid
          description: >
            The id of the handling station group or handling station where the vehicle has
            to pick up the load. Must be a valid handling station group or handling station on the map.
          example: 49a089f3-3745-40b4-a8f2-7819eb8b925c
        externalPickStationId:
          type: string
          description: >
            The external id of the handling station group or handling station where the vehicle has
            to pick up the load. Must be a valid handling station group or handling station on the map.
          example: HSG_lane4_section1
        pickStationIdOfGroup:
          type: boolean
          description: >
            TRUE, when the id of the pick station identifies a group of handling stations,
            FALSE, when it identifies a concrete handling station.
          example: true
        dropStationId:
          type: string
          format: uuid
          description: >
            The id of the handling station group or handling station where the vehicle has
            to drop off the load. Must be a valid handling station group or handling station on the map
          example: 5a9d4e36-5124-4f2a-8ac2-10cc4a4388ce
        externalDropStationId:
          type: string
          description: >
            The external id of the handling station group or handling station where the vehicle has
            to drop off the load. Must be a valid handling station group or handling station on the map
          example: HSG_lane4_section1
        dropStationIdOfGroup:
          type: boolean
          description: >
            TRUE, when the id of the drop station identifies a group of handling stations,
            FALSE, when it identifies a concrete handling station.
          example: false
        earliestPickTime:
          type: string
          format: date-time
          description: The earliest allowed pick-up time as RFC-3339 timestamp.
          example: "2020-08-06T15:45:00Z"
        latestPickTime:
          type: string
          format: date-time
          description: The latest allowed pick-up time as RFC-3339 timestamp.
          example: "2020-08-06T15:50:00Z"
        earliestDropTime:
          type: string
          format: date-time
          description: The earliest allowed drop-off time as RFC-3339 timestamp.
          example: "2020-08-06T15:50:00Z"
        latestDropTime:
          type: string
          format: date-time
          description: The latest allowed drop-off time as RFC-3339 timestamp.
          example: "2020-08-06T16:05:00Z"
        customAttributes:
          type: object
          additionalProperties:
            type: string
          example:
            customAttributeName1: customAttributeValue1
            customAttributeName2: null
        agvId:
          type: string
          format: uuid
          description: The unique identifier of the executing AGV.
          example: b2d83800-4e44-4818-a252-61c5a90948c9
        externalAgvId:
          type: string
          description: The external (i.e. customer specific) identifier of the executing AGV.
          example: AGV-123

    ArrayOfReadTransportOrders:
      type: array
      items:
        $ref: "#/components/schemas/ReadTransportOrder"

    CreateTransportOrder:
      type: object
      required:
        - orderType
        - pickStation
        - dropStation
      properties:
        externalId:
          type: string
          description: >
            The external unique identifier of the transport order.
            If either blank, left out or only whitespace, SYNA.OS will create a human readable external ID.
          example: Order-123
        externalLoadId:
          type: string
          description: The external unique identifier of the load of the transport order.
          example: Load-123
        priority:
          type: integer
          description: The priority of the transport order. Higher priority is represented by a lower number, so 0 is highest.
          example: 1
        containerType:
          type: string
          description: The type of the container the payload is packed up in.
          example: Container-1234
        orderType:
          type: string
          enum: [ FULL, EMPTY ]
          description: The order type specifies if this a full or empty order. Default is `full`.
          example: FULL
        pickStation:
          type: string
          description: >
            The name of the handling station group or handling station where the load needs to be picked up.
            Must be a valid handling station group or handling station on the map.
          example: HS01
        dropStation:
          type: string
          description: >
            The name of the handling station group or handling station where the load has to be droppped.
            Must be a valid handling station group or handling station on the map.
          example: HS02
        earliestPickTime:
          type: string
          format: date-time
          description: >
            The earliest allowed pick-up time as RFC-3339 timestamp.
            A complete time window has to be supplied (earliest and latest date). Either for drop off
            or for pick up but not both.
          example: "2020-08-06T16:05:00Z"
        latestPickTime:
          type: string
          format: date-time
          description: >
            The latest allowed pick-up time as RFC-3339 timestamp.
            A complete time window has to be supplied (earliest and latest date). Either for drop off
            or for pick up but not both.
          example: "2020-08-06T16:05:00Z"
        earliestDropTime:
          type: string
          format: date-time
          description: >
            The earliest allowed drop-off time as RFC-3339 timestamp.
            A complete time window has to be supplied (earliest and latest date). Either for drop off
            or for pick up but not both.
          example: "2020-08-06T16:05:00Z"
        latestDropTime:
          type: string
          format: date-time
          description: >
            The latest allowed drop-off time as RFC-3339 timestamp.
            A complete time window has to be supplied (earliest and latest date). Either for drop off
            or for pick up but not both.
          example: "2020-08-06T16:05:00Z"
        partNumber:
          type: string
          description: The name of the part that is transported with that transport order.
          example: Part-1234
        customAttributes:
          type: object
          description: A Field for customer specific attributes.
          additionalProperties:
            type: string
          example:
            customAttributeName1: customAttributeValue1
            customAttributeName2: customAttributeValue2

    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri-reference
          enum: [ "https://synaos.com/fpos/problems/undefined-map-point",
                  "https://synaos.com/fpos/problems/invalid-pick-up-or-drop-off-time-window",
                  "https://synaos.com/fpos/problems/incompatible-agv-types",
                  "https://synaos.com/fpos/problems/internal-server-error" ,
                  "https://synaos.com/fpos/problems/invalid-user-input",
                  "https://synaos.com/fpos/problems/unparsable-user-input",
                  "https://synaos.com/fpos/problems/transport-order-already-exists",
                  "https://synaos.com/fpos/problems/invalid-target-update",
                  "https://synaos.com/fpos/problems/invalid-source-update",
                  "https://synaos.com/fpos/problems/invalid-time-window-update",
                  "https://synaos.com/fpos/problems/transport-order-already-finished",
                  "https://synaos.com/fpos/problems/station-has-no-access-node",]
          description: >
            A URI reference that uniquely identifies the problem type only in the
            context of the provided API. Opposed to the specification in RFC-7807,
            it is neither recommended to be dereferenceable and point to a
            human-readable documentation nor globally unique for the problem type.
          example: 'https://synaos.com/fpos/problems/undefined-map-point'
        title:
          type: string
          description: >
            A short summary of the problem type. Written in English and readable
            for engineers, usually not suited for non technical stakeholders and
            not localized.
          example: Service Unavailable
        status:
          type: integer
          format: int32
          description: >
            The HTTP status code generated by the origin server for this occurrence
            of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 503
        detail:
          type: string
          description: >
            A human readable explanation specific to this occurrence of the
            problem that is helpful to locate the problem and give advice on how
            to proceed. Written in English and readable for engineers, usually not
            suited for non technical stakeholders and not localized.
          example: Connection to database timed out
        instance:
          type: string
          format: uri-reference
          description: >
            A URI reference that identifies the specific occurrence of the problem,
            e.g. by adding a fragment identifier or sub-path to the problem type.
            May be used to locate the root of this problem in the source code.
          example: '/problem/connection-error#token-info-read-timed-out'

    Problems:
      type: array
      items:
        $ref: "#/components/schemas/Problem"

  securitySchemes:
    oauthToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: "https://example.com/token"
          scopes:
            FPOS_ADMIN: admin role
            FPOS_USER: user role
            FPOS_EXTERNAL_API: third-party system
