openapi: 3.0.0
info:
  description: >
    This is the specification of the bLink 'order-placement' module API. (as
    implemented by service users who offer a notification endpoint to providers
    and as used by SIX) 

    This API is used to place orders and check on the order status.
  version: 2.2.1.6-nr
  title: bLink API - order placement module
  contact:
    name: SIX BBS AG
    url: https://www.six-group.com/en/products-services/banking-services/blink.html
servers:
  - url: https://api.six-group.com/api/bankingservices/b-link/order-placement/v2
  - url: >-
      https://api.six-group.com/api/bankingservices/b-link-consent-2/order-placement/v2
tags:
  - name: event-notification-webhook
    description: Event notification webhook operations.
paths:
  /event-notifications:
    parameters:
      - $ref: '#/components/parameters/api_version_in_header'
      - $ref: '#/components/parameters/event_type_in_header'
      - $ref: '#/components/parameters/event_id_in_header'
      - $ref: '#/components/parameters/event_created_at_in_header'
      - $ref: '#/components/parameters/event_subscription_id_in_header'
      - $ref: '#/components/parameters/correlation_in_header'
      - $ref: '#/components/parameters/agent_in_header'
      - $ref: '#/components/parameters/clientid_in_header'
      - $ref: '#/components/parameters/optional_targetid_in_header'
      - $ref: '#/components/parameters/optional_psu_ip_in_header'
      - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
    post:
      summary: Push notification towards TPP
      description: Push notifications for subscribed event notifications.
      operationId: postEventNotification
      tags:
        - event-notification-webhook
      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/standard400'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '429':
          $ref: '#/components/responses/standard429'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '502':
          $ref: '#/components/responses/standard502'
        '503':
          $ref: '#/components/responses/standard503'
        '504':
          $ref: '#/components/responses/standard504'
components:
  parameters:
    optional_psu_ip_in_header:
      name: X-PSU-IP-Address
      in: header
      description: >-
        IP address of the user initiating the operation (SCOPE: FI /
        NOTIFICATION_RECIPIENT - optional)
      required: false
      schema:
        type: string
    optional_psu_user_agent_in_header:
      name: X-PSU-User-Agent
      in: header
      description: >-
        User of the client software (SCOPE: FI / NOTIFICATION_RECIPIENT -
        optional)
      required: false
      schema:
        type: string
    correlation_in_header:
      name: X-Correlation-ID
      in: header
      description: >-
        Unique ID (defined by the caller) which will be reflected back in the
        response.
      required: true
      schema:
        type: string
        maxLength: 64
    agent_in_header:
      name: User-Agent
      in: header
      description: Name and version of the of the Client software
      required: true
      schema:
        type: string
    api_version_in_header:
      name: X-CorApi-API-Version
      in: header
      description: The API Version
      example: 1.0.0
      required: true
      schema:
        type: string
    event_type_in_header:
      name: X-CorApi-Event-Type
      in: header
      description: The Event-Type
      example: order:trade
      required: true
      schema:
        type: string
    event_id_in_header:
      name: X-CorApi-Event-ID
      in: header
      description: The Event-ID
      example: 7c5f40fc-1b29-4263-a2dd-e127a22a947f
      required: true
      schema:
        type: string
    event_created_at_in_header:
      name: X-CorApi-Event-Created-At
      in: header
      description: The Event-Created Date
      example: '2024-05-28T13:44:53Z'
      required: true
      schema:
        type: string
        format: date-time
    event_subscription_id_in_header:
      name: X-CorApi-Event-Subscription-ID
      in: header
      description: The ID of the Subscription the event was created for
      example: 7c5f40fc-1b29-4263-a2dd-e127a22a947f
      required: true
      schema:
        type: string
    optional_targetid_in_header:
      name: X-CorAPI-Target-ID
      in: header
      description: >-
        ID of the target, e.g., a financial institution. (SCOPE: FI /
        NOTIFICATION_RECIPIENT - optional)
      required: false
      schema:
        type: string
    clientid_in_header:
      name: X-CorAPI-Client-ID
      in: header
      description: >-
        ID of the client forwarded to the target. (SCOPE: FI /
        NOTIFICATION_RECIPIENT)
      required: true
      schema:
        type: string
  headers:
    X-Correlation-ID:
      description: >-
        Client defined ID from request to correlates HTTP requests between a
        client and server.
      schema:
        type: string
        maxLength: 64
        example: f058ebd6-02f7-4d3f-942e-904344e8cde5
    Content-Language:
      schema:
        type: string
        description: Response language - always en
        example: en
  schemas:
    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'
    dateTime:
      title: DateTime
      type: string
      format: date-time
      example: '2018-04-13T16:00:00+01:00'
    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'
    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'
    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
    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
    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'
    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
    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'
    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:
          $ref: '#/components/schemas/dateTime'
        id:
          $ref: '#/components/schemas/notificationId'
        predecessorId:
          $ref: '#/components/schemas/notificationId'
        orderStatus:
          $ref: '#/components/schemas/orderStatus'
        executedQuantity:
          $ref: '#/components/schemas/executedQuantity'
        averagePrice:
          $ref: '#/components/schemas/averagePrice'
        remainingQuantity:
          $ref: '#/components/schemas/remainingQuantity'
        dayExecutedQuantity:
          $ref: '#/components/schemas/dayExecutedQuantity'
        dayAveragePrice:
          $ref: '#/components/schemas/dayAveragePrice'
        lastQuantity:
          $ref: '#/components/schemas/lastQuantity'
        lastPrice:
          $ref: '#/components/schemas/lastPrice'
    lastPrice:
      type: string
      pattern: ^[0-9]{1,12}([.][0-9]{1,9})?$
      maxLength: 22
      description: Price of this (last) fill.
      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'
    notificationId:
      description: Identification of the notification.
      type: string
      example: 120066c9-58a1-432b-aa60-712fae7f143e
    version:
      description: >-
        Indicates to which version of the respective API the notification is
        belonging to.
      type: string
      enum:
        - v1
        - v2
        - v3
      example: v2
    commonErrorResponse:
      title: Common Error Response
      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
    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
  responses:
    standard400:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      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'
    standard404:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: >-
        Not Found - The origin server did not find a current representation for
        the target resource or is not willing to disclose that one exists.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    standard405:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: >-
        Method Not Allowed - The method received in the request-line is known by
        the origin server but not supported by the target resource.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    standard429:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: >-
        Too many requests - The user has sent too many requests in a given
        amount of time.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    standard500:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      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'
    standard501:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: >-
        Not Implemented - The server does not support the functionality required
        to fulfill the request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    standard502:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: >-
        Bad Gateway - The server received an invalid response from the upstream
        server.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    standard503:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: >-
        Service Unavailable - The server is currently unable to handle the
        request due to a temporary overload or scheduled maintenance.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    standard504:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: >-
        Gateway Timeout - The server did not get a response in time that it
        needed in order to complete the request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
