OpenAPI Specification
openapi: 3.0.2
info:
title: Interhyp Submission commands protocol 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: protocol
description: access to submission protocol
paths:
/v2/submissions/protocol:
get:
deprecated: true
summary: Delivers all submissions protocol for a provider
description: Delivers a collection of submission protocol for a specific provider filtered by the date of protocol.<p> *By Default*, we will return the first *20* matching records. However, this is not a hard limitation! a parameter called `limit` can be used to tell the API how many records you want to return all at once *(max 40)*.<p> To get further matching records, a parameter called `after` or `before` can be used to tell the API the start of each page using specified cursor.<p> To navigate through the query result, a reference to the following navigations are included in the response *(next, prev, first, last, self)*.
operationId: getSubmissionsProtocol
tags:
- protocol
parameters:
- $ref: '#/components/parameters/since'
- $ref: '#/components/parameters/until'
- $ref: '#/components/parameters/protocol-type-filter'
- $ref: '#/components/parameters/sbms-protocol-limit'
- $ref: '#/components/parameters/cursor-after'
- $ref: '#/components/parameters/cursor-before'
- $ref: '#/components/parameters/embed'
responses:
'200':
description: A paged array of submissions protocol
content:
application/json:
schema:
$ref: '#/components/schemas/SubmissionProtocol'
'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'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/UnexpectedError'
components:
schemas:
SubmissionProtocolRef:
type: object
allOf:
- $ref: '#/components/schemas/ResourceRef'
- properties:
embedded:
$ref: '#/components/schemas/EmbeddedSubmissionProtocol'
SubmissionProtocolItem:
type: object
properties:
submission:
$ref: '#/components/schemas/SubmissionProtocolRefItem'
protocol:
$ref: '#/components/schemas/SubmissionProtocolRef'
EmbeddedSubmissionProtocol:
type: object
properties:
protocol:
type: array
items:
$ref: '#/components/schemas/ProtocolItem'
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
Paging:
properties:
cursor:
$ref: '#/components/schemas/Cursor'
previous:
type: string
format: uri
next:
type: string
format: uri
first:
type: string
format: uri
last:
type: string
format: uri
self:
type: string
format: uri
SubmissionProtocolRefItem:
type: object
allOf:
- $ref: '#/components/schemas/SubmissionRef'
- properties:
legacyId:
description: Legacy submission id
type: string
SubmissionProtocol:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/SubmissionProtocolItem'
paging:
$ref: '#/components/schemas/Paging'
SubmissionRef:
type: object
allOf:
- $ref: '#/components/schemas/ResourceRef'
- properties:
id:
type: string
description: Submission id
ProtocolItem:
type: object
properties:
type:
$ref: '#/components/schemas/ProtocolItemType'
id:
type: string
createdAt:
type: string
format: date-time
author:
type: string
discriminator:
propertyName: type
mapping:
DOCUMENT: '#/components/schemas/SubmissionDocumentUpdate'
DATA: '#/components/schemas/SubmissionDataUpdate'
STATUS: '#/components/schemas/SubmissionStatusUpdate'
NEW_SUBMISSION: '#/components/schemas/NewSubmission'
BadRequest:
allOf:
- $ref: '#/components/schemas/ClientError'
ClientError:
type: object
required:
- rootCause
allOf:
- $ref: '#/components/schemas/UnexpectedError'
- properties:
message:
type: string
exception:
type: string
ProtocolItemType:
type: string
description: open ended enum contains possible protocol item types, possible values are (DOCUMENT, DATA, STATUS, NEW_SUBMISSION)
example: DOCUMENT
x-extensible-enum:
- DOCUMENT
- DATA
- STATUS
- NEW_SUBMISSION
Cursor:
properties:
before:
type: string
after:
type: string
ResourceRef:
required:
- href
properties:
href:
type: string
description: Link to retrieve a specific resource
example: http://some-domain/some/link/to/somewhere
Unauthorized:
allOf:
- $ref: '#/components/schemas/ClientError'
parameters:
cursor-before:
name: before
in: query
description: Cursor that points to the start of the page of data that has been returned.
required: false
schema:
type: string
protocol-type-filter:
name: protocolType
in: query
required: false
schema:
type: string
enum:
- document
- data
- status
- new_submission
description: query parameter to restrict submissions associated to the provided protocol type.
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
cursor-after:
name: after
in: query
description: Cursor that points to the end of the page of data that has been returned.
required: false
schema:
type: string
since:
name: since
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
sbms-protocol-limit:
name: limit
in: query
description: Specifies how many items to return at one time (max 40). <br> A query may return fewer than the value of limit due to filtering.
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 40
default: 20
until:
name: until
in: query
description: A UTC date-time value that points to the end of the range of time-based data. <br> If not provided, current date-time is used. Defined by date-time - [RFC3339](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14).
required: false
schema:
type: string
format: date-time
example: 2019-12-29 10:22:50+00:00
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT