OrderNotification.yaml

openapi: 3.0.0
info:
  version: 2.2.1
  title: OpenWealth Order Placement Event Notification API - TPP Endpoint
  description: API for Receiving Event Notification for OpenWealth APIs.
  contact:
    email: openwealth@synpulse.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - description: Your server url
    url: https://www.openwealth.ch

externalDocs:
  description: Find out more about OpenWealth API specifications.
  url: https://openwealth.ch

tags:
  - name: event-notification
    description: Order event notifications.

security: []

paths:
  /event-notifications:
    post:
      tags:
        - event-notification
      summary: Push notification towards TPP
      description: Push notficiations for subscribed event notifications.
      operationId: postEventNotification
      parameters:
        - $ref: '#/components/parameters/correlation_in_header'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/notificationOrderPlacement'
      responses:
        '202':
          description: Notification accepted.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
components:
  parameters:
    correlation_in_header:
      in: header
      name: X-Correlation-ID
      required: true
      schema:
        type: string
      description: Unique ID (defined by the caller) which will be reflected back in the response.
  schemas:
    eventSubscriptionId:
      description: Unique identification as assigned by the API exposing party to uniquely identify the callback URL resource.
      type: string
      minLength: 1
      maxLength: 40
      example: 3v3n7subscr1p70n
    version:
      description: Indicates to which version of the respective API the notification is belonging to.
      type: string
      enum:
        - v1
        - v2
        - v3
      example: v2
    eventType:
      description: Event type the subscription should apply to AND reason why a notification is sent.
      type: string
      enum:
        - heartbeat
        - order:doneForDay
        - order:orderStatusUpdated
        - order:pendingReplace
        - order:replaced
        - order:restated
        - order:suspended
        - order:trade
        - order:tradeCancel
        - order:tradeCorrect
      example: order:orderStatusUpdated
    dateTime:
      title: DateTime
      type: string
      format: date-time
      example: 2018-04-13T16:00+01:00
    notificationId:
      description: Identification of the notification.
      type: string
      example: 120066c9-58a1-432b-aa60-712fae7f143e
    orderStatus:
      type: string
      description: Shows in which stage of its life cycle an order is.
      enum:
        - acknowledged
        - accepted
        - customerRelease
        - placed
        - partiallyFilled
        - filled
        - executed
        - cancelled
        - partiallyCancelled
        - marketCancelled
        - pendingCancel
        - rejected
        - partiallyRejected
        - marketRejected
        - expired
        - partiallyExpired
        - marketExpired
      example: partiallyFilled
    executedQuantity:
      type: string
      pattern: '^[0-9]{1,12}([.][0-9]{1,9})?$'
      maxLength: 22
      description: Total quantity (e.g. number of shares) filled.
      example: '100'
    averagePrice:
      type: string
      pattern: '^[0-9]{1,12}([.][0-9]{1,9})?$'
      maxLength: 22
      description: Calculated average price of all fills on this order.
      example: '17.8'
    remainingQuantity:
      type: string
      pattern: '^[0-9]{1,12}([.][0-9]{1,9})?$'
      maxLength: 22
      description: >
        Quantity open for further execution.
        If the status is cancelled, expired, or rejected (in which case the order is no longer active) then remainingQuantity could be 0,
        otherwise remainingQuantity = orderQuantity - executedQuantity.
      example: '20'
    dayExecutedQuantity:
      type: string
      pattern: '^[0-9]{1,12}([.][0-9]{1,9})?$'
      maxLength: 22
      description: Quantity on an order that has traded today.
      example: '5'
    dayAveragePrice:
      type: string
      pattern: '^[0-9]{1,12}([.][0-9]{1,9})?$'
      maxLength: 22
      description: Calculated average price of all fills on this order.
      example: '17.8'
    lastQuantity:
      type: string
      pattern: '^[0-9]{1,12}([.][0-9]{1,9})?$'
      maxLength: 22
      description: Quantity (e.g. shares) bought/sold on this (last) fill.
      example: '30'
    lastPrice:
      type: string
      pattern: '^[0-9]{1,12}([.][0-9]{1,9})?$'
      maxLength: 22
      description: Price of this (last) fill.
      example: '17.8'
    notificationOrderPlacement:
      description: Notification for the order placement API that is pushed to the TPP.
      type: object
      properties:
        eventSubscriptionId:
          $ref: '#/components/schemas/eventSubscriptionId'
        version:
          $ref: '#/components/schemas/version'
        eventType:
          $ref: '#/components/schemas/eventType'
        resourceLink:
          description: Link to resource that triggered the event notification.
          type: string
          example: /api/openwealth/order-placement/v2/orders/abcd1234
        created:
          description: Timestamp - Date and time including timezone on which the notification has been created, according to ISO8601
          $ref: '#/components/schemas/dateTime'
        id:
          description: Identification (UUID) of this notification.
          $ref: '#/components/schemas/notificationId'
        predecessorId:
          description: Identification (UUID) of the notification that predeceeds this notification.
          $ref: '#/components/schemas/notificationId'
        orderStatus:
          description: Status of the requested resource notification.
          $ref: '#/components/schemas/orderStatus'
        executedQuantity:
          description: Total quantity (e.g. number of shares) filled.
          $ref: '#/components/schemas/executedQuantity'
        averagePrice:
          description: Calculated average price of all fills on this order.
          $ref: '#/components/schemas/averagePrice'
        remainingQuantity:
          description: >
            Quantity open for further execution.
            If the status is cancelled, expired, or rejected (in which case the order is no longer active) then remainingQuantity could be 0,
            otherwise remainingQuantity = orderQuantity - executedQuantity.
          $ref: '#/components/schemas/remainingQuantity'
        dayExecutedQuantity:
          description: Quantity on an order that has traded today.
          $ref: '#/components/schemas/dayExecutedQuantity'
        dayAveragePrice:
          description: The average price for quantity that has traded today.
          $ref: '#/components/schemas/dayAveragePrice'
        lastQuantity:
          description: Quantity (e.g. shares) bought/sold on this (last) fill.
          $ref: '#/components/schemas/lastQuantity'
        lastPrice:
          description: Price of this (last) fill.
          $ref: '#/components/schemas/lastPrice'
    commonErrorType:
      title: Common Error Type
      description: Error Types for CommonErrorResponse.
      type: string
      enum:
        - /problems/INVALID_PAYLOAD
        - /problems/MALFORMED_PAYLOAD
        - /problems/INVALID_TOKEN
        - /problems/EXPIRED_TOKEN
        - /problems/INSUFFICIENT_PRIVILEGES
        - /problems/NO_ACCESS_TO_RESOURCE
        - /problems/RESOURCE_DOES_NOT_EXIST
        - /problems/RESOURCE_NOT_READY
        - /problems/RESOURCE_TOO_LARGE
        - /problems/WRONG_METHOD
        - /problems/OPERATION_NOT_ALLOWED
        - /problems/TECHNICAL_ERROR
        - /problems/NOT_IMPLEMENTED
        - /problems/SERVICE_UNAVAILABLE
      example: /problems/TECHNICAL_ERROR
    commonErrorResponse:
      title: CommonErrorResponse
      type: object
      properties:
        type:
          $ref: '#/components/schemas/commonErrorType'
        title:
          type: string
          example: This is the general problem description
        detail:
          type: string
          example: Detailed problem description with respect to the current request
        instance:
          type: string
          example: path/to/corresponding/resource
  headers:
    X-Correlation-ID:
      description: Client defined ID from request to correlates HTTP requests between a client and server.
      schema:
        type: string
        example: f058ebd6-02f7-4d3f-942e-904344e8cde5
  responses:
    '400':
      headers:
        Content-Type:
          schema:
            type: string
            description: application/problem+json; charset=utf-8 according to RFC7807
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: Response language - always en
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: >
        Bad Request - The server cannot or will not process the request due to something that is perceived to be a client error as malformed request
        syntax.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    '500':
      headers:
        Content-Type:
          schema:
            type: string
            description: application/problem+json; charset=utf-8 according to RFC7807
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: Response language - always en
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'