openapi: 3.0.2
info:
  title: Interhyp Submission commands documents API
  version: 2.0.0
  contact:
    name: Interhyp AG (Team Provider Excellence)
    email: support_submission_api@interhyp.de
  license:
    name: Interhyp AG
  description: '### This document describes the RESTful API and resources provided by Interhyp AG.<p> The RESTful API provides access to resources associated to submission process via *URI* paths, a client application will make an HTTP request using standard HTTP methods like *GET, PUT, POST and DELETE* and parse the response in *JSON* format.<p>

    ### API Audience<p> The API is intended to be consumed by clients who want to integrate Interhyp submission process in their own workflow.

    + **Bank Partners**

    ### API design Principles <p> During API design a set of principles were taken into consideration.

    + **API First**

    + **Mobile First**

    ### API client <p> As an API client you should adhere to the following robustness principle

    + **Tolerant Reader** Be tolerant with unknown fields in the payload. This is required to avoid new API versions if new fields were added, i.e. ignore new fields but do not eliminate them from payload if needed for subsequent *PUT* requests

    + Be prepared to handle HTTP status codes not explicitly specified in endpoint definitions.'
servers:
- url: https://api-test.interhyp.de/submission
  description: Test-Staging
- url: https://api.interhyp.de/submission
  description: Production
security:
- BearerAuth: []
tags:
- name: documents
  description: access to submission documents
paths:
  /v2/submissions/{submissionId}/documents/metadata:
    get:
      deprecated: true
      tags:
      - documents
      summary: Delievers all submission relevant documents metadata
      operationId: getDocumentsMetadata
      description: Retrieve all submission relevant documents in the requested format. <p>
      parameters:
      - $ref: '#/components/parameters/submission-id'
      - $ref: '#/components/parameters/startDate'
      - $ref: '#/components/parameters/embed'
      responses:
        '200':
          description: Submission documents matching provided criteria in the requested format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Documents'
        '202':
          description: Documents metadata are being prepared, try again later, please refer to Retry-After Header
          headers:
            Retry-After:
              schema:
                type: integer
              description: metadata is expected to be ready after the specified amout of seconds
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Error indicates that a requested submission resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnexpectedError'
  /v2/submissions/{submissionId}/documents/{documentId}/binaries:
    get:
      deprecated: true
      tags:
      - documents
      summary: Delievers specific submission document in `pdf` format
      operationId: getDocumentBinary
      description: 'Retrieve specific submission document based on an identifier in `pdf` format<p /> Note: retries following a 202 *must* provide the If-Match header.'
      parameters:
      - in: header
        name: If-Match
        schema:
          type: string
          format: etag
        required: false
      - $ref: '#/components/parameters/submission-id'
      - $ref: '#/components/parameters/document-id'
      responses:
        '200':
          description: Requested submission document is returned
          content:
            application/pdf:
              schema:
                $ref: '#/components/schemas/Binary'
        '202':
          description: Payload is being prepared, try again later
          headers:
            ETag:
              schema:
                type: string
                format: etag
              description: unique ID of payload creation request; use as If-Match in subsequent calls to retrieve payload
            Retry-After:
              schema:
                type: integer
              description: payload is expected to be ready after the specified amout of seconds
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Error indicates that a requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '409':
          description: Error indicates the document has a stale state. Maybe the document was modified or deleted. Please refresh the documents metadata of the submission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnexpectedError'
components:
  schemas:
    DocumentCategory:
      type: object
      properties:
        name:
          type: string
          example: KONTOAUSZUG
        tags:
          type: array
          items:
            $ref: '#/components/schemas/DocumentCategoryTag'
    NotFound:
      allOf:
      - $ref: '#/components/schemas/ClientError'
    DocumentValidity:
      type: object
      required:
      - value
      - resolution
      properties:
        resolution:
          type: string
          description: open ended enum contains type of resolutions, possible values are (MONTH, YEAR)
          example: MONTH
          x-extensible-enum:
          - MONTH
          - YEAR
      discriminator:
        propertyName: resolution
        mapping:
          MONTH: '#/components/schemas/MonthlyResolution'
          YEAR: '#/components/schemas/YearlyResolution'
    UnexpectedError:
      required:
      - status
      - message
      - timestamp
      - path
      - traceId
      properties:
        timestamp:
          type: string
          format: date-time
        status:
          type: integer
          format: int32
        error:
          type: string
        path:
          type: string
        traceId:
          type: string
        errorCode:
          type: integer
          format: int32
    Documents:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DocumentItem'
    ClientError:
      type: object
      required:
      - rootCause
      allOf:
      - $ref: '#/components/schemas/UnexpectedError'
      - properties:
          message:
            type: string
          exception:
            type: string
    DocumentItem:
      type: object
      required:
      - id
      - content
      - category
      properties:
        id:
          type: string
        content:
          $ref: '#/components/schemas/ResourceRef'
        category:
          $ref: '#/components/schemas/DocumentCategory'
        reference:
          type: string
          description: holds information about who/what this document category references
          example: Mustermann, Max
        validity:
          $ref: '#/components/schemas/DocumentValidity'
    BadRequest:
      allOf:
      - $ref: '#/components/schemas/ClientError'
    ResourceRef:
      required:
      - href
      properties:
        href:
          type: string
          description: Link to retrieve a specific resource
          example: http://some-domain/some/link/to/somewhere
    Conflict:
      allOf:
      - $ref: '#/components/schemas/ClientError'
    Unauthorized:
      allOf:
      - $ref: '#/components/schemas/ClientError'
    Binary:
      type: string
      format: binary
    DocumentCategoryTag:
      type: object
      properties:
        name:
          type: string
          example: MIETAUSGANG
  parameters:
    document-id:
      name: documentId
      in: path
      required: true
      schema:
        type: string
      description: Id for the requested submission document.
    submission-id:
      name: submissionId
      in: path
      required: true
      schema:
        type: string
      description: Id for the requested submission.
    embed:
      name: embed
      in: query
      style: form
      required: false
      schema:
        type: boolean
      description: Flag to expand or embed sub-resources in the response resource.<br> By default is set to `FALSE` where only a **ref** to the sub-resources will be returned.<br> By set it to `TRUE` the sub-resources content will be embedded in the response which might affect the payload size
    startDate:
      name: startDate
      in: query
      description: A UTC date-time value that points to the start of the range of time-based data. <br> Defined by date-time - [RFC3339](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14).
      required: true
      schema:
        type: string
        format: date-time
        example: 2019-12-29 10:22:50+00:00
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT