Deutsche Bank Order Details API

openapi: 3.2.0
info:
  title: dbapi-investments-orders Order Details API
  description: 'The Order Service API is a dbAPI platform service that enables developers and customers to create their own investment applications for executing securities orders (stocks, funds, bonds or ETFs) on the German stock exchanges or on the most important foreign stock exchanges.

    The service enables client applications to allow users to create, view, modify or cancel their orders in near real-time in the Deutsche Bank order management system.'
  termsOfService: https://developer.db.com/termsandconditions
  contact:
    url: https://developer.db.com/contact
    email: bank.api@db.com
  version: v1
servers:
- url: https://simulator-api.db.com:443/gw/dbapi/investments/orders/v1
tags:
- name: Order Details
  description: Retrieve details on existing orders
paths:
  /:
    get:
      tags:
      - Order Details
      description: This API returns a list of current orders (also known as order book) for a given account including order details, e.g. status and order id. At least one of parameters 'securityAccountId' or 'externalOrderReference' must be provided.
      operationId: orderBookList
      parameters:
      - name: securityAccountId
        in: query
        description: Securities Account ID
        required: false
        style: form
        explode: true
        schema:
          pattern: '[0-9]{12}'
          type: string
      - name: externalOrderReference
        in: query
        description: Unique external order reference
        required: false
        style: form
        explode: true
        schema:
          maxLength: 16
          type: string
      - name: Correlation-Id
        in: header
        description: Free form key controlled by the caller e.g. uuid
        required: false
        schema:
          maxLength: 50
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderBookResponse'
        '400':
          description: Unsuccessful operation, returns http status 400. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 2
                message: Invalid value for %s.
              - code: 3
                message: 'Invalid value for %s: %s.'
              - code: 17
                message: Invalid OTP.
              - code: 102
                message: Invalid value for parameter externalOrderReference or securityAccountId.
              - code: 111
                message: 2FA method is not ACTIVE.
              - code: 114
                message: Unable to identify transaction by Id.
              - code: 127
                message: Booking date from must precede booking date to.
              - code: 131
                message: Invalid value for 'sortBy'. Valid values are 'bookingDate[ASC]' and 'bookingDate[DESC]'.
              - code: 601
                message: Order deletion/modification not allowed due to order state.
              - code: 602
                message: Multiple positions exist. Please contact your personal bank advisor.
              - code: 603
                message: Insufficient stock
              - code: 604
                message: Security data not found
              - code: 605
                message: Missing authorization
              - code: 606
                message: Quantity not tradeable
              - code: 607
                message: No suitable position found
              - code: 609
                message: Only one price should be provided for the order limit
              - code: 610
                message: 'The order exceeds the maximum available quota: Free quota: {freeQuota}'
              - code: 611
                message: Not enough securities with minimum holding period available
              - code: 613
                message: Ordering quotas of OEREFs (Open-Ended Real Estate Funds) bought after 21.07.2013 and cannot be returned
              - code: 614
                message: Ordering quotas of OEREFs (Open-Ended Real Estate Funds) bought partly after 21.07.2013 and cannot be returned
              - code: 615
                message: Security not tradeable
              - code: 616
                message: Order not in orderbook
              - code: 617
                message: Minimum order amount not reached
              - code: 620
                message: CashAccount does not exist
              - code: 621
                message: Customer is not allowed to order
              - code: 622
                message: Security Account is not valid for orders
              - code: 623
                message: Liquidity not sufficient for order
              - code: 624
                message: MarketPlace does not exist
              - code: 633
                message: SecurityAccount does not exist
              - code: 634
                message: ExpiryDate is before current date
              - code: 635
                message: Invalid blockingDate
              - code: 636
                message: ExpiryDate must be a business day
              - code: 637
                message: Setting a limit when ordering over the capital management company is not possible
              - code: 638
                message: Setting an expiry date when ordering over the capital management company is not possible
              - code: 639
                message: Either WKN or ISIN must be provided
              - code: 640
                message: invalid preview Signature
              - code: 641
                message: preview Signature expired
              - code: 642
                message: preview Signature order parameter mismatch
              - code: 643
                message: Unique external order reference missing
              - code: 654
                message: Invalid limit price/stop price.
              - code: 655
                message: The order is part of a bulk order and cannot be changed.
              - code: 656
                message: addOns.expiryDate not allowed with type of addOns.restriction
              - code: 657
                message: OTC market place not allowed
              - code: 658
                message: Maximum addOns.expiryDate exceeded.
              - code: 659
                message: Token doesn't exist
              - code: 660
                message: No price returned by PriceModule
              - code: 661
                message: BestEx could not be retrieved for holding recommendation
              - code: 662
                message: No data for given wkn found
              - code: 664
                message: Mismatching ccy for the given security
              - code: 665
                message: Security not tradeable with market place
              - code: 666
                message: Best Execution stock market could not be determined
              - code: 667
                message: Portfolio not found
              - code: 668
                message: Security data not found
              - code: 670
                message: Market place ID not provided
              - code: 671
                message: The order cannot be cancelled, it is already executed.
              - code: 673
                message: Investment decider was not provided
              - code: 699
                message: reportToken doesn't exist
              - code: 701
                message: 'validation not successful: consent information is not available, but required.'
              - code: 702
                message: 'validation not successful: consent information cannot be validated completely.'
              - code: 703
                message: The user’s investment decision experience rating needs to be updated. The required steps can be performed within the Online Banking.
        '401':
          description: Unsuccessful operation, returns http status 401. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 401
                message: The requested function requires a SCA Level Authentication.
              - code: 644
                message: Order type is not allowed for user
              - code: 645
                message: User not allowed to use (2FA) session
              - code: 646
                message: Daily order limit exceeded
              - code: 647
                message: 2FA for session renewal required. Limit exceeded
              - code: 648
                message: 2FA for session renewal required. Time exceeded
              - code: 649
                message: 2FA for session renewal required. Transaction count greater than max transaction count
              - code: 650
                message: Business authorisation issue. Cash account not found
              - code: 651
                message: Business authorisation issue. Security account not found
              - code: 652
                message: Business authorisation issue. Partner ID not found
              - code: 653
                message: Business authorisation issue. Client ID setup incorrect
              - code: 672
                message: Investment decider rejected
        '500':
          description: Unsuccessful operation, returns http status 500. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 669
                message: Backend responded with an unexpected SA Key
      security:
      - api_auth_code:
        - order_securities
      summary: Order book list
      x-summary-source: derived
  /{orderId}:
    get:
      tags:
      - Order Details
      description: This API returns details to a previously entered or modified order. The order is identified by its unique order id.
      operationId: orderDetails
      parameters:
      - name: orderId
        in: path
        description: Unique system order identifier
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: securityAccountId
        in: query
        description: Securities Account ID
        required: false
        style: form
        explode: true
        schema:
          pattern: '[0-9]{12}'
          type: string
      - name: Correlation-Id
        in: header
        description: Free form key controlled by the caller e.g. uuid
        required: false
        schema:
          maxLength: 50
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetailResponse'
        '400':
          description: Unsuccessful operation, returns http status 400. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 2
                message: Invalid value for %s.
              - code: 3
                message: 'Invalid value for %s: %s.'
              - code: 17
                message: Invalid OTP.
              - code: 102
                message: Invalid value for parameter externalOrderReference or securityAccountId.
              - code: 111
                message: 2FA method is not ACTIVE.
              - code: 114
                message: Unable to identify transaction by Id.
              - code: 127
                message: Booking date from must precede booking date to.
              - code: 131
                message: Invalid value for 'sortBy'. Valid values are 'bookingDate[ASC]' and 'bookingDate[DESC]'.
              - code: 601
                message: Order deletion/modification not allowed due to order state.
              - code: 602
                message: Multiple positions exist. Please contact your personal bank advisor.
              - code: 603
                message: Insufficient stock
              - code: 604
                message: Security data not found
              - code: 605
                message: Missing authorization
              - code: 606
                message: Quantity not tradeable
              - code: 607
                message: No suitable position found
              - code: 609
                message: Only one price should be provided for the order limit
              - code: 610
                message: 'The order exceeds the maximum available quota: Free quota: {freeQuota}'
              - code: 611
                message: Not enough securities with minimum holding period available
              - code: 613
                message: Ordering quotas of OEREFs (Open-Ended Real Estate Funds) bought after 21.07.2013 and cannot be returned
              - code: 614
                message: Ordering quotas of OEREFs (Open-Ended Real Estate Funds) bought partly after 21.07.2013 and cannot be returned
              - code: 615
                message: Security not tradeable
              - code: 616
                message: Order not in orderbook
              - code: 617
                message: Minimum order amount not reached
              - code: 620
                message: CashAccount does not exist
              - code: 621
                message: Customer is not allowed to order
              - code: 622
                message: Security Account is not valid for orders
              - code: 623
                message: Liquidity not sufficient for order
              - code: 624
                message: MarketPlace does not exist
              - code: 633
                message: SecurityAccount does not exist
              - code: 634
                message: ExpiryDate is before current date
              - code: 635
                message: Invalid blockingDate
              - code: 636
                message: ExpiryDate must be a business day
              - code: 637
                message: Setting a limit when ordering over the capital management company is not possible
              - code: 638
                message: Setting an expiry date when ordering over the capital management company is not possible
              - code: 639
                message: Either WKN or ISIN must be provided
              - code: 640
                message: invalid preview Signature
              - code: 641
                message: preview Signature expired
              - code: 642
                message: preview Signature order parameter mismatch
              - code: 643
                message: Unique external order reference missing
              - code: 654
                message: Invalid limit price/stop price.
              - code: 655
                message: The order is part of a bulk order and cannot be changed.
              - code: 656
                message: addOns.expiryDate not allowed with type of addOns.restriction
              - code: 657
                message: OTC market place not allowed
              - code: 658
                message: Maximum addOns.expiryDate exceeded.
              - code: 659
                message: Token doesn't exist
              - code: 660
                message: No price returned by PriceModule
              - code: 661
                message: BestEx could not be retrieved for holding recommendation
              - code: 662
                message: No data for given wkn found
              - code: 664
                message: Mismatching ccy for the given security
              - code: 665
                message: Security not tradeable with market place
              - code: 666
                message: Best Execution stock market could not be determined
              - code: 667
                message: Portfolio not found
              - code: 668
                message: Security data not found
              - code: 670
                message: Market place ID not provided
              - code: 671
                message: The order cannot be cancelled, it is already executed.
              - code: 673
                message: Investment decider was not provided
              - code: 699
                message: reportToken doesn't exist
              - code: 701
                message: 'validation not successful: consent information is not available, but required.'
              - code: 702
                message: 'validation not successful: consent information cannot be validated completely.'
              - code: 703
                message: The user’s investment decision experience rating needs to be updated. The required steps can be performed within the Online Banking.
        '401':
          description: Unsuccessful operation, returns http status 401. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 401
                message: The requested function requires a SCA Level Authentication.
              - code: 644
                message: Order type is not allowed for user
              - code: 645
                message: User not allowed to use (2FA) session
              - code: 646
                message: Daily order limit exceeded
              - code: 647
                message: 2FA for session renewal required. Limit exceeded
              - code: 648
                message: 2FA for session renewal required. Time exceeded
              - code: 649
                message: 2FA for session renewal required. Transaction count greater than max transaction count
              - code: 650
                message: Business authorisation issue. Cash account not found
              - code: 651
                message: Business authorisation issue. Security account not found
              - code: 652
                message: Business authorisation issue. Partner ID not found
              - code: 653
                message: Business authorisation issue. Client ID setup incorrect
              - code: 672
                message: Investment decider rejected
        '500':
          description: Unsuccessful operation, returns http status 500. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 669
                message: Backend responded with an unexpected SA Key
      security:
      - api_auth_code:
        - order_securities
      summary: Order details
      x-summary-source: derived
