openapi: 3.0.0
info:
  title: Open Banking Reach
  version: "3.2.0"
  description: |
    The Reach Directory is used to get the a list of ASPSP's which can be reached for a specific Service.
    
    **Sandbox**
    The following authorization token can be used to test in the sandbox (unlike a real token this one doesn't expire): 97fb13a74c712d8c7a50476e71769eaf 
  x-tpp-buildversion: '1.27'
servers:
  - url: https://xs2a.awltest.de/xs2a/routingservice/services/directory/v3
    description: Sandbox

paths:
  /aspsps:
    get:
      security:
        - Authorization: []
      tags:
      - Reach Directory
      summary: Get list of ASPSPs reachable with our Open Banking Services
      operationId: reach
      parameters:
      - $ref: '#/components/parameters/country'
      - $ref: '#/components/parameters/allDetails'
      - $ref: '#/components/parameters/allOptions'
      - $ref: '#/components/parameters/categoryLabel'
      - $ref: '#/components/parameters/X-Request-ID'
      - $ref: '#/components/parameters/MessageCreateDateTime'
      - $ref: '#/components/parameters/Service'
      - $ref: '#/components/parameters/allAspspSpecificFields'
      responses:
        200:
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReachDirectoryResponse'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            MessageCreateDateTime:
              $ref: '#/components/headers/MessageCreateDateTime'
        400:
          description: |
            Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            MessageCreateDateTime:
              $ref: '#/components/headers/MessageCreateDateTime'
        401:
          description: |
            Missing or wrong IP Token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            MessageCreateDateTime:
              $ref: '#/components/headers/MessageCreateDateTime'
        403:
          description: |
            Expired IP Token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            MessageCreateDateTime:
              $ref: '#/components/headers/MessageCreateDateTime'
        404:
          description: |
            No ASPSP found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            MessageCreateDateTime:
              $ref: '#/components/headers/MessageCreateDateTime'
        500:
          description: |
            Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            MessageCreateDateTime:
              $ref: '#/components/headers/MessageCreateDateTime'
              
components:
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      
  schemas:
    ASPSP:
      required:
      - AspspId
      - Name
      type: object
      properties:
        AspspId:
          maxLength: 35
          minLength: 1
          type: string
          description: Id of the ASPSP used within the Open Banking Service, to be used in other API’s to identify the ASPSP
        Name:
          type: array
          items:
            $ref: '#/components/schemas/NameLabel'
        BIC:
          pattern: '[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}'
          type: string
          description: BIC of the ASPSP
        Country:
          $ref: '#/components/schemas/Country'
        CategoryLabel:
          type: array
          items:
            maxLength: 255
            minLength: 0
            type: string
            description: Labels to identify categories e.g. Retail or Corporate
        Details:
          type: array
          description: This block only shows when query parameter allDetails = true
          items:
            $ref: '#/components/schemas/DetailsType'
        Options:
          type: array
          description: List of directory service options for the given ASPSP
          items:
            $ref: '#/components/schemas/OptionType'
        GroupId:
          type: string
          description: An id referencing a group this ASPSP is part of.
          maxLength: 255
        AspspSpecificLabels:
          type: array
          description: List of Specific Labels for the given ASPSP
          items:
            $ref: '#/components/schemas/AspspSpecificLabel'
    Group:
      required:
        - GroupId
        - Name
      type: object
      properties:
        GroupId:
          type: string
          description: The id of this group
          maxLength: 255
        Name:
          type: array
          items:
            $ref: '#/components/schemas/NameLabel'

    ReachDirectoryResponse:
        type: object
        required:
          - ASPSP
          - Service
          - Groups
        properties:
          Service:
            maxLength: 35
            minLength: 1
            type: string
            description: |
              The name of the service the ASPSPs are listed for.
          ASPSP:
            type: array
            items:
              $ref: '#/components/schemas/ASPSP'
          Groups:
            type: array
            description: A list of ASPSP groups. An ASPSP may belong to one or no group.
            items:
              $ref: '#/components/schemas/Group'
        description: |
          Reach Directory Response
          
    DetailsType:
      required:
      - Api
      type: object
      properties:
        Api:
          type: string
          description: |
            Indicates for which of our Open Banking Service APIs this is applicable.
            The value is composed of the http method and the URL. The star character
            '*' can be used as a wildcard. Below three examples:
            - POST /v3/payments 
            - '*' /v3/payments    - all http methods
            - GET '*'             - all urls called with GET
          example: "POST /v3/payments "
        Fieldname:
          type: string
          description: The name of the field within the API
        Type:
          type: string
          description: |
            **The description of this field differs if it's supplied with or without a FieldName, see the two tables below.**
            | Type             | Description if NOT combined with a FieldName |
            | ---------------- | ------------|
            | UNSUPPORTED      | The mentioned Api is not supported by the ASPSP, the Open Banking Service will throw an error if it’s used.     |
            | SUPPORTED        | The mentioned Api is supported by the ASPSP. This is mentioned for the following Api’s (because they are usually not supported): - POST /psus/{psuId}/Aspsps/{aspspId}/pre-authentication". If the Post is supported the corresponding api methods (GET, PUT, DELETE) are also supported, if defined in the swagger.|
            
            
            | Type             | Description if combined with a FieldName |
            | ---------------- | ------------|
            | UNSUPPORTED      | The mentioned FieldName is ignored if provided to the Open Banking Service, the Open Banking Service will not throw an error     |
            | SUPPORTED        | A subset of the values in the mentioned FieldName is supported. The Value field (which is always supplied with the SUPPORTED Type) will indicate which values are supported. If no value is provided by the Initiating Party the Open Banking Service will use a default value. If an unsupported value is used, the Open Banking Service will throw an error. |
            | MANDATORY        | The mentioned FieldName is mandatory and has to be filled. If supplied, the Value field will indicate which values are supported. If the Value field is not supplied no validation on the field is done by the Open Banking Service. If the mentioned FieldName is not filled by the Initiating Party the Open Banking Service will throw an error. If an unsupported value is used, the Open Banking Service will throw an error.     |
            | FORBIDDEN        | The mentioned FieldName is forbidden. The Open Banking Service will throw an error if the Initiating Party fills this field and the request will not be sent to the ASPSP.     |
            
        Value:
          type: string
          description: |
            Indicates the values which can be filled in the field. This
            field is only filled if the options differ from the options in the swagger
            file.
        ProtocolVersion:
          minLength: 2
          type: string
          description: |
            The ASPSP ProtocolVersion for which this is valid.
        Condition:
          type: string
          description: |
           Contains conditions which describe when this specific detail is applicable. This field uses logical operations as they are commonly used in e.g. Java and Javascript. If a field is given without a value that Operand is true if the field has any value (is not empty).
          maxLength: 255
          
    OptionType:
      type: object
      properties:
        Key1:
          type: string
        Key2:
          type: string
        Value:
          type: string
        Level:
          $ref: '#/components/schemas/OptionLevelType'
        ProtocolVersion:
          type: string
          description: |
            The ASPSP ProtocolVersion for which this is valid.
    OptionLevelType:
      type: string
      description: |
           - INFORMATIONAL: The information can be ignored
           - CRITICAL: The information must be handled otherwise the ASPSP should be ignored.
      enum:
      - INFORMATIONAL
      - CRITICAL
      
    Country:
      type: string
      description: |
        The code of the country regarding ISO 3166-1, Alpha-2 standard

    NameLabel:
      required:
        - Label
        - Language
      type: object
      properties:
        Label:
          type: string
          description: |
            A label describing a name.
        Language:
          type: string
          description: |
            Label internationalization. It specifies the language of the
            label. ISO 639-1
    AspspSpecificLabel:
      type: object
      properties:
        Fieldname:
          type: string
        Label:
          type: array
          items:
            $ref: '#/components/schemas/NameLabel'

    Link:
      required:
      - href
      type: object
      properties:
        href:
          maxLength: 1024
          minLength: 1
          type: string
      
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          pattern: '[0-9]{1,3}'
          type: string
        message:
          maxLength: 140
          minLength: 1
          type: string
        details:
          type: string
        link:
          $ref: '#/components/schemas/Link'
      description: |
        |HTTP Status|Code |Description
        |-----------|-----|---------------------------------------
        |400        |001  |Bad Request
        |           |002  |The message does not comply the schema definition
        |           |102  |The client or merchant is inactive
        |           |101  |The client or merchant is is unknown
        |401        |     |Missing or wrong Initiating Party Token
        |403        |007  |Initiating Party is not authorised
        |           |017  |Initiating Party access token is expired
        |404        |     |No ASPSP found
        |500        |004  |An internal error occurred
        
  headers:
    X-Request-ID:
      required: true
      description: |
        UUID for unique request identification.
      schema:
        type: string
        maxLength: 36
        minLength: 1
      example: abcdef2e-3000-4000-88cc-ae40e3b113d7
    MessageCreateDateTime:
      required: true
      schema:
        type: string
        format: 'date-time'
      description: |
        The message create date time.

        ISO 8601 DateTime.
      example: "2020-09-25T08:15:00.856Z"
      
  parameters:
    X-Request-ID:
      name: X-Request-ID
      in: header
      description: |
        UUID for unique request identification.
      required: true
      schema:
        maxLength: 36
        minLength: 1
        type: string
      example: abcdef2e-3000-4000-88cc-ae40e3b113d7
    MessageCreateDateTime:
      name: MessageCreateDateTime
      in: header
      description: |
        The message create date time.
        ISO 8601 DateTime.
      required: true
      schema:
        type: string
        format: date-time
      example: "2020-09-25T08:15:00.856Z" 
    Service:
      name: Service
      in: header
      description: |
        The name of the service for which the reach will be retrieved. Only AIS or PIS is allowed.
      schema:
        type: string
      required: true
    country:
      name: country
      in: query
      description: |
          List ASPSPs of given country only. ISO 3166-1, Alpha-2 standard
      schema:
        maxLength: 2
        minLength: 2
        type: string
    allDetails:
      name: allDetails
      in: query
      description: |
        When `true` the details block in the response is provided.
      schema:
        type: boolean
        default: false
    allOptions:
      name: allOptions
      in: query
      description: |
        When `true` the options block in the response is provided.
      schema:
        type: boolean
        default: false
    categoryLabel:
      name: categoryLabel
      in: query
      description: |
        Filter request that contains a specified Label
      schema:
        type: string
    allAspspSpecificFields:
      name: allAspspSpecificFields
      in: query
      description: |
        When `true` the AspspSpecificFields block in the response is provided.
      schema:
        type: boolean
        default: false