Interhyp Commands API

openapi: 3.2.0
info:
  title: Interhyp Submission Commands API
  version: 6.10.0
  contact:
    name: Interhyp AG (Team Provider Excellence)
    email: support_submission_api@interhyp.de
    url: https://www.interhyp.de
  license:
    name: Interhyp AG
  description: This document describes the RESTful API and resources provided by Interhyp AG.
servers:
- url: https://api-dev.ehyphome.de/submission/v2
  description: Test-Staging
- url: https://api-acc.ehyphome.de/submission/v2
  description: Acceptance-Staging
- url: https://api.interhyp.de/submission/v2
  description: Production
security:
- ApiKey: []
  BearerAuth: []
tags:
- name: Commands
  description: provides endpoints to access to commands sent to the submission API
paths:
  /commands/{commandId}:
    get:
      summary: Get an existing command
      description: 'Delivers information about an existing command


        A Command is a unit of execution which has been created to perform asynchronous operation.'
      operationId: getCommandsById
      tags:
      - Commands
      parameters:
      - $ref: '#/components/parameters/command-id'
      responses:
        '200':
          description: Command is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Command'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that a requested command resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
components:
  schemas:
    OAuthProblem:
      type: object
      description: Error while Authentication
      required:
      - error
      - error_description
      properties:
        error:
          type: string
          description: Summary of the error type
          example: invalid_token
        error_description:
          type: string
          description: Detailed information about the error
          example: Access token expired
    Violation:
      description: 'DE: Ein Verstoss gegen die Schnittstellenspezifikation. EN: A violation against the API schema.

        '
      type: object
      title: Violation
      properties:
        field:
          type: string
          description: 'DE: Bezeichner des problematischen Felds. EN: Name of the problematic field.

            '
          example: address.city.numberOfInhabitants
        message:
          type: string
          description: 'DE: Beschreibung des Verstosses. EN: Description of the violation.

            '
          example: Must be greater than or equal to 0.
    CommandError:
      type: object
      required:
      - errorCode
      properties:
        errorMessage:
          type: string
        errorCode:
          type: string
          x-extensible-enum:
          - SBM_ARCHIVE_SUBMISSION_DENIED
          - SBM_NOT_UNARCHIVABLE
          - SBM_ASSIGN_PROCESSOR_UNIT_MISMATCH
          - SBM_STATUS_CHANGE_DENIED
          - UNEXPECTED_ERROR
          - NO_PROCESSOR_ASSIGNED
          - FINAL_STATE
          - PRE_INQUIRY_NOT_SUBMITTED
          - PRE_INQUIRY_ALREADY_SUBMITTED
          - PRE_INQUIRY_NOT_ARCHIVABLE
          - PRE_INQUIRY_IS_ARCHIVED
    RFC7807Problem:
      type: object
      title: RFC7807Problem
      description: 'DE: Angaben zum zurueckgegebenen Fehler. EN: Holds information on the returned error.

        '
      required:
      - timestamp
      - traceId
      - instance
      - title
      - status
      properties:
        timestamp:
          type: string
          format: date-time
          description: 'DE: Ein UTC-Zeitstempel, der den Fehlerzeitpunkt angibt (https://de.wikipedia.org/wiki/Koordinierte_Weltzeit). EN: A UTC date-time indicating the error timestamp (https://en.wikipedia.org/wiki/Coordinated_Universal_Time).

            '
          example: 2024-06-29 19:22:50+00:00
        type:
          type: string
          format: uri
          description: 'DE: Verknuepfung zum Abruf von mehr Informationen zu dem Fehler. EN: URL referring to more information about the error.

            '
          default: about:blank
        title:
          type: string
          description: 'DE: Kurzbeschreibung des Fehlers. EN: Error short description.

            '
          example: Bad Request
        status:
          type: integer
          format: int32
          description: 'DE: HTTP-Status-Code gemaess Konvention (https://tools.ietf.org/html/rfc2616#section-10). EN: HTTP status code following standared error codes (https://tools.ietf.org/html/rfc2616#section-10).

            '
          example: 400
          minimum: 100
          maximum: 599
        detail:
          type: string
          description: 'DE: Detaillierte Beschreibung des Fehlers. EN: Detailed description for the returned error.

            '
          example: JSON parse error
        traceId:
          type: string
          description: 'DE: Eindeutige Kennung zur Verfolgung der Anfrage. EN: Unique trace id for problematic request.

            '
          example: avx1234asd
        instance:
          type: string
          format: uri
          description: 'DE: Pfad zur betreffenden Resource. EN: Path of requested resource.

            '
          example: http://localhost/resources/123
        violations:
          type: array
          description: 'DE: Abfolge der Verstoesse in der Anfrage. EN: Collection of the invalid content of the request.

            '
          items:
            $ref: '#/components/schemas/Violation'
    Command:
      type: object
      required:
      - commandId
      - result
      - traceId
      - aggregateId
      properties:
        commandId:
          type: string
        result:
          type: string
          x-extensible-enum:
          - SUCCESSFUL
          - FAILED
          - DLQ
          - PARKING_LOT
          - DLQ_PURGE
          - UNPROCESSABLE
        traceId:
          type: string
        aggregateId:
          type: string
        error:
          $ref: '#/components/schemas/CommandError'
  parameters:
    command-id:
      name: commandId
      in: path
      required: true
      schema:
        type: string
      description: Id of the requested command
  securitySchemes:
    BearerAuth:
      $ref: '#/components/securitySchemes/StandardBearerAuth'
    ApiKey:
      $ref: '#/components/securitySchemes/StandardApiKey'
    StandardApiKey:
      type: apiKey
      in: header
      name: Api-Key
      description: API keys are unique codes issued by an API provider that allow partners to access specific API resources. By requiring an API key, the provider can ensure that only authorized clients are accessing the API and can prevent potential abuse or unauthorized access.
    StandardBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT stands for JSON Web Token and is a type of bearer token that is commonly used for authentication and authorization purposes. Once retrieved, the token is sent with each request and grants access to the associated resource until it expires or is revoked. Thus, it is a compact, URL-safe means of representing a user's claims to access a resource without providing additional credentials.
x-guideline-version: v1