components:
  schemas:
    Xd020a:
      pattern: '[A-Z0-9]{3}'
      type: string
      description: XD020A value of market place
    SecurityAccountId:
      pattern: '[0-9]{12}'
      type: string
      description: Security Account ID
    OrderLimit:
      type: object
      properties:
        limitPrice:
          type: number
          description: The lowest price (for a buy) or highest price (for a sell) in trading currency at which an order execution should be triggered
          format: double
          exclusiveMinimum: 0
        stopPrice:
          type: number
          description: 'Stop-Buy price (for a buy), Stop-Loss price (for a sell) in trading currency '
          format: double
          exclusiveMinimum: 0
      description: 'You can protect your order by setting a limit or stop price. Default: At best'
    ISIN:
      pattern: '[A-Z]{2}[0-9A-Z]{9}[0-9]'
      type: string
      description: International Securities Identification Number
      example: DE0007100000
    SecurityId:
      type: object
      properties:
        isin:
          $ref: '#/components/schemas/ISIN'
        wkn:
          $ref: '#/components/schemas/WKN'
      description: The related security id
    CashAccount:
      required:
      - currency
      - id
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        id:
          pattern: '[0-9]{12}'
          type: string
      description: The account used for settling an order transaction execution. <br/>The default account will be used if not specified in the order placement request
    SecurityOrder:
      type: object
      properties:
        orderIds:
          $ref: '#/components/schemas/SecurityOrderIds'
        orderParameter:
          $ref: '#/components/schemas/SecurityOrderParameter'
        orderStatus:
          type: array
          items:
            $ref: '#/components/schemas/SecurityOrderStatus'
      description: The security order including parameter, ids and status
    SecurityOrderIds:
      type: object
      properties:
        externalOrderReference:
          maxLength: 16
          type: string
          description: External order reference
        orderId:
          type: string
          description: Unique system order identifier
        bulkOrderId:
          type: string
          description: Bulk order identifier
      description: The security order identifiers
    OrderDetailResponse:
      required:
      - order
      type: object
      properties:
        order:
          $ref: '#/components/schemas/SecurityOrder'
      description: A summary of the order for the order execution
    SecurityOrderMessage:
      type: object
      properties:
        text_de:
          type: string
          description: status message in German
        text_en:
          type: string
          description: status message in English
        code:
          type: string
          description: The response code
        category:
          type: string
          description: Reason category
          enum:
          - INFO
          - WARN
          - ERROR
    CurrencyCode:
      pattern: '[A-Z]{3}'
      type: string
      description: ISO 4217 Alpha 3 currency code.
      example: EUR
    SecurityOrderStatus:
      required:
      - status
      - timeStamp
      type: object
      properties:
        executionTradingTimeStamp:
          type: string
          description: Captures the timestamp when an order was executed on the market place in ISO 8601 format full-date 'T' full-time without offsets
          format: date-time
          example: '2018-12-10T13:45:12Z'
        message:
          $ref: '#/components/schemas/SecurityOrderMessage'
        quantity:
          type: number
          description: The quantity of the partial execution
          format: double
          exclusiveMinimum: 0
        requestedStatus:
          type: string
          description: Specifies the status of an order modification
          enum:
          - LIMIT_CHANGE_REQUESTED
          - LIMIT_CHANGE_DECLINED
          - CANCELLATION_REQUESTED
          - CANCELLATION_DECLINED
          - VALIDITY_CHANGE_REQUESTED
          - VALIDITY_CHANGE_DECLINED
        securityRate:
          $ref: '#/components/schemas/SecurityRate_1'
        sequence:
          type: integer
          description: Determines the position in the order status history
          format: int64
          example: 1
        status:
          type: string
          description: Specifies the status of an order
          enum:
          - ACCEPTED
          - DELETED
          - PLACED
          - REJECTED
          - APPROVAL_PENDING
          - EXECUTED
          - PARTIALLY_EXECUTED
          - EXPIRED
          - INVOICED
          - DELETED_AFTER_PARTIALLY_EXECUTED
          - EXPIRED_AFTER_PARTIALLY_EXECUTED
          - AUTH_PENDING
          - AUTH_EXPIRED
          - AUTH_REJECTED
          - IDP_ERROR
          - PROCESSING_ERROR
        timeStamp:
          type: string
          description: Captures the timestamp of the order status change in ISO 8601 format full-date 'T' full-time without offsets
          format: date-time
          example: '2018-12-10T13:45:12Z'
        valueDate:
          type: string
          description: Value date of the transaction delivered after execution or fixed price orders. Date in ISO 8601 format YYYY-MM-DD
          format: date
      description: The security order status
    SecurityRate_1:
      required:
      - currency
      - rate
      type: object
      properties:
        rate:
          type: number
          description: The rate of the security in the respective currency on the respective date
          format: double
          example: 56.14
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        unitPer:
          type: number
          description: Unit/percentage quotation of the security
          format: double
          example: 1.0
        date:
          type: string
          description: The date of the security rate in ISO 8601 format YYYY-MM-DD
          format: date
          example: '1970-10-20'
    WKN:
      pattern: '[A-Z0-9]{6}'
      type: string
      description: German securities identification code (Wertpapierkennnumer)
      example: '710000'
    SecurityOrderParameter:
      required:
      - activityType
      - securityAccountId
      - securityId
      type: object
      properties:
        activityType:
          $ref: '#/components/schemas/OrderActivityType'
        addOns:
          $ref: '#/components/schemas/AddOns'
        cashAmount:
          type: number
          description: The amount to order securities for. Supported for wealth management use cases only - here either cashAmount or quantity must be supplied.
          format: double
          exclusiveMinimum: 0
        cashAccount:
          $ref: '#/components/schemas/CashAccount'
        comment:
          type: string
          description: Comment on the further processing of an order
        investmentDecider:
          type: string
          description: Identifier of the investment decision maker
        marketPlaceId:
          $ref: '#/components/schemas/MarketPlaceId'
        orderLimit:
          $ref: '#/components/schemas/OrderLimit'
        quantity:
          type: number
          description: The number of securities to order. For retail uses cases quantity must be supplied, can't use cashAmount. For wealth management use cases either cashAmount or quantity must be supplied.
          format: double
          exclusiveMinimum: 0
        securityAccountId:
          $ref: '#/components/schemas/SecurityAccountId'
        securityId:
          $ref: '#/components/schemas/SecurityId'
        tradeCurrency:
          $ref: '#/components/schemas/CurrencyCode'
      description: All parameters relevant for a security order
    ErrorResponse:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: integer
          description: The error code
        message:
          type: string
          description: Description of the belonging error code.
        messageId:
          type: string
          description: dbAPI internal message-id (unique identifier) that allow reference to each of your API calls.
      description: Default error response message
    AddOns:
      required:
      - restriction
      type: object
      properties:
        expiryDate:
          type: string
          description: The expiry date defines how long the order will be valid and get executed in ISO 8601 format YYYY-MM-DD
          format: date
        restriction:
          type: string
          description: Use Order restrictions to define a specific price quote (default=good till date), if required. Please be aware of potential dependencies of the defined order type
          enum:
          - GOOD_TILL_DATE
          - GOOD_TILL_CANCEL
          - FILL_OR_KILL
          - IMMEDIATE_OR_CANCEL
          - FIRST_RATE
          - SPOT_RATE
          - CLOSING_RATE
      description: Order Add-Ons
    OrderBookResponse:
      required:
      - orders
      - totalItems
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/SecurityOrder'
        totalItems:
          type: number
          format: integer
      description: Response representation for an order list request
    OrderActivityType:
      type: string
      description: SELL - an order to sell <br/> BUY - an order to buy
      enum:
      - SELL
      - BUY
    MarketPlaceId:
      required:
      - xd020a
      type: object
      properties:
        xd020a:
          $ref: '#/components/schemas/Xd020a'
      description: You can leave the execution of the order to Deutsche Bank - in accordance with its execution principles (Best Execution)- or choose between various stock exchanges and fund companies. Depending on your selection, you can make further settings. Please note that the trading partners (exchange or fund company) charge different fees for trading.
  securitySchemes:
    api_auth_code:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://simulator-api.db.com:443/gw/oidc/oauth2/authorize
          tokenUrl: https://simulator-api.db.com:443/gw/oidc/oauth2/token
          scopes:
            offline_access: Request an OAuth2 Refresh Token
            openid: Request access to OpenId Connect functionality
            order_securities: Order Securities
x-original-swagger-version: '2.0'