openapi: 3.0.1
info:
  title: Transport Order Events
  version: "1.2"
servers:
  - url: http://localhost:8100
    description: Generated server url
tags:
  - name: TransportOrderEventSubscription
    description: This API provides REST API endpoints for managing subscriptions to transport order events and also specifies the exchanged event DTOs.
paths:
  /api/v1/transport-order-event-subscriptions:
    get:
      tags:
        - TransportOrderEventSubscription
      summary: Get all transport order event subscriptions
      description: This operation returns a list of all subscriptions.
      operationId: getSubscriptions
      responses:
        200:
          description: The request was successful and the event subscriptions
            are returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReadTransportOrderEventSubscription'
        500:
          description: There was an internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - oauthToken:
            - FPOS_ADMIN
            - FPOS_EXTERNAL_API
    put:
      tags:
        - TransportOrderEventSubscription
      summary: Create a new transport order event subscription or update an existing one. A subscription is identified by the combination of callback URL and event type.
      description: This operation subscribes a callback URL for the given event types. Receivers
        must handle events in an idempotent way.
      operationId: createSubscription
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTransportOrderEventSubscription'
        required: true
      responses:
        201:
          description: The request was successful and a transport order event subscription was created.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReadTransportOrderEventSubscription'
        400:
          description: There was a problem validating the input.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        500:
          description: There was an internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      callbacks:
        Transport order received:
          '{$request.body#/callbackUrl}':
            post:
              summary: A transport order was created
              description: Notifies about a created transport order via the supplied callback URL.
                The event must be handled in an idempotent way.
              operationId: transportOrderReceived
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/ReceivedEvent'
              responses:
                200:
                  description: The Request was successful.
                400:
                  description: There was a client error.
                500:
                  description: There was a server error.
        Transport order started:
          '{$request.body#/callbackUrl}':
            post:
              summary: A transport order was started
              description: Notifies about a started transport order via the supplied callback URL.
                The event must be handled in an idempotent way.
              operationId: transportOrderStarted
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/StartedEvent'
              responses:
                200:
                  description: The Request was successful.
                400:
                  description: There was a client error.
                500:
                  description: There was a server error.
        Transport order picked:
          '{$request.body#/callbackUrl}':
            post:
              summary: A transport order was picked
              description: Notifies about a picked transport order via the supplied callback URL.
                The event must be handled in an idempotent way.
              operationId: transportOrderPicked
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/PickedEvent'
              responses:
                200:
                  description: The Request was successful.
                400:
                  description: There was a client error.
                500:
                  description: There was a server error.
        Transport order finished:
          '{$request.body#/callbackUrl}':
            post:
              summary: A transport order was finished
              description: Notifies about a finished transport order via the supplied callback URL.
                The event must be handled in an idempotent way.
              operationId: transportOrderFinished
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/FinishedEvent'
              responses:
                200:
                  description: The Request was successful.
                400:
                  description: There was a client error.
                500:
                  description: There was a server error.
        Transport order failed:
          '{$request.body#/callbackUrl}':
            post:
              summary: A transport order failed
              description: Notifies about a failed transport order via the supplied callback URL.
                The event must be handled in an idempotent way.
              operationId: transportOrderFailed
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/FailedEvent'
              responses:
                200:
                  description: The Request was successful.
                400:
                  description: There was a client error.
                500:
                  description: There was a server error.
        Transport order execution interrupted:
          '{$request.body#/callbackUrl}':
            post:
              summary: A transport order's execution was created
              description: Notifies about a transport order's execution being interrupted via the supplied callback URL.
                The event must be handled in an idempotent way.
              operationId: transportOrderExecutionInterrupted
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/ExecutionInterruptedEvent'
              responses:
                200:
                  description: The Request was successful.
                400:
                  description: There was a client error.
                500:
                  description: There was a server error.
      security:
        - oauthToken:
            - FPOS_ADMIN
            - FPOS_EXTERNAL_API
  /api/v1/transport-order-event-subscriptions/{subscriptionId}:
    delete:
      tags:
        - TransportOrderEventSubscription
      summary: Delete an existing transport order event subscription
      description: This operation unsubscribes a callback URL.
      operationId: deleteSubscription
      parameters:
        - name: subscriptionId
          in: path
          description: The id of the subscription
          required: true
          schema:
            type: string
            format: uuid
      responses:
        204:
          description: The request was successful and the transport order event subscription was
            deleted.
        404:
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        500:
          description: There was an internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - oauthToken:
            - FPOS_ADMIN
            - FPOS_EXTERNAL_API

components:
  schemas:
    CreateTransportOrderEventSubscription:
      required:
        - callbackUrl
        - types
      type: object
      properties:
        callbackUrl:
          maxLength: 2000
          minLength: 1
          type: string
          description: The callback URL for the subscribed event
          format: url
        types:
          $ref: '#/components/schemas/EventTypes'
        oauth:
          $ref: '#/components/schemas/OAuth'
        bearerToken:
          $ref: '#/components/schemas/Bearer'
        basicAuth:
          $ref: '#/components/schemas/BasicAuth'
      description: A subscription for events
    ReadTransportOrderEventSubscription:
      required:
        - id
        - callbackUrl
        - type
      type: object
      properties:
        id:
          type: string
          description: The id of the subscription
          format: uuid
        callbackUrl:
          maxLength: 2000
          minLength: 1
          type: string
          description: The callback URL for the subscription
          format: url
        type:
          $ref: '#/components/schemas/EventType'
        oauth:
          $ref: '#/components/schemas/OAuth'
        bearerToken:
          $ref: '#/components/schemas/Bearer'
        basicAuth:
          $ref: '#/components/schemas/BasicAuth'
      description: A transport order event subscription
    OAuth:
      type: object
      required:
        - authenticationUrl
      properties:
        authenticationUrl:
          maxLength: 2000
          minLength: 1
          type: string
          description: The authentication URL for sending OAuth requests to.
          format: url
        requestParameters:
          type: object
          description: Key-value pairs to include in the authentication request
          additionalProperties:
            type: string
          example:
            client_id: bob
            client_secret: bananas1234
      description: Optionally you can define that sent out transport order events should include authorization information retrieved via OAuth.
    Bearer:
      type: object
      required:
        - token
      properties:
        token:
          type: string
      description: Optionally you can define that sent out transport order events should include a bearer token.
    BasicAuth:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
          description: Username to use for the basic authentication.
        password:
          type: string
          description: Password to use for the basic authentication
      description: Optionally you can define that sent out transport order events should include basic auth information.
    Problem:
      type: object
      properties:
        type:
          type: string
          description: "A URI reference that identifies the problem type. In contrast\
                \ to RFC7807, it is not meant to be dereferenced."
        title:
          type: string
          description: "A short, human-readable summary of the problem type. It is\
                \ written in english and not localized."
        status:
          maximum: 600
          minimum: 100
          type: integer
          description: The HTTP status code generated by the origin server for this
            occurrence of the problem.
          format: int32
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of
            the problem. It is written in english and not localized.
        instance:
          type: string
          description: "A representation of the problem instance. Might be left blank\
                \ for some problems. In contrast to RFC7807, it is not a URI and not meant\
                \ to be dereferenced."
        extensions:
          type: object
          additionalProperties:
            type: object
            description: Extensions used for internal purposes. Do not rely on these
              being set and/or stable.
          description: Extensions used for internal purposes. Do not rely on these
            being set and/or stable.
          deprecated: true
        translatableExtensions:
          type: object
          additionalProperties:
            type: object
            description: Extensions used for internal purposes. Do not rely on these
              being set and/or stable.
          description: Extensions used for internal purposes. Do not rely on these
            being set and/or stable.
          deprecated: true
      description: Problem details as proposed in https://tools.ietf.org/html/rfc7807
    EventType:
      type: string
      enum:
        - TRANSPORT_ORDER_RECEIVED
        - TRANSPORT_ORDER_STARTED
        - TRANSPORT_ORDER_PICKED
        - TRANSPORT_ORDER_FINISHED
        - TRANSPORT_ORDER_FAILED
        - TRANSPORT_ORDER_EXECUTION_INTERRUPTED
    EventTypes:
      type: array
      items:
        $ref: '#/components/schemas/EventType'
    PickedEvent:
      type: object
      required:
        - eventType
        - transportOrderId
        - externalTransportOrderId
        - agvId
        - externalAgvId
        - eventTime
        - customAttributes
      properties:
        eventType:
          $ref: '#/components/schemas/EventType'
        transportOrderId:
          type: string
          format: uuid
          description: The id of the transport order attached to this pick event.
        externalTransportOrderId:
          type: string
          description: The external id of the transport order attached to this received event.
        agvId:
          type: string
          format: uuid
          description: The internal id of the AGV fulfilling the transport order.
        externalAgvId:
          type: string
          description: The external id of the AGV fulfilling the transport order.
        eventTime:
          type: string
          format: date-time
          description: The time when the the transport order was received.
          example: "2020-08-06T15:50:00Z"
        customAttributes:
          type: object
          additionalProperties:
            type: string
          example:
            customAttributeName1: customAttributeValue1
            customAttributeName2: null
    ReceivedEvent:
      type: object
      required:
        - eventType
        - transportOrderId
        - externalTransportOrderId
        - eventTime
        - customAttributes
      properties:
        eventType:
          $ref: '#/components/schemas/EventType'
        transportOrderId:
          type: string
          format: uuid
          description: The id of the transport order attached to this received event.
        externalTransportOrderId:
          type: string
          description: The external id of the transport order attached to this received event.
        eventTime:
          type: string
          format: date-time
          description: The time when the the transport order was received.
          example: "2020-08-06T15:50:00Z"
        customAttributes:
          type: object
          additionalProperties:
            type: string
          example:
            customAttributeName1: customAttributeValue1
            customAttributeName2: null
    StartedEvent:
      type: object
      required:
        - eventType
        - transportOrderId
        - externalTransportOrderId
        - eventTime
        - agvId
        - externalAgvId
        - customAttributes
      properties:
        eventType:
          $ref: '#/components/schemas/EventType'
        transportOrderId:
          type: string
          format: uuid
          description: The id of the transport order attached to this received event.
        externalTransportOrderId:
          type: string
          description: The external id of the transport order attached to this received event.
        eventTime:
          type: string
          format: date-time
          description: The time when the the transport order was received.
          example: "2020-08-06T15:50:00Z"
        agvId:
          type: string
          format: uuid
          description: The internal id of the AGV fulfilling the transport order.
        externalAgvId:
          type: string
          description: The external id of the AGV fulfilling the transport order.
        customAttributes:
          type: object
          additionalProperties:
            type: string
          example:
            customAttributeName1: customAttributeValue1
            customAttributeName2: null
    FinishedEvent:
      type: object
      required:
        - eventType
        - transportOrderId
        - externalTransportOrderId
        - eventTime
        - dropStationId
        - externalDropStationId
        - customAttributes
      properties:
        eventType:
          $ref: '#/components/schemas/EventType'
        transportOrderId:
          type: string
          format: uuid
          description: The id of the transport order attached to this received event.
        externalTransportOrderId:
          type: string
          description: The external id of the transport order attached to this received event.
        eventTime:
          type: string
          format: date-time
          description: The time when the the transport order was received.
          example: "2020-08-06T15:50:00Z"
        agvId:
          type: string
          format: uuid
          description: The internal id of the AGV that executed the transport order or blank if the order was finished manually.
        externalAgvId:
          type: string
          description: The external id of the AGV that executed the transport order or blank if the order was finished manually.
        dropStationId:
          type: string
          format: uuid
          description: The internal id of the station where the load was dropped.
        externalDropStationId:
          type: string
          description: The external id of the station where the load was dropped.
        customAttributes:
          type: object
          additionalProperties:
            type: string
          example:
            customAttributeName1: customAttributeValue1
            customAttributeName2: null
    FailedEvent:
      type: object
      required:
        - eventType
        - transportOrderId
        - externalTransportOrderId
        - eventTime
        - errorCode
        - errorInfo
        - customAttributes
      properties:
        eventType:
          $ref: '#/components/schemas/EventType'
        transportOrderId:
          type: string
          format: uuid
          description: The id of the transport order attached to this received event.
        externalTransportOrderId:
          type: string
          description: The external id of the transport order attached to this received event.
        eventTime:
          type: string
          format: date-time
          description: The time when the the transport order was received.
          example: "2020-08-06T15:50:00Z"
        errorCode:
          type: string
          enum: [ NO_ROUTE, INVALID_PICK_UP_OR_DROP_OFF_TIME_WINDOW, UNDEFINED_NODE_FOR_MAP_POINT, INCOMPATIBLE_AGV_TYPES, UNKNOWN, SHOP_FLOOR_MODEL_MIGRATION_FAILED ]
          description: The code that indicates why the transport order failed.
        errorInfo:
          type: string
          description: More details about why the transport order failed.
        customAttributes:
          type: object
          additionalProperties:
            type: string
          example:
            customAttributeName1: customAttributeValue1
            customAttributeName2: null
    ExecutionInterruptedEvent:
      type: object
      required:
        - eventType
        - transportOrderId
        - externalTransportOrderId
        - agvId
        - externalAgvId
        - eventTime
        - interruptionReason
        - customAttributes
      properties:
        eventType:
          $ref: '#/components/schemas/EventType'
        transportOrderId:
          type: string
          format: uuid
          description: The id of the transport order attached to this received event.
        externalTransportOrderId:
          type: string
          description: The external id of the transport order attached to this received event.
        eventTime:
          type: string
          format: date-time
          description: The time when the the transport order was received.
          example: "2020-08-06T15:50:00Z"
        agvId:
          type: string
          format: uuid
          description: The internal id of the AGV fulfilling the transport order.
        externalAgvId:
          type: string
          description: The external id of the AGV fulfilling the transport order.
        interruptionReason:
          type: string
          enum: [ NO_DROP_STATION_AVAILABLE, TARGET_IS_HSG_AND_AUTOMATIC_HS_SELECTION_NOT_ALLOWED ]
          description: Reason why the execution of the order has been interrupted.
        customAttributes:
          type: object
          additionalProperties:
            type: string
          example:
            customAttributeName1: customAttributeValue1
            customAttributeName2: null

  securitySchemes:
    oauthToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: "https://example.com/token"
          scopes:
            FPOS_ADMIN: admin role
            FPOS_EXTERNAL_API: api role