openapi: 3.0.1
info:
title: fiskaltrust PosSystem API
description: "This API provides a variety of different functionalities for POS systems\
\ and is the central entry point to the **fiskaltrust.Middleware**. It can be\
\ used to **fiscalize (or sign) receipts**, execute **payments** via different\
\ payment providers, **digitally print receipts** (e.g. via the Receipt Bundle),\
\ and to **export data** from the Middleware.
\n
\nAPI design principles
While\
\ the POSSystem API was designed to be easily usable via HTTP calls and JSON the\
\ call patterns follow a processual principle. We believe that by giving POS Systems\
\ a way to handle core processes in a stateful way as if they are a statemachine,\
\ that we can always ensure that the processes run as frictionless as possible.\
\ Each call that is handled by the POS System API is safe to be replayed and idempotent.\
\
\n\n Authentication
The POSSystem API can only be used with\
\ the access data of a CashBox. These credentials can be found on the fiskaltrust.Portal\
\ in the CashBox Configuration page.You will need both CashBoxId\
\ and AccessToken to use this API.
\n \n Versioning
This\
\ API uses semantic versioning, meaning only major version changes contain breaking\
\ changes. Non-breaking changes (like returning additional data without changing\
\ the original model) will not increase the major version.
- The latest\
\ version is used if no version is specified (like in the samples in this collection).
- Users\
\ can specify versions by explicitly stating it in the URL once more versions\
\ are released.
\n \nHeaders:\n- x-operation-id: The operation id is\
\ meant to be a idempotency key that let's the caller of the API endpoints safely\
\ retry calls. In case of timeouts, network interruptions this gives the ability\
\ to safely retry the process. While the request on the server side is still in\
\ progress calling the endpoint again with the same operation id does return a\
\ 422 Unprocessable Content. As soon as the request is finished whatever the initial\
\ request has finished with will be returned to the caller whenever the endpoint\
\ is called with the same body and the same operation-id.\n\n e.g. Calling /sign\
\ with x-operation-id ea4279ee-8684-412f-b8eb-32b5dea52811. The operation fails\
\ with a timeout. The caller handles the exception by performing the exact same\
\ operation again. The backend notices that this operation-id has been used in\
\ another transaction already and checks the state. If the state is finished it\
\ returnes the original response body"
contact:
name: fiskaltrust
email: hello@fiskaltrust.eu
license:
name: This documentation and samples are released under the EUPL license.
url: https://opensource.org/licenses/EUPL
version: "2.0"
servers:
- url: https://possystem-api-sandbox.fiskaltrust.eu/v2
description: Sandbox
- url: https://possystem-api.fiskaltrust.eu/v2
description: Production
security:
- CashBoxId: []
CashBoxAccessToken: []
tags:
- name: SynchronAPI
description: |
# synchronous call pattern
caller / watcher description
## successfull
[](https://mermaid.live/edit#pako:eNrFU01LAzEQ_SshJ4UuvedQEC1SULqwBT3sZUymbWQ3icmsWGr_u9PuB_3QQ0_mNPPy8mbeMNlK7Q1KJRN-NOg0PlhYRahLJ_i8-S-R-1RsEmEHBYhktQ3gSNxDVWG8xF-A9Lq_QGcuGXf5rAVbiWwyYUSJfF4sRNx3kujmNZsHjEDWu2xmbls-aLKfQHhSewAH2a6DXvdxuhDjd99EB9V4UJ2xqfFplTO9EyOXVTjgCh1JiSdIVBAzlAjs2rqV-BYheo0pcdK-Mfi7-hF-pt86VTyXFLxL-Df_CDsez38Pw3iH15iXI1ljrMEa3svtnlFKWmONpVQcGlxCU1EpS7djKjTki43TUlFscCSbYFinW2OpllClAZ0aSz72TDxkz-3-H77B7gcTagV6)
## timeout / retry
[](https://mermaid.live/edit#pako:eNrFU8FKAzEQ_ZWQk0KX3nNYEC1SUFrYgj3sZUymNrKbxGQiltp_N212l9bWg17MKXl5mffmkdlyaRVywQO-RTQS7zS8eGhrw9J6th9sbkO1CYQd5MCTltqBIXYLTYP-HH8Ckuv-Ao06Z9zMpxnMJYqyTIhg81m1YH7vJNDVspg59EDammKqrjMfJOl3IDzRHsChbNoUxTJzBCPdoo2UrzpzveT9ZMHGrzZ6A814EJymfsenBr5JnfR42UBZdiTBHiBQRYkhmEuBaPPCPpnzVmII-aCswfxU4WWRI_zP8WVbfS4eg7Mm4M_1j7DjwP8lw98mxEe8Rd-CVul7b_eMmtMaW6y5SFuFK4gN1bw2u0SFSLbaGMkF-YgjHp1Kdbpp4GIFTRjQidJkfc_Ew-kxj9FhmnZffSQbwQ)
## failed
[](https://mermaid.live/edit#pako:eNptklFrwyAUhf-K-LRBQ959CIytjMJGAymsD3m505vVYTQz17FS-t9naxKaZT7puR_H4_WeuHQKueA9fgW0Ep80fHhoa8vienc_rHR9dewJB6kDT1rqDiyxRzAG_VJ_A5KHsYBWLYmHcpPEZJEVRVQEK7fVjvlLkp7u9tm2Qw-knc026j7xIEl_A-Hs7kmcbOMmy_aJEYx0iy5QKilc4jfare_wjjHd83rH8k8XvAWTT9k2sTX5POufVLN2_J-1KAZIsBfoqaJICNaANqgWEWd-8-fwFW_Rt6BV_NLThag5HbDFmou4VdhAMFTz2p4jCoFcdbSSC_IBVzx0KvoME8BFA6af1LXS5PxI4vX0mkbnOkHnX_u2w24)
- name: echo
description: |
health check
- name: order
description: |
execute orders
- name: pay
description: |
execute payments
- name: sign
description: |
# finalize receipts
## successfull
[](https://mermaid.live/edit#pako:eNrVVMFOxCAQ_RXCSZM2rh45bGLUgwdjs_VmPUxgthJbQJgaTcO_y5a1ajSbGPeynIbH482bCczIpVXIBQ_4PKCReKmh9dA3hqXlwJOW2oEhdgFdh_4nfl5dZzATyuUyIYJVt_UdO6l1a1Yb5UBHr6V16IG0NaVWx2xcoUTtaHseswpI0i9A-C3fDM7JUpAyZY5gZ4vTDCv89f4XeKfdCvFph-V_OEwWF4LdjyxQYgnmvJUYgjYtiw8H7L2YUWUN7quWXEdw1gTcYyFTHZ_PLuvHw-j-3xrLC96j70Gr9LXHDafh9Ig9NlykUOEaho4a3piYqDCQrd-M5IL8gAUfnEpK20nAxRq6MKNXSpP1H0ycdjd5hEyTJL4DZatqBg)
## timeout / retry
[](https://mermaid.live/edit#pako:eNqtU8FKxDAQ_ZWQk8IWF485FEQ9eBDL1pv1MCSzu8E2ielEVkr_3bTZrS4rC4XNafLm8d5jmOm4tAq54C1-BjQSHzRsPDSVYfE58KSldmCI3UNdoz_F74qnBCZClucREax4KV_ZTak3ZjUot3S1y6xDD6StybS6Zt0KJWpH-36fVECS_gLCI78JnMxikWW7xBGMdIM2UGopPKVfJttgmucHU3a7XJ44_k39n2mB-HHGePYMjuMI9taxliJLMGUNsv79bMJ5o2qdNS1eMPKY-HfUSb-flZgveIO-Aa3iDncDp-K0xQYrLmKpcA2hpopXpo9UCGTLbyO5IB9wwYNTUWm_8lysoW4n9FFpsv7AxPH3nG5lPJn-ByT_ERA)
## failed
[](https://mermaid.live/edit#pako:eNrVk8FKxDAQhl8l5KSwxbp4ymFF1IMHsWy9GQ9DMl2DbRKTqSil7252sxbFZUHcizlN_vkz8zFkBq6cRi54xJcercIrA6sAnbQsHQ-BjDIeLLFLaFsMP_WL6iaL2VAsFkkRrLqr79lJbVZ2ua4c6eitcB4DkHG2MPqYDUtUaDxt82OuAorMKxB-6zeJU7MUpE7ZI9i8PM2yxp3vv8h7cSvE5z3IfyBMiKVgDwOLlFyCNWBa1Gx8PAh3Zo7e2YgHhJ6XZ-f_Y66_GyOf8Q5DB0anjz-sPZLTE3YouUihxgb6liSXdkxW6MnV71ZxQaHHGe-9TpW2e8JFA22c1GttyIVPJ25ut3nBNns2fgCFdB6q)
## callback usage
[](https://mermaid.live/edit#pako:eNqlk19PwyAUxb8K4cklbTZ9JGaJ8U_ig3FZ9a0vd3A3iS0gULPZ9LtLS1e3uRmNfYLD6Y9zL1BTrgVSRh2-Vag43khYWShzRcK30Gsy0y7bOI-9ZMB6yaUB5ck1FAXa4_oC-GtcQSW-W65m91GMjHQ6DQojs8fsiYwzuVLzNo_zlws7np6tU23QgpdapVIku1Pe75UupYJCfuCJZefB46jD1XPkKI3vt2hiEOBevgfPXlWDOOQNgxA2ehi5mJxHWeDR_3fkPUKPaJMNRbcBt-KzLQ6KHpG6K4EZqzk6J9WqIeRH4t22I7-gCq1w4J0-E2e0cngI-VcDJ4x8HUjkN3_qKU1oibYEKcI1rltPTv0LlphTFoYCl1AVPqe5aoIVKq-zjeKUeVthQisjAqm_9ZQtoXCDeiuk13brxG72EJ9L92qaTzigF8Q)
- name: issue
description: |
distribute receipts
- name: journal
description: |
export data
- name: configuration
description: |
configuration handling and management tools for cash registers
paths:
/echo:
post:
tags:
- SynchronAPI
summary: Executes a blocking echo call end-to-end
description: |
This method can be used to perform a basic health and communcation check. It is also used for reseting the Middleware Instance (echo(null)
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-operation-callback-state
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-state'
- name: x-terminal-id
in: header
description: |
identifies the terminal #TODO
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
- name: x-possystem-id
in: header
description: |
identifies the calling possystem #TODO
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-possystem-id'
requestBody:
content:
application/json:
schema:
type: object
responses:
"200":
description: |
operation-id found, response from cashbox/queue/terminal
content:
application/json:
schema:
type: object
"201":
description: |
Operation-id successfully created. Response contains information from the cashbox/queue/terminal.
content:
application/json:
schema:
type: object
"400":
description: |
The request was malformed or could not be processed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
"401":
description: Access token is not set or invalid.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
unauthorized:
$ref: '#/components/examples/unauthorized'
"500":
description: The server encountered an unexpected error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
serverError:
$ref: '#/components/examples/server-error'
callbacks:
OperationState:
$ref: '#/components/callbacks/OperationState'
/sign:
post:
tags:
- SynchronAPI
summary: execute a sign call end-to-end
description: |
This method can be used to sign different types of receipts according to local fiscalization regulations. After signing the receipt according to the fiscal law, this method synchronously returns the data that need to be printed onto the receipt. The format of the receipt request is documented in the Middleware API docs, and the exact behavior of the method is determined by the cases sent within the properties (e.g. ftReceiptCase, ftChargeItemCase and ftPayItemCase.
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-operation-callback-state
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-state'
- name: x-terminal-id
in: header
description: |
identifies the terminal #TODO
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
- name: x-possystem-id
in: header
description: |
identifies the calling possystem #TODO
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-possystem-id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReceiptRequest'
responses:
"200":
description: |
successfull, response from existing item
content:
application/json:
schema:
$ref: '#/components/schemas/ReceiptResponse'
"201":
description: |
successfull created, response from queue
content:
application/json:
schema:
$ref: '#/components/schemas/ReceiptResponse'
"400":
description: |
The request was malformed or could not be processed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
"401":
description: Access token is not set or invalid.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
unauthorized:
$ref: '#/components/examples/unauthorized'
"500":
description: The server encountered an unexpected error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
serverError:
$ref: '#/components/examples/server-error'
callbacks:
OperationState:
$ref: '#/components/callbacks/OperationState'
/SignRequest:
post:
tags:
- sign
summary: starts a sign request
description: |
starts a sign request
operationId: SignRequestAsnyc
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-operation-callback-finalized
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-finalized'
- name: x-operation-callback-state
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-state'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
- name: x-possystem-id
in: header
description: |
identifies the calling possystem #TODO
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-possystem-id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReceiptRequest'
responses:
"200":
description: |
successfull operation found
"201":
description: |
successfull, operation created
"400":
description: |
The request was malformed or could not be processed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
"401":
description: Access token is not set or invalid.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
unauthorized:
$ref: '#/components/examples/unauthorized'
"500":
description: The server encountered an unexpected error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
serverError:
$ref: '#/components/examples/server-error'
callbacks:
OperationState:
$ref: '#/components/callbacks/OperationState'
OperationFinalized:
$ref: '#/components/callbacks/OperationFinalized'
/PeekSignRequestState:
get:
tags:
- sign
summary: get state of sign request
description: |
get state of sign request
operationId: PeekSignRequestStateAsnyc
parameters:
- name: x-operation-id
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
responses:
"200":
description: |
successfull
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SignRequestState'
"400":
description: |
The request was malformed or could not be processed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
"401":
description: Access token is not set or invalid.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
unauthorized:
$ref: '#/components/examples/unauthorized'
"500":
description: The server encountered an unexpected error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
serverError:
$ref: '#/components/examples/server-error'
/SignResponse:
post:
tags:
- sign
summary: get result of sign request and purges it from queue
description: |
get result of sign request and purges it from queue
operationId: SignResponseAsnyc
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
responses:
"200":
description: |
successfull
content:
application/json:
schema:
$ref: '#/components/schemas/ReceiptResponse'
"400":
description: |
The request was malformed or could not be processed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
"401":
description: Access token is not set or invalid.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
unauthorized:
$ref: '#/components/examples/unauthorized'
"500":
description: The server encountered an unexpected error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
serverError:
$ref: '#/components/examples/server-error'
/issue:
post:
tags:
- SynchronAPI
summary: execute a issue call end-to-end
description: |
execute a issue call end-to-end
operationId: Issue
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-operation-callback-state
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-state'
- name: x-terminal-id
in: header
description: |
identifies the terminal #TODO
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
- name: x-possystem-id
in: header
description: |
identifies the calling possystem #TODO
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-possystem-id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/issue_body'
responses:
"200":
description: |
successfull, response from existing item
content:
application/json:
schema:
$ref: '#/components/schemas/IssueResponse'
"201":
description: |
successfull created
content:
application/json:
schema:
$ref: '#/components/schemas/IssueResponse'
"400":
description: |
The request was malformed or could not be processed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
"401":
description: Access token is not set or invalid.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
unauthorized:
$ref: '#/components/examples/unauthorized'
"500":
description: The server encountered an unexpected error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
serverError:
$ref: '#/components/examples/server-error'
callbacks:
OperationState:
$ref: '#/components/callbacks/OperationState'
/issue/{QueueId}/{QueueItemId}:
get:
tags:
- SynchronAPI
summary: get content of an issued receipt
description: |
get content of an issued receipt in requested format, without updateing the submitted state
parameters:
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
- name: QueueItemId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
responses:
"200":
description: |
(OK) successfull
content:
image/png:
schema:
type: string
format: binary
application/pdf:
schema:
type: string
format: binary
application/json:
schema:
type: object
"204":
description: |
(No Content) successfull
"400":
description: |
The request was malformed or could not be processed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
"401":
description: Access token is not set or invalid.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
unauthorized:
$ref: '#/components/examples/unauthorized'
"500":
description: The server encountered an unexpected error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
serverError:
$ref: '#/components/examples/server-error'
put:
tags:
- SynchronAPI
summary: updates an issued and/or submitted receipt
description: |
execute a update call end-to-end
parameters:
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
- name: QueueItemId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: X-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-operation-callback-state
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-state'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
- name: x-possystem-id
in: header
description: |
identifies the calling possystem #TODO
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-possystem-id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueueId_QueueItemId_body'
responses:
"200":
description: |
(OK) successfull action: download, print
content:
text/*:
schema:
type: string
application/pdf:
schema:
type: string
format: binary
image/*:
schema:
type: string
format: binary
"201":
description: |
(Created) successfull action: send, upload
content:
text/*:
schema:
type: string
application/pdf:
schema:
type: string
format: binary
image/*:
schema:
type: string
format: binary
"204":
description: |
(No Content) successfull action: accept, view
"400":
description: |
The request was malformed or could not be processed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
"401":
description: Access token is not set or invalid.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
unauthorized:
$ref: '#/components/examples/unauthorized'
"500":
description: The server encountered an unexpected error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
serverError:
$ref: '#/components/examples/server-error'
callbacks:
OperationState:
$ref: '#/components/callbacks/OperationState'
/issue/{QueueId}/{QueueItemId}/link/qrcode:
get:
tags:
- SynchronAPI
summary: link visualization via qr code
description: |
get image of qr code for digital receipt url 
parameters:
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
- name: QueueItemId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
responses:
"200":
description: |
successfull
content:
image/png:
schema:
type: string
format: byte
"400":
description: |
The request was malformed or could not be processed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
"401":
description: Access token is not set or invalid.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
unauthorized:
$ref: '#/components/examples/unauthorized'
"404":
description: The requested resource was not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
notFound:
$ref: '#/components/examples/not-found'
"500":
description: The server encountered an unexpected error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
serverError:
$ref: '#/components/examples/server-error'
/issue/{QueueId}/{QueueItemId}/delivered:
get:
tags:
- SynchronAPI
summary: "gives the information, if the receipt was delivered, at leasted once"
description: |
TBD
parameters:
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
- name: QueueItemId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
responses:
"200":
description: |
(OK) successfull was deliverd
content:
application/json:
schema:
type: object
"204":
description: |
(No Content) successfull was not delivered
"400":
description: |
The request was malformed or could not be processed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
"401":
description: Access token is not set or invalid.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
unauthorized:
$ref: '#/components/examples/unauthorized'
"404":
description: The requested resource was not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
notFound:
$ref: '#/components/examples/not-found'
"500":
description: The server encountered an unexpected error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
serverError:
$ref: '#/components/examples/server-error'
default:
description: "unexpected error \n"
/IssueRequest:
post:
tags:
- issue
summary: starts an issue request
description: |
execute a issue call end-to-end publish a digital receipt
operationId: IssueRequestAsync
parameters:
- name: x-operation-id
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-operation-callback-finalized
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-finalized'
- name: x-operation-callback-state
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-state'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
- name: x-possystem-id
in: header
description: |
identifies the calling possystem #TODO
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-possystem-id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueRequest_body'
responses:
"201":
description: |
successfull created
"400":
description: |
header values wrong
default:
description: "unexpected error \n"
callbacks:
OperationState:
$ref: '#/components/callbacks/OperationState'
OperationFinalized:
$ref: '#/components/callbacks/OperationFinalized'
/IssueRequest/{QueueId}/{QueueItemId}:
put:
tags:
- issue
summary: updates an issue request
description: |
execute a issue call end-to-end
operationId: IssueUpdate
parameters:
- name: x-operation-id
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-operation-callback-finalized
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-finalized'
- name: x-operation-callback-state
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-state'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
- name: QueueItemId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueueId_QueueItemId_body_1'
responses:
"200":
description: |
(OK) successfull action: download, print
content:
text/*:
schema:
type: string
application/pdf:
schema:
type: string
format: binary
image/*:
schema:
type: string
format: binary
"201":
description: |
(Created) successfull action: send, upload use `PeekIssueRequestState` and `IssueResponse` for more details
"204":
description: |
(No Content) successfull action: accept, view
"400":
description: |
Bad Request
"500":
description: |
Internal error
callbacks:
OperationState:
$ref: '#/components/callbacks/OperationState'
OperationFinalized:
$ref: '#/components/callbacks/OperationFinalized'
/PeekIssueRequestState:
get:
tags:
- issue
summary: get state of issue request
description: |
get state of sign request
operationId: PeekIssueRequestStateAsnyc
parameters:
- name: x-operation-id
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-terminal-id
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
responses:
"200":
description: |
successfull
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IssueRequestState'
"400":
description: |
not successfull
default:
description: |
unexpected error
/IssueResponse:
post:
tags:
- issue
summary: get result of issue request and purges the state from queue/processor
description: |
get result of issue request and purges it from queue/processor
operationId: IssueResponseAsnyc
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
responses:
"200":
description: |
successfull
content:
application/json:
schema:
$ref: '#/components/schemas/IssueResponse'
"400":
description: |
header values wrong
default:
description: "unexpected error \n"
/BlockIssueRequest/{QueueId}/{QueueItemId}/WhileSubmitted:
get:
tags:
- issue
summary: blocks for a maxiumum timeout in second (default is 15) and comes back
with 200 if delivered and 204 if not deliverd
description: |
TBD
parameters:
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
- name: QueueItemId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
- name: Timeout
in: query
required: false
style: form
explode: true
schema:
type: number
format: int
nullable: false
default: 15
responses:
"200":
description: |
(OK) successfull was deliverd
content:
application/json:
schema:
type: object
"204":
description: |
(No Content) successfull was not delivered
"404":
description: |
QueueId or QueueItemId doesn't exist
default:
description: "unexpected error \n"
/BlockIssueRequest/{QueueId}/{QueueItemId}/WhileDelivered:
get:
tags:
- issue
summary: blocks for a maxiumum timeout in second (default is 15) and comes
back with 200 if delivered and 204 if not deliverd
description: |
TBD
*TEST*
parameters:
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
- name: QueueItemId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
nullable: false
- name: Timeout
in: query
required: false
style: form
explode: true
schema:
type: number
format: int
nullable: false
default: 15
responses:
"200":
description: |
(OK) successfull was deliverd
content:
application/json:
schema:
type: object
"204":
description: |
(No Content) successfull was not delivered
"404":
description: |
QueueId or QueueItemId doesn't exist
default:
description: "unexpected error \n"
/pay:
post:
tags:
- SynchronAPI
summary: exectue a pay call end-to-end
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-operation-callback-state
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-state'
- name: x-terminal-id
in: header
description: "identifies the terminal and overwrites also TerminalId in ReceiptRequest,\
\ if given \n"
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
- name: x-possystem-id
in: header
description: |
identifies the calling possystem #TODO
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-possystem-id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequest'
examples:
payment:
$ref: '#/components/examples/PayRequestHobexPaymentMinimum_1'
cancel:
$ref: '#/components/examples/PayRequestHobexRestApiCancelMinimum_1'
refund:
$ref: '#/components/examples/PayRequestHobexRestApiRefundMinimum_1'
pre_authorize:
$ref: '#/components/examples/PayRequestHobexRestApiPreAuthMinimum_1_1'
pre_authorize_capture:
$ref: '#/components/examples/PayRequestHobexRestApiPreAuthMinimum_1_2'
pre_authorize_cancel:
$ref: '#/components/examples/PayRequestHobexRestApiPreAuthMinimum_1_3'
responses:
"200":
description: |
successfull, response from existing item
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
"201":
description: |
successfull created, response from queue
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
examples:
payment:
$ref: '#/components/examples/PayResponseHobexRestApiPaymentMinimum_1'
cancel:
$ref: '#/components/examples/PayResponseHobexRestApiCancelMinimum_1'
refund:
$ref: '#/components/examples/PayResponseHobexRestApiRefundMinimum_1'
pre_authorize:
$ref: '#/components/examples/PayResponseHobexRestApiPreAuthMinimum_1_1'
pre_authorize_capture:
$ref: '#/components/examples/PayResponseHobexRestApiPreAuthMinimum_1_2'
pre_authorize_cancel:
$ref: '#/components/examples/PayResponseHobexRestApiPreAuthMinimum_1_3'
"400":
description: |
Either the x-operation-id header was not sent or the body that was sent doesn't meet the requirements
"401":
description: |
Not authenticated
default:
description: "unexpected error \n"
callbacks:
OperationState:
$ref: '#/components/callbacks/OperationState'
delete:
tags:
- SynchronAPI
summary: stops ongoing pay call
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-operation-callback-state
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-state'
- name: x-terminal-id
in: header
description: "identifies the terminal and overwrites also TerminalId in ReceiptRequest,\
\ if given \n"
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
- name: x-possystem-id
in: header
description: |
identifies the calling possystem #TODO
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-possystem-id'
responses:
default:
description: "unexpected error \n"
callbacks:
OperationState:
$ref: '#/components/callbacks/OperationState'
/PayRequest:
post:
tags:
- pay
summary: starts a pay request
operationId: PayRequestAsnyc
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-operation-callback-finalized
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-finalized'
- name: x-operation-callback-state
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-state'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in PaymentRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequest'
examples:
payment:
$ref: '#/components/examples/PayRequestHobexPaymentMinimum_1'
cancel:
$ref: '#/components/examples/PayRequestHobexRestApiCancelMinimum_1'
refund:
$ref: '#/components/examples/PayRequestHobexRestApiRefundMinimum_1'
pre_authorize:
$ref: '#/components/examples/PayRequestHobexRestApiPreAuthMinimum_1_1'
pre_authorize_capture:
$ref: '#/components/examples/PayRequestHobexRestApiPreAuthMinimum_1_2'
pre_authorize_cancel:
$ref: '#/components/examples/PayRequestHobexRestApiPreAuthMinimum_1_3'
responses:
"200":
description: |
successfull submitted
"400":
description: |
not successfull
default:
description: "unexpected error \n"
callbacks:
OperationState:
$ref: '#/components/callbacks/OperationState'
OperationFinalized:
$ref: '#/components/callbacks/OperationFinalized'
delete:
tags:
- pay
summary: |
stops a ongoing pay request
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-operation-callback-finalized
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-finalized'
- name: x-operation-callback-state
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-callback-state'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in PaymentRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
responses:
default:
description: "unexpected error \n"
callbacks:
OperationState:
$ref: '#/components/callbacks/OperationState'
OperationFinalized:
$ref: '#/components/callbacks/OperationFinalized'
/PeekPayRequestState:
get:
tags:
- pay
summary: get state of pay request
description: |
get state of pay request
operationId: PeekPayRequestStateAsnyc
parameters:
- name: x-operation-id
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
responses:
"200":
description: |
successfull
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PayRequestState'
"400":
description: |
not successfull
default:
description: |
unexpected error
/PayResponse:
post:
tags:
- pay
summary: |
get result of a pay request and purges state from queue/processor
operationId: PayResponseAsnyc
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
responses:
"200":
description: |
successfull
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
examples:
payment:
$ref: '#/components/examples/PayResponseHobexRestApiPaymentMinimum_1'
cancel:
$ref: '#/components/examples/PayResponseHobexRestApiCancelMinimum_1'
refund:
$ref: '#/components/examples/PayResponseHobexRestApiRefundMinimum_1'
pre_authorize:
$ref: '#/components/examples/PayResponseHobexRestApiPreAuthMinimum_1_1'
pre_authorize_capture:
$ref: '#/components/examples/PayResponseHobexRestApiPreAuthMinimum_1_2'
pre_authorize_cancel:
$ref: '#/components/examples/PayResponseHobexRestApiPreAuthMinimum_1_3'
"400":
description: |
not successfull
default:
description: "unexpected error \n"
/PeekJournalItem/{QueueId}/{StorageType}/{Id}:
get:
tags:
- journal
summary: |
get a single journal entry by id
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
- name: StorageType
in: path
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/StorageTypeEnum'
- name: Id
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
responses:
"200":
description: |
successfull
"400":
description: |
not successfull
default:
description: "unexpected error \n"
/PeekJournalRange/{QueueId}/{StorageType}:
get:
tags:
- journal
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
- name: StorageType
in: path
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/StorageTypeEnum'
responses:
default:
description: "unexpected error \n"
/journal/{StorageType}/{Id}:
get:
tags:
- SynchronAPI
description: "gets a single entry of a specific \n"
parameters:
- name: StorageType
in: path
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/StorageTypeEnum'
- name: Id
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
responses:
"200":
description: |
successfull
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_200'
"400":
description: |
storage type not found
"404":
description: |
entry within storage type not found
default:
description: "unexpected error \n"
/pair:
post:
tags:
- configuration
parameters:
- name: x-operation-id
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
- name: x-operation-lifetime
in: header
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-lifetime'
- name: x-terminal-id
in: header
description: |
identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
required: false
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-terminal-id'
requestBody:
$ref: '#/components/requestBodies/PairRequest'
responses:
"200":
description: |
response credentials
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_200_1'
default:
description: "unexpected error \n"
security: []
/rebuild:
post:
tags:
- configuration
responses:
default:
description: "unexpected error \n"
components:
schemas:
x-operation-id:
description: |
operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime:
description: |
operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-state:
description: |
single state callback setting for current operation, executed each time when a status change occures
x-terminal-id:
description: terminal identification
x-possystem-id:
description: identifies the calling possystem
ProblemDetails:
required:
- title
type: object
properties:
type:
maxLength: 1024
type: string
description: A URI reference that identifies the problem type.
format: uri
status:
maximum: 599
minimum: 100
type: integer
description: The HTTP status code generated by the origin server for this
occurrence of the problem.
format: int32
title:
maxLength: 1024
type: string
description: "A short, human-readable summary of the problem type. It should\
\ not change from occurrence to occurrence of the problem, except for\
\ purposes of localization."
detail:
maxLength: 4096
type: string
description: A human-readable explanation specific to this occurrence of
the problem.
instance:
maxLength: 1024
type: string
description: A URI reference that identifies the specific occurrence of
the problem. It may or may not yield further information if dereferenced.
code:
maxLength: 50
type: string
description: An API specific error code aiding the provider team understand
the error based on their own potential taxonomy or registry.
errors:
$ref: '#/components/schemas/Errors'
Errors:
maxItems: 1000
type: array
description: An array of error details to accompany a problem details response.
items:
$ref: '#/components/schemas/ErrorDetail'
ErrorDetail:
required:
- detail
type: object
properties:
detail:
maxLength: 4096
type: string
description: "A granular description on the specific error related to a\
\ body property, query parameter, path parameters, and/or header."
pointer:
maxLength: 1024
type: string
description: A JSON Pointer to a specific request body property that is
the source of error.
parameter:
maxLength: 1024
type: string
description: The name of the query or path parameter that is the source
of error.
header:
maxLength: 1024
type: string
description: The name of the header that is the source of error.
code:
maxLength: 50
type: string
description: A string containing additional provider specific codes to identify
the error context.
description: An object to provide explicit details on a problem towards an API
consumer.
ReceiptRequest:
required:
- cbChargeItems
- cbPayItems
- cbReceiptMoment
- cbReceiptReference
type: object
properties:
cbTerminalID:
maxLength: 1023
type: string
description: |
The unique identification of the input-station/terminal within a cash-register/pos-system identified by `ftCashBoxID`.
nullable: false
default: undefined
cbReceiptReference:
maxLength: 1023
type: string
description: |
Reference number send by the cash register. This value must be a unique string/receipt number related to the calling cash register. This string/receipt number is a unique primary key of the dataset of the cash register.
nullable: false
default: undefined
cbReceiptMoment:
type: string
description: |
moment at which the receipt was create by the cash register, must be provided in UTC.
format: date-time
nullable: false
example: 2020-06-29T17:45:40.505Z
cbChargeItems:
type: array
description: |
list of line items related to services and products
items:
$ref: '#/components/schemas/ChargeItem'
cbPayItems:
type: array
description: |
list of line items related to payments
items:
$ref: '#/components/schemas/PayItem'
ftCashBoxID:
type: string
description: |
identification of the cash register
format: uuid
nullable: false
default: 00000000-0000-0000-0000-000000000000
ftPosSystemID:
type: string
description: |
identification of the used software of the cash register
format: uuid
nullable: false
default: 00000000-0000-0000-0000-000000000000
ftReceiptCase:
type: integer
description: |
Type of business according to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO! this is relevant for fiskaltrust middleware processing and is a country specific mapping. as fallback when not specified, a cash register business case at the point-of-sale is used.
format: uint64
nullable: false
default: 0
ftReceiptCaseData:
description: "optional gives additional details for defined type of business\
\ related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu\
\ !TODO! \n"
oneOf:
- type: string
nullable: true
- type: object
additionalProperties: true
nullable: false
ftQueueID:
type: string
description: |
optional routing instruction to identify a specific queue behind a load balancer or in other usecases
format: uuid
nullable: true
cbPreviousReceiptReference:
maxLength: 1023
type: string
description: |
optional Reference `cbReceiptReference` of the previous receipt. Used to connect multiple requests for a single Business Case.
nullable: true
cbReceiptAmount:
description: |
optional total receipt amount, including value added taxes (=gross receipt amount) given to avoid calculation and rounding differences. systems which are using net amounts as central calculation should alsways use this property. if not provided, the sum of `Amount` in all provided `ftChargeItems` is used as total receipt amount. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
nullable: true
oneOf:
- type: integer
format: int64
- type: number
format: double
default: null
cbUser:
description: |
optional Identification of the user, who creates the receipt.
oneOf:
- maxLength: 1023
type: string
nullable: true
- type: object
properties:
Description:
maxLength: 1023
type: string
nullable: true
additionalProperties: true
nullable: false
default: null
cbArea:
description: |
optional Identification of the area/section/field, in which the receipt is created. e.g. Table number of a restaurant business; a department of a commercial establishment; the vehicle of a taxi company
oneOf:
- maxLength: 1023
type: string
nullable: true
- type: object
properties:
Description:
maxLength: 1023
type: string
nullable: true
additionalProperties: true
nullable: false
default: null
cbCustomer:
description: |
optional Identification of the consumer, for whom the receipt is created. e.g. Email address, phone number, personal tax number
oneOf:
- maxLength: 1023
type: string
nullable: true
- type: object
properties:
Description:
maxLength: 1023
type: string
nullable: true
additionalProperties: true
nullable: false
default: null
cbSettlement:
description: |
optional Settlement identification where this receipt will be added. e.g. shift number or day of operation
oneOf:
- maxLength: 1023
type: string
nullable: true
- type: object
properties:
Description:
maxLength: 1023
type: string
nullable: true
additionalProperties: true
nullable: false
default: null
Currency:
$ref: '#/components/schemas/CurrencyEnum'
DecimalPrecisionMultiplier:
$ref: '#/components/schemas/DecimalPrecisionMultiplierEnum'
description: |
The cash register transfers the data of an entire receipt request to the fiskaltrust.Middleware using the ReceiptRequest data structure. The details of fields supported by this data structure are outlined in the table below. The field fiskaltrust receipt case (ftReceiptCase) is of the highest importance for the correct processing of the receipt. This field defines the receipt type, determines if the receipt has to be secured accordingly to the national law, and establishes the way to calculate the correct values for each national counter.
ChargeItem:
required:
- Amount
- Description
- Quantity
- VATRate
type: object
properties:
ftChargeItemID:
type: string
description: |
optional used as an identifier of a chargeitem, when reading data
format: uuid
nullable: true
readOnly: true
Quantity:
description: |
defines the quantity of the line item. quantities of line items with same `Description`, `VATRate` and itemprice (=`Amount`/`Quantity`) can be accumulated for better visualization. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
oneOf:
- type: integer
format: int64
nullable: false
default: 1
- type: number
format: double
nullable: false
default: 1.0
Description:
maxLength: 1023
type: string
description: |
defines the description of the line item. line items with same `Description`, `VATRate` and itemprice (=`Amount`/`Quantity`) can be accumulated for better visualization
nullable: true
Amount:
description: |
defines the (total) amount of the line item. to get itemprice the amount need to be devided by quantity. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
oneOf:
- type: integer
format: int64
nullable: false
default: 0
- type: number
format: double
nullable: false
default: 0.0
VATRate:
description: |
defines the value added tax rate in percentage of the line item. line items with same `Description`, `VATRate` and itemprice (=`Amount`/`Quantity`) can be accumulated for better visualization. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
oneOf:
- type: integer
format: int64
nullable: false
default: 0
- type: number
format: double
nullable: false
default: 0.0
ftChargeItemCase:
type: integer
description: |
optional defines the type of service or product related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO! this is relevant for fiskaltrust middleware processing and is a country specific mapping. as fallback when not specified, a service or product delivered at the point-of-sale with defined `VATRate` is used.
format: uint64
nullable: false
default: 0
ftChargeItemCaseData:
description: |
optional gives additional details for defined type of service or product related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO!
oneOf:
- type: string
nullable: true
- type: object
additionalProperties: true
nullable: false
VATAmount:
description: |
optional when given and not null this amount is used as the (total) value added taxes amount for the line item to avoid rounding when accumulating value added taxes. systems which are using net amounts as central calculation should alsways use this property. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
nullable: true
oneOf:
- type: integer
format: int64
- type: number
format: double
default: null
Moment:
type: string
description: |
optional moment at which the serivce or product was ordered or delivered, must be provided in UTC. accumulated line items get the minimum (first) moment. if not given, the `cbReceiptMoment` is used as fallback
format: date-time
nullable: true
example: 2020-06-29T17:45:40.505Z
Position:
description: |
optional used to sort and group the line items for receipt visualization. accumulated line items get the minimum (first) position. uses `DecimalPresissionMultiplier` as discriminator between int64 and double with a specific instruction/flag in `ftReceiptCase` a grouping of multiple line items can be activated. if this is the case, `Position` is threaded as a decimal number, the whole number represents the grouped line item and the fraction part is used within the group
oneOf:
- type: integer
format: int64
nullable: false
default: 0
- type: number
format: double
nullable: false
default: 0.0
AccountNumber:
maxLength: 1023
type: string
description: |
optional account number for bookkeeping export purpose
nullable: true
CostCenter:
maxLength: 1023
type: string
description: |
optional cost center for cost accounting purpose
nullable: true
ProductGroup:
maxLength: 1023
type: string
description: |
optional product group related to line item
nullable: true
ProductNumber:
maxLength: 1023
type: string
description: |
optional product number related to line item
nullable: true
ProductBarcode:
maxLength: 1023
type: string
description: |
optional product barcode related to line item
nullable: true
Unit:
maxLength: 1023
type: string
description: |
optional unit of measurement for the line item. e.g. you have on one charging session of an electric vehicle, this would be `Quantity` 1 and the total amount of the session within `amount`. the unit of measurement could be `kW` for dc charging or `min` for ac charging.
nullable: true
UnitQuantity:
description: |
optional the quantity related to the unit of measurement defined in `Unit`. uses `DecimalPresissionMultiplier` as discriminator between int64 and double e.g. you have on one charging session of an electric vehicle, this would be `Quantity` 1 and the total amount of the session within `amount`. if the unit of measurement is `kW` for dc charging the `UnitQuantity` could be 65.4 as an example. which would mean the line item represents a charging session with a total amout of power of 65.4kW.
nullable: true
oneOf:
- type: integer
format: int64
- type: number
format: double
default: null
UnitPrice:
description: "optional the price related to the unit of measurement defined\
\ in `Unit`. uses `DecimalPresissionMultiplier` as discriminator between\
\ int64 and double e.g. you have on one charging session of an electric\
\ vehicle, this would be `Quantity` 1 and as example the total amount\
\ of 30.7 of the session within `amount`. if the unit of measurement is\
\ `kW` for dc charging the `UnitQuantity` could be 65.4 as an example\
\ and for the given total amount the `UnitPrice` would be 0.5. which would\
\ mean the line item represents a charging session with a total amout\
\ of power of 65.4kW with a price per kW of 0.5. \n"
nullable: true
oneOf:
- type: integer
format: int64
- type: number
format: double
default: null
Currency:
$ref: '#/components/schemas/CurrencyEnum'
DecimalPrecisionMultiplier:
$ref: '#/components/schemas/DecimalPrecisionMultiplierEnum'
description: |
represents a item related to a service or a product, taxable
CurrencyEnum:
type: string
description: |
used as currency code for money numbers. along ISO 4217 (https://en.wikipedia.org/wiki/ISO_4217)
nullable: false
default: EUR
enum:
- EUR
- CHF
- CZK
- HUF
- BAM
- DKK
- RON
- NOK
- PLN
- RSD
- SEK
- UAH
- USD
- AED
- AFN
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BBD
- BDT
- BGN
- BHD
- BIF
- BMD
- BND
- BOB
- BOV
- BRL
- BSD
- BTN
- BWP
- BYN
- BZD
- CAD
- CDF
- CHE
- CHW
- CLF
- CLP
- CNY
- COP
- COU
- CRC
- CUP
- CVE
- DJF
- DOP
- DZD
- EGP
- ERN
- ETB
- FJD
- FKP
- GBP
- GEL
- GHS
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HTG
- IDR
- ILS
- INR
- IQD
- IRR
- ISK
- JMD
- JOD
- JPY
- KES
- KGS
- KHR
- KMF
- KPW
- KRW
- KWD
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- LYD
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRU
- MUR
- MVR
- MWK
- MXN
- MXV
- MYR
- MZN
- NAD
- NGN
- NIO
- NPR
- NZD
- OMR
- PAB
- PEN
- PGK
- PHP
- PKR
- PYG
- QAR
- RUB
- RWF
- SAR
- SBD
- SCR
- SDG
- SGD
- SHP
- SLE
- SLL
- SOS
- SRD
- SSP
- STN
- SVC
- SYP
- SZL
- THB
- TJS
- TMT
- TND
- TOP
- TRY
- TTD
- TWD
- TZS
- UGX
- USN
- UYI
- UYU
- UYW
- UZS
- VED
- VES
- VND
- VUV
- WST
- XAF
- XAG
- XAU
- XBA
- XBB
- XBC
- XBD
- XCD
- XDR
- XOF
- XPD
- XPF
- XPT
- XSU
- XTS
- XUA
- XXX
- YER
- ZAR
- ZMW
- ZWL
DecimalPrecisionMultiplierEnum:
type: integer
description: |
is used as multiplier for decimal numbers. when value 1 is used, revlevant numbers are interpreted as floating-point numbers. for all other values, relevant numbers are interpreted as integer and need to be devided by the Multiplier to get the decimal representation.
format: int32
nullable: false
default: 1
enum:
- 1
- 100
- 10000
- 1000000
- 100000000
PayItem:
required:
- Amount
- Description
type: object
properties:
ftPayItemID:
type: string
description: |
optional used as an identifier of a chargeitem, when reading data
format: uuid
nullable: true
readOnly: true
Quantity:
description: |
defines the quantity of the line item. quantities of line items with same `Description` and itemprice (=`Amount`/`Quantity`) can be accumulated for better visualization. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
oneOf:
- type: integer
format: int64
nullable: false
default: 1
- type: number
format: double
nullable: false
default: 1.0
Description:
maxLength: 1023
type: string
description: |
defines the description of the line item. line items with same `Description` and itemprice (=`Amount`/`Quantity`) can be accumulated for better visualization
nullable: true
Amount:
description: |
defines the (total) amount of the line item. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
oneOf:
- type: integer
format: int64
nullable: false
default: 0
- type: number
format: double
nullable: false
default: 0.0
ftPayItemCase:
type: integer
description: |
optional defines the type of payment related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO! this is relevant for fiskaltrust middleware processing and is a country specific mapping. as fallback when not specified, a cah payment at the point-of-sale is used.
format: uint64
nullable: false
default: 0
ftPayItemCaseData:
description: |
optional gives additional details for defined type of payment related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO!
oneOf:
- type: string
nullable: true
- type: object
additionalProperties: true
nullable: false
Moment:
type: string
description: |
optional moment at which the payment was executed, must be provided in UTC. accumulated line items get the minimum (first) moment. if not given, the `cbReceiptMoment` is used as fallback
format: date-time
nullable: true
example: 2020-06-29T17:45:40.505Z
Position:
description: "optional used to sort and group the line items for receipt\
\ visualization. accumulated line items get the minimum (first) position.\
\ uses `DecimalPresissionMultiplier` as discriminator between int64 and\
\ double with a specific instruction/flag in `ftReceiptCase` a grouping\
\ of multiple line items can be activated. if this is the case, `Position`\
\ is threaded as a decimal number, the whole number represents the grouped\
\ line item and the fraction part is used within the group \n"
oneOf:
- type: integer
format: int64
nullable: false
default: 0
- type: number
format: double
nullable: false
default: 0.0
AccountNumber:
maxLength: 1023
type: string
description: |
optional account number for bookkeeping export purpose
nullable: true
CostCenter:
maxLength: 1023
type: string
description: |
optional cost center for cost accounting purpose
nullable: true
MoneyGroup:
maxLength: 1023
type: string
description: |
optional group related to line item
nullable: true
MoneyNumber:
maxLength: 1023
type: string
description: |
optional number related to line item
nullable: true
MoneyBarcode:
maxLength: 1023
type: string
description: |
optional barcode or serialnumber related to line item
nullable: true
Currency:
$ref: '#/components/schemas/CurrencyEnum'
DecimalPrecisionMultiplier:
$ref: '#/components/schemas/DecimalPrecisionMultiplierEnum'
description: |
represents a item related to a payment
ReceiptResponse:
required:
- ftCashBoxIdentification
- ftQueueId
- ftQueueItemId
- ftQueueRow
- ftReceiptIdentification
- ftReceiptMoment
- ftSignatures
- ftState
type: object
properties:
ftQueueID:
type: string
description: |
identification of the queue used for processing
format: uuid
nullable: false
default: 00000000-0000-0000-0000-000000000000
ftQueueItemID:
type: string
description: |
identification of the item within a specific queue used for processing
format: uuid
nullable: false
default: 00000000-0000-0000-0000-000000000000
ftQueueRow:
type: integer
description: |
row in which the item is stored within a specific queue used for processing
format: uint64
nullable: false
default: 0
ftCashBoxIdentification:
maxLength: 1023
type: string
description: |
human readable identification or serial number of the cash register related to the national regulation/law. this need to be printed on the receipt to identify the cash register within a merchant, and is unique over a single merchant. do not mix up `ftCashBoxId` with `ftCashBoxIdentification`. the `ftCashBoxId` identifies a configuration container and is used as part of authentication. the `ftCashBoxIdentification` is a human readable identification of the queue.
nullable: false
default: undefined
ftReceiptIdentification:
maxLength: 1023
type: string
description: |
human readable identification of the receipt related to the national regulation/law and the `ftCashBoxIdentification`/ Queue. this need to be printed on the receipt to identify it within a merchant and cash register. this always starts with 'ft', followed by the row number of the queue in hexadecimal, followed by '#', followed by national required or defined receipt numbering.
nullable: false
default: ft0#
ftReceiptMoment:
type: string
description: "moment at which the receipt was processed by fiskaltrust.Middleware,\
\ must be provided in UTC. this need to be printed on the receipt in local\
\ date/time. \n"
format: date-time
nullable: false
example: 2020-06-29T17:45:40.505Z
ftSignatures:
type: array
description: |
list of signature items generated by fiskaltrust.Middleware. this need to be printed on the receipt according to given format instructions to comply with national regulation/law and to enable fiskaltrust's compliance-as-a-service.
items:
$ref: '#/components/schemas/SignatureItem'
ftState:
type: integer
description: |
indicates the status of the fiskaltrust.Middleware according to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO!
format: uint64
nullable: false
default: 0
ftStateData:
description: "optional gives additional details for the status of fiskaltrust.Middleware\
\ defined type of business related to fiskaltrust reference. for detailed\
\ definition goto https://docs.fiskaltrust.eu !TODO! \
\ \n"
oneOf:
- type: string
nullable: true
- type: object
additionalProperties: true
nullable: false
ftCashBoxID:
type: string
description: |
mirror from `ReceiptRequest` identification of the cash register
format: uuid
nullable: false
default: 00000000-0000-0000-0000-000000000000
cbTerminalID:
maxLength: 1023
type: string
description: |
mirror from `ReceiptRequest` The unique identification of the input-station/terminal within a cash-register/pos-system identified by `ftCashBoxID`.
nullable: false
default: undefined
cbReceiptReference:
maxLength: 1023
type: string
description: "mirror from `ReceiptRequest` Reference number send by the\
\ cash register. This value must be a unique string/receipt number related\
\ to the calling cash register. This string/receipt number is a unique\
\ primary key of the dataset of the cash register. \n"
nullable: false
default: undefined
ftReceiptHeader:
type: array
description: |
additional header lines this need to be printed on the receipt.
items:
maxLength: 1023
type: string
nullable: false
ftChargeItems:
type: array
description: |
list of line items added by fiskaltrust.Middleware while processing the request related to services and products this need to be printed on the receipt.
items:
$ref: '#/components/schemas/ChargeItem'
ftChargeLines:
type: array
description: |
additional text for line items related to services and products this need to be printed on the receipt.
items:
maxLength: 1023
type: string
nullable: false
ftPayItems:
type: array
description: |
list of line items added by fiskaltrust.Middleware while processing the request related to payments this need to be printed on the receipt.
items:
$ref: '#/components/schemas/PayItem'
ftPayLines:
type: array
description: |
additional text for line items related to payments this need to be printed on the receipt.
items:
maxLength: 1023
type: string
nullable: false
ftReceiptFooter:
type: array
description: |
additional footer lines this need to be printed on the receipt.
items:
maxLength: 1023
type: string
nullable: false
description: |
fiskaltrust.Middleware sends back the processed data to the cash register through the receipt response. The data included in the request, such as header, service, pay items, and footer, will not be sent back. The returned data is added to the receipt as supplement to the data of the receipt request.
SignatureItem:
required:
- Data
- ftSignatureFormat
- ftSignatureType
type: object
properties:
ftSignatureItemID:
type: string
description: |
optional used as an identifier of a signautreitem, when reading data
format: uuid
nullable: true
readOnly: true
ftSignatureFormat:
type: integer
description: |
Format for displaying signature data according to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO!
format: uint64
nullable: false
default: 0
ftSignatureType:
type: integer
description: |
Type of signature according to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO!
format: uint64
default: 0
Caption:
maxLength: 1023
type: string
description: |
optional Heading, which has to be displayed as text above the signature data.
nullable: true
Data:
description: "optional Signature content which has to be displayed in the\
\ specified format. \n"
oneOf:
- type: string
nullable: true
- type: object
additionalProperties: true
nullable: false
description: |
The signature of the receipt must comply with the national law. The signature data returned in the response must be visualized on the receipt related to format instruction and to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO! The signature entries can also be used to visualize hints and messages related to the fiskaltrust.SecurityMechanism.
x-operation-callback-finalized:
description: |
single callback setting for current operation, executed once the operation is in final state, `done` or `failed`
SignRequestState:
required:
- OperationId
- State
type: object
description: |
reflects a single state event of a sign request
allOf:
- $ref: '#/components/schemas/OperationState'
- type: object
properties:
QueueItemID:
type: string
format: uuid
nullable: true
OperationState:
required:
- OperationId
- State
properties:
OperationID:
type: string
description: |
operationid
format: uuid
nullable: false
QueueID:
type: string
format: uuid
nullable: true
State:
$ref: '#/components/schemas/OperationStateEnum'
StateMessage:
type: string
nullable: true
StateData:
description: |
optional
oneOf:
- type: string
nullable: true
- type: object
additionalProperties: true
nullable: false
description: |
reflects a single state event
OperationStateEnum:
type: string
example: done
default: unknown
enum:
- pending
- processing
- done
- failed
- unknown
IssueRequest:
required:
- ReceiptRequest
- ReceiptResponse
type: object
properties:
ReceiptRequest:
$ref: '#/components/schemas/ReceiptRequest_1'
ReceiptResponse:
$ref: '#/components/schemas/ReceiptResponse_1'
additionalProperties: false
description: |
request to issue receipt
ReceiptRequest_1:
type: object
properties:
ftCashBoxID:
type: string
description: This ID is assigned by the fiskaltrust-user portal and is a
part of the authentication of the cash register.
nullable: true
ftQueueID:
type: string
description: The QueueID is required only when a load balancer is used.
The value of the ftQueueID allows the load balancer to find the correct
route to the corresponding Queue.
nullable: true
ftPosSystemId:
type: string
description: This field identifies and documents the type and software version
of the PosSystem sending the request. It is used for audits and as a base
for commission calculation. The PosSystem itself has to be created in
the portal and its ID can be implemented as a constant value by the PosCreator.
nullable: true
cbTerminalID:
type: string
description: The unique identification of the input station/ cash register
within a ftCashBoxID
nullable: true
cbReceiptReference:
type: string
description: "Reference number returned by the cash register. Ideally, this\
\ value would be a unique receipt number for the cash register, to allow\
\ saving of the return value to the cash register data set."
nullable: true
cbReceiptMoment:
type: string
description: The time of receipt creation. Must be provided in UTC.
format: date-time
cbChargeItems:
type: array
description: List of services or items sold.
nullable: true
items:
$ref: '#/components/schemas/ChargeItem_1'
cbPayItems:
type: array
description: List of payment received.
nullable: true
items:
$ref: '#/components/schemas/PayItem_1'
ftReceiptCase:
type: integer
description: Type of business transaction according to the reference table
in the appendix. It is used to choose the right processing logic.
format: int64
ftReceiptCaseData:
type: string
description: "Additional data for the business transaction, currently accepted\
\ only in JSON format. Although all string values are supported, we suggest\
\ using data structures serialized into JSON format."
nullable: true
cbReceiptAmount:
type: number
description: "Total receipt amount incl. taxes (gross receipt amount). If\
\ it is not provided, it can be calculated with the sum of the amounts\
\ of the cbChargeItems. It can be useful and important for systems working\
\ with net amounts, as it helps to apply different methods of calculation\
\ and rounding."
format: double
nullable: true
cbUser:
type: string
description: "Identification of the user, who creates the receipt. Although\
\ all string values are supported, we suggest using data structures serialized\
\ into JSON format."
nullable: true
cbArea:
type: string
description: "Identification of the section/field, in which the receipt\
\ is created. Although all string values are supported, we suggest using\
\ data structures serialized into JSON format."
nullable: true
cbCustomer:
type: string
description: "Identification of the client, for whom the receipt is created.\
\ Although all string values are supported, we suggest using data structures\
\ serialized into JSON format."
nullable: true
cbSettlement:
type: string
description: Settlement identification where this receipt will be added.
nullable: true
cbPreviousReceiptReference:
type: string
description: cbReceiptReference of the previous receipt. Used to connect
multiple requests for a single Business Case.
nullable: true
additionalProperties: false
description: The cash register transfers the data of an entire receipt request
to the fiskaltrust.Middleware using the ReceiptRequest data structure.
ChargeItem_1:
type: object
properties:
position:
type: integer
description: Line number or position number on the Receipt. Used to preserve
the order of lines on the receipt.
format: int64
quantity:
type: number
description: Amount or volume (number) of service(s) or items of the entry.
format: double
description:
type: string
description: "Name, description of customary indication, or type of the\
\ service or item."
nullable: true
amount:
type: number
description: "Gross total price of service(s). The gross individual price,\
\ net total price, and net individual price, have to be calculated using\
\ the amount and either VAT rate or VAT amount."
format: double
vatRate:
type: number
description: VAT rate as percentage.
format: double
ftChargeItemCase:
type: integer
description: Type of service or item according to the reference table in
the appendix. It is used in order to determine the processing logic for
the corresopnding business transaction.
format: int64
ftChargeItemCaseData:
type: string
description: "Additional data about the service, currently accepted only\
\ in JSON format."
nullable: true
vatAmount:
type: number
description: "If the VAT amount is indicated, it can be used to calculate\
\ the net amount in order to avoid rounding errors which are especially\
\ likely to appear in row-based net price additions."
format: double
nullable: true
accountNumber:
type: string
description: Account number for transfer into bookkeeping.
nullable: true
costCenter:
type: string
description: "Indicator for transfer into cost accounting (type, center,\
\ and payer)."
nullable: true
productGroup:
type: string
description: This value allows the customer the logical grouping of products.
nullable: true
productNumber:
type: string
description: Value used to identify the product.
nullable: true
productBarcode:
type: string
description: Product’s barcode
nullable: true
unit:
type: string
description: Unit of measurement
nullable: true
unitQuantity:
type: number
description: "Quantity of the service(s) of receipt entry, displayed in\
\ indicated units."
format: double
nullable: true
unitPrice:
type: number
description: Gross price per indicated unit.
format: double
nullable: true
moment:
type: string
description: "Time of service (year, month, day, hour, minute, second)"
format: date-time
nullable: true
additionalProperties: false
description: Charge items entries are used for receipt requests as well as for
receipt responses.
PayItem_1:
type: object
properties:
position:
type: integer
description: Line number or positionnumber on the Receipt. Used to preserve
the order of lines on the receipt.
format: int64
quantity:
type: number
description: Number of payments. This value will be set to 1 in most of
the cases. It can be greater then 1 e.g. when paying with multiple vouchers
of the same value.
format: double
description:
type: string
description: Name or description of payment.
nullable: true
amount:
type: number
description: Total amount of payment.
format: double
ftPayItemCase:
type: integer
description: Type of payment according to the reference table in the appendix.
It is used in order to determine the processing logic.
format: int64
ftPayItemCaseData:
type: string
description: "Additional data about the payment, currently accepted only\
\ in JSON format."
nullable: true
accountNumber:
type: string
description: Account number for transfer into bookkeeping.
nullable: true
costCenter:
type: string
description: "Indicator for transfer into cost accounting (type, centre\
\ and payer)"
nullable: true
moneyGroup:
type: string
description: This value allows the logical grouping of payment types.
nullable: true
moneyNumber:
type: string
description: This value identifies the payment type.
nullable: true
moment:
type: string
description: Time of payment
format: date-time
nullable: true
additionalProperties: false
description: Payment entries are used for receipt requests as well as for receipt
responses.
ReceiptResponse_1:
type: object
properties:
ftCashBoxID:
type: string
description: Allocated from request to response.
nullable: true
ftQueueID:
type: string
description: QueueId used for processing.
nullable: true
ftQueueItemID:
type: string
description: QueueItemId used for processing.
nullable: true
ftQueueRow:
type: integer
description: QueueRow used for processing.
format: int64
cbTerminalID:
type: string
description: Allocated from request to response.
nullable: true
cbReceiptReference:
type: string
description: Allocated from request to response.
nullable: true
ftCashBoxIdentification:
type: string
description: Cash register identification number.
nullable: true
ftReceiptIdentification:
type: string
description: Upcounting receipt number allocated through fiskaltrust.SecurityMechanisms.
nullable: true
ftReceiptMoment:
type: string
description: "Time of receipt processing through fiskaltrust.Middleware,\
\ provided in UTC."
format: date-time
ftReceiptHeader:
type: array
description: Additional header for the receipt. Each row can contain up
to 4096 characters. Line breaks should be inserted by the cash register
independently
nullable: true
items:
type: string
ftChargeItems:
type: array
description: "Additional data sets in the charge items block which the cash\
\ register has to print onto the receipt. By default no additional data\
\ is provided. If additional data is provided, these data sets state an\
\ amount of „0“."
nullable: true
items:
$ref: '#/components/schemas/ChargeItem_1'
ftChargeLines:
type: array
description: "Additional text line for the charge items block which the\
\ cash register has to print onto the receipt. Each row can contain up\
\ to 4096 characters, line breaks should be inserted by the cash register\
\ independently."
nullable: true
items:
type: string
ftPayItems:
type: array
description: "Additional data set in the pay items block which the cash\
\ register has to print onto the receipt. By default no additional data\
\ is provided. If additional data is provided, these data sets state an\
\ amount of „0“."
nullable: true
items:
$ref: '#/components/schemas/PayItem_1'
ftPayLines:
type: array
description: "Additional text line for the pay items block which the cash\
\ register has to print onto the receipt. Each row can contain up to 4096\
\ characters, line breaks should be inserted by the cash register independently."
nullable: true
items:
type: string
ftSignatures:
type: array
description: "Signature block, which the cash register has to print onto\
\ the receipt."
nullable: true
items:
$ref: '#/components/schemas/SignaturItem'
ftReceiptFooter:
type: array
description: "Additional footer for the receipt. Each row can contain up\
\ to 4096 characters, line breaks should be inserted by the cash register\
\ independently."
nullable: true
items:
type: string
ftState:
type: integer
description: Flag indicating the status of the fiskaltrust.Middleware; set
accordingly to the reference table in the appendix.
format: int64
ftStateData:
type: string
description: "Additional information regarding the status of the fiskaltrust.Middleware,\
\ currently accepted only in JSON format."
nullable: true
additionalProperties: false
description: The fiskaltrust.Middleware sends back the processed data to the
cash register through the receipt response.
SignaturItem:
type: object
properties:
ftSignatureFormat:
type: integer
description: Format for displaying signature data according to the reference
table in the appendix.
format: int64
ftSignatureType:
type: integer
description: "Type of signature according to the reference table in the\
\ appendix, e.g.: signature indicating a failure notification"
format: int64
caption:
type: string
description: "Heading, which has to be displayed as text above the signature\
\ data."
nullable: true
data:
type: string
description: Signature content which has to be displayed in the specified
format.
nullable: true
additionalProperties: false
description: The signature entry is only used for the receipt response.
IssueRequestSimple:
required:
- ReceiptSimple
type: object
properties:
ReceiptSimple:
$ref: '#/components/schemas/ReceiptSimple'
description: |
request to issue receipt
ReceiptSimple:
required:
- cbChargeItems
- cbPayItems
- cbReceiptMoment
- cbReceiptReference
- cbSignatureItems
- cbTerminalId
type: object
properties:
cbTerminalId:
maxLength: 1023
type: string
description: |
The unique identification of the input-station/terminal within a cash-register/pos-system identified by `ftCashBoxID`.
nullable: false
default: undefined
cbReceiptReference:
maxLength: 1023
type: string
description: |
Reference number send by the cash register. This value must be a unique string/receipt number related to the calling cash register. This string/receipt number is a unique primary key of the dataset of the cash register.
nullable: false
default: undefined
cbReceiptMoment:
type: string
description: |
moment at which the receipt was create by the cash register, must be provided in UTC.
format: date-time
nullable: false
example: 2020-06-29T17:45:40.505Z
cbChargeItems:
type: array
description: |
list of line items related to services and products
items:
$ref: '#/components/schemas/ChargeItem_2'
cbPayItems:
type: array
description: "list of line items related to payments \n"
items:
$ref: '#/components/schemas/PayItem_2'
cbSignatureItems:
type: array
description: "list of line items related to signatures \n"
items:
$ref: '#/components/schemas/SignatureItem_1'
cbReceiptHeader:
type: array
description: |
optional additional header lines to be printed on the receipt.
items:
maxLength: 1023
type: string
nullable: false
cbReceiptFooter:
type: array
description: "optional additional footer lines to be printed on the receipt.\
\ \n"
items:
maxLength: 1023
type: string
nullable: false
ftReceiptCase:
type: integer
description: |
Type of business according to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO! this is relevant for fiskaltrust middleware processing and is a country specific mapping. as fallback when not specified, a cash register business case at the point-of-sale is used.
format: uint64
nullable: false
default: 0
ftReceiptCaseData:
description: "optional gives additional details for defined type of business\
\ related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu\
\ !TODO! \n"
oneOf:
- type: string
nullable: true
- type: object
additionalProperties: true
nullable: false
cbPreviousReceiptReference:
maxLength: 1023
type: string
description: |
optional Reference `cbReceiptReference` of the previous receipt. Used to connect multiple requests for a single Business Case.
nullable: true
cbReceiptAmount:
description: |
optional total receipt amount, including value added taxes (=gross receipt amount) given to avoid calculation and rounding differences. systems which are using net amounts as central calculation should alsways use this property. if not provided, the sum of `Amount` in all provided `ftChargeItems` is used as total receipt amount. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
nullable: true
oneOf:
- type: integer
format: int64
- type: number
format: double
default: null
cbUser:
description: |
optional Identification of the user, who creates the receipt.
oneOf:
- maxLength: 1023
type: string
nullable: true
- type: object
properties:
Description:
maxLength: 1023
type: string
nullable: true
additionalProperties: true
nullable: false
default: null
cbArea:
description: |
optional Identification of the area/section/field, in which the receipt is created. e.g. Table number of a restaurant business; a department of a commercial establishment; the vehicle of a taxi company
oneOf:
- maxLength: 1023
type: string
nullable: true
- type: object
properties:
Description:
maxLength: 1023
type: string
nullable: true
additionalProperties: true
nullable: false
default: null
cbCustomer:
description: |
optional Identification of the consumer, for whom the receipt is created. e.g. Email address, phone number, personal tax number
oneOf:
- maxLength: 1023
type: string
nullable: true
- type: object
properties:
Description:
maxLength: 1023
type: string
nullable: true
additionalProperties: true
nullable: false
default: null
cbSettlement:
description: "optional Settlement identification where this receipt will\
\ be added. e.g. shift number or day of operation \n"
oneOf:
- maxLength: 1023
type: string
nullable: true
- type: object
properties:
Description:
maxLength: 1023
type: string
nullable: true
additionalProperties: true
nullable: false
default: null
ftCashBoxId:
type: string
description: |
optional identification of the cash register
format: uuid
nullable: false
default: 00000000-0000-0000-0000-000000000000
ftPosSystemId:
type: string
description: |
optional identification of the used software of the cash register
format: uuid
nullable: false
default: 00000000-0000-0000-0000-000000000000
ftQueueId:
type: string
description: |
optional routing instruction to identify a specific queue behind a load balancer or in other usecases
format: uuid
nullable: true
Currency:
$ref: '#/components/schemas/CurrencyEnum'
DecimalPrecisionMultiplier:
$ref: '#/components/schemas/DecimalPrecisionMultiplierEnum'
description: |
simplified receipt data format which can be used to issue receipts at fiskaltrust.Middleware with already given fiskalization data and without using the `sign` method to get a `ReceiptResponse` from a `ReceiptRequest` merchant onboarding and cashbox related to an outlet with a QueueEU (=European CloudCashBox) need to be done, before this can be used `ftCashBoxIdentification` is assigned by base64url(QueueId) `ftReceiptIdentification` is assigned by `ft{hex(QueueRow)}#{base64url(QueueItemId)} url is https://s.ft.ms/{base64url(QueueItemId)}
ChargeItem_2:
required:
- Amount
- Description
- Quantity
- VATRate
type: object
properties:
ChargeItemId:
type: string
description: |
optional used as an identifier of a chargeitem, when reading data
format: uuid
nullable: true
readOnly: true
Quantity:
description: |
defines the quantity of the line item. quantities of line items with same `Description`, `VATRate` and itemprice (=`Amount`/`Quantity`) can be accumulated for better visualization. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
oneOf:
- type: integer
format: int64
nullable: false
default: 1
- type: number
format: double
nullable: false
default: 1.0
Description:
maxLength: 1023
type: string
description: |
defines the description of the line item. line items with same `Description`, `VATRate` and itemprice (=`Amount`/`Quantity`) can be accumulated for better visualization
nullable: true
Amount:
description: |
defines the (total) amount of the line item. to get itemprice the amount need to be devided by quantity. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
oneOf:
- type: integer
format: int64
nullable: false
default: 0
- type: number
format: double
nullable: false
default: 0.0
VATRate:
description: |
defines the value added tax rate in percentage of the line item. line items with same `Description`, `VATRate` and itemprice (=`Amount`/`Quantity`) can be accumulated for better visualization. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
oneOf:
- type: integer
format: int64
nullable: false
default: 0
- type: number
format: double
nullable: false
default: 0.0
ftChargeItemCase:
type: integer
description: |
optional defines the type of service or product related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO! this is relevant for fiskaltrust middleware processing and is a country specific mapping. as fallback when not specified, a service or product delivered at the point-of-sale with defined `VATRate` is used.
format: uint64
nullable: false
default: 0
ftChargeItemCaseData:
description: |
optional gives additional details for defined type of service or product related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO!
oneOf:
- type: string
nullable: true
- type: object
additionalProperties: true
nullable: false
VATAmount:
description: |
optional when given and not null this amount is used as the (total) value added taxes amount for the line item to avoid rounding when accumulating value added taxes. systems which are using net amounts as central calculation should alsways use this property. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
nullable: true
oneOf:
- type: integer
format: int64
- type: number
format: double
default: null
Moment:
type: string
description: |
optional moment at which the serivce or product was ordered or delivered, must be provided in UTC. accumulated line items get the minimum (first) moment. if not given, the `cbReceiptMoment` is used as fallback
format: date-time
nullable: true
example: 2020-06-29T17:45:40.505Z
Position:
description: |
optional used to sort and group the line items for receipt visualization. accumulated line items get the minimum (first) position. uses `DecimalPresissionMultiplier` as discriminator between int64 and double with a specific instruction/flag in `ftReceiptCase` a grouping of multiple line items can be activated. if this is the case, `Position` is threaded as a decimal number, the whole number represents the grouped line item and the fraction part is used within the group
oneOf:
- type: integer
format: int64
nullable: false
default: 0
- type: number
format: double
nullable: false
default: 0.0
AccountNumber:
maxLength: 1023
type: string
description: |
optional account number for bookkeeping export purpose
nullable: true
CostCenter:
maxLength: 1023
type: string
description: |
optional cost center for cost accounting purpose
nullable: true
ProductGroup:
maxLength: 1023
type: string
description: |
optional product group related to line item
nullable: true
ProductNumber:
maxLength: 1023
type: string
description: |
optional product number related to line item
nullable: true
ProductBarcode:
maxLength: 1023
type: string
description: |
optional product barcode related to line item
nullable: true
Unit:
maxLength: 1023
type: string
description: |
optional unit of measurement for the line item. e.g. you have on one charging session of an electric vehicle, this would be `Quantity` 1 and the total amount of the session within `amount`. the unit of measurement could be `kW` for dc charging or `min` for ac charging.
nullable: true
UnitQuantity:
description: |
optional the quantity related to the unit of measurement defined in `Unit`. uses `DecimalPresissionMultiplier` as discriminator between int64 and double e.g. you have on one charging session of an electric vehicle, this would be `Quantity` 1 and the total amount of the session within `amount`. if the unit of measurement is `kW` for dc charging the `UnitQuantity` could be 65.4 as an example. which would mean the line item represents a charging session with a total amout of power of 65.4kW.
nullable: true
oneOf:
- type: integer
format: int64
- type: number
format: double
default: null
UnitPrice:
description: "optional the price related to the unit of measurement defined\
\ in `Unit`. uses `DecimalPresissionMultiplier` as discriminator between\
\ int64 and double e.g. you have on one charging session of an electric\
\ vehicle, this would be `Quantity` 1 and as example the total amount\
\ of 30.7 of the session within `amount`. if the unit of measurement is\
\ `kW` for dc charging the `UnitQuantity` could be 65.4 as an example\
\ and for the given total amount the `UnitPrice` would be 0.5. which would\
\ mean the line item represents a charging session with a total amout\
\ of power of 65.4kW with a price per kW of 0.5. \n"
nullable: true
oneOf:
- type: integer
format: int64
- type: number
format: double
default: null
Currency:
$ref: '#/components/schemas/CurrencyEnum'
DecimalPrecisionMultiplier:
$ref: '#/components/schemas/DecimalPrecisionMultiplierEnum'
description: |
represents a item related to a service or a product, taxable
PayItem_2:
required:
- Amount
- Description
type: object
properties:
PayItemId:
type: string
description: |
optional used as an identifier of a chargeitem, when reading data
format: uuid
nullable: true
readOnly: true
Quantity:
description: |
defines the quantity of the line item. quantities of line items with same `Description` and itemprice (=`Amount`/`Quantity`) can be accumulated for better visualization. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
oneOf:
- type: integer
format: int64
nullable: false
default: 1
- type: number
format: double
nullable: false
default: 1.0
Description:
maxLength: 1023
type: string
description: |
defines the description of the line item. line items with same `Description` and itemprice (=`Amount`/`Quantity`) can be accumulated for better visualization
nullable: true
Amount:
description: |
defines the (total) amount of the line item. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
oneOf:
- type: integer
format: int64
nullable: false
default: 0
- type: number
format: double
nullable: false
default: 0.0
ftPayItemCase:
type: integer
description: |
optional defines the type of payment related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO! this is relevant for fiskaltrust middleware processing and is a country specific mapping. as fallback when not specified, a cah payment at the point-of-sale is used.
format: uint64
nullable: false
default: 0
ftPayItemCaseData:
description: |
optional gives additional details for defined type of payment related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO!
oneOf:
- type: string
nullable: true
- type: object
additionalProperties: true
nullable: false
Moment:
type: string
description: |
optional moment at which the payment was executed, must be provided in UTC. accumulated line items get the minimum (first) moment. if not given, the `cbReceiptMoment` is used as fallback
format: date-time
nullable: true
example: 2020-06-29T17:45:40.505Z
Position:
description: "optional used to sort and group the line items for receipt\
\ visualization. accumulated line items get the minimum (first) position.\
\ uses `DecimalPresissionMultiplier` as discriminator between int64 and\
\ double with a specific instruction/flag in `ftReceiptCase` a grouping\
\ of multiple line items can be activated. if this is the case, `Position`\
\ is threaded as a decimal number, the whole number represents the grouped\
\ line item and the fraction part is used within the group \n"
oneOf:
- type: integer
format: int64
nullable: false
default: 0
- type: number
format: double
nullable: false
default: 0.0
AccountNumber:
maxLength: 1023
type: string
description: |
optional account number for bookkeeping export purpose
nullable: true
CostCenter:
maxLength: 1023
type: string
description: |
optional cost center for cost accounting purpose
nullable: true
MoneyGroup:
maxLength: 1023
type: string
description: |
optional group related to line item
nullable: true
MoneyNumber:
maxLength: 1023
type: string
description: |
optional number related to line item
nullable: true
MoneyBarcode:
maxLength: 1023
type: string
description: |
optional barcode or serialnumber related to line item
nullable: true
Currency:
$ref: '#/components/schemas/CurrencyEnum'
DecimalPrecisionMultiplier:
$ref: '#/components/schemas/DecimalPrecisionMultiplierEnum'
description: |
represents a item related to a payment
SignatureItem_1:
required:
- Data
- ftSignatureFormat
- ftSignatureType
type: object
properties:
SignaturItemId:
type: string
description: |
optional used as an identifier of a signautreitem, when reading data
format: uuid
nullable: true
readOnly: true
ftSignatureFormat:
type: integer
description: |
Format for displaying signature data according to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO!
format: uint64
nullable: false
default: 0
ftSignatureType:
type: integer
description: |
Type of signature according to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO!
format: uint64
default: 0
Caption:
maxLength: 1023
type: string
description: |
optional Heading, which has to be displayed as text above the signature data.
nullable: true
Data:
description: "optional Signature content which has to be displayed in the\
\ specified format. \n"
oneOf:
- type: string
nullable: true
- type: object
additionalProperties: true
nullable: false
description: |
The signature of the receipt must comply with the national law. The signature data returned in the response must be visualized on the receipt related to format instruction and to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO! The signature entries can also be used to visualize hints and messages related to the fiskaltrust.SecurityMechanism.
IssueRequestQueueItem:
required:
- QueueId
- QueueItemId
type: object
properties:
QueueID:
type: string
format: uuid
nullable: false
QueueItemID:
type: string
format: uuid
nullable: false
additionalProperties: false
description: |
request to issue receipt by queueid and queueitemid
IssueResponse:
required:
- QueueId
- QueueItemId
properties:
ftQueueID:
type: string
format: uuid
nullable: false
ftQueueItemID:
type: string
format: uuid
nullable: false
DocumentURL:
type: string
format: uri
nullable: false
DocumentContentType:
type: string
nullable: true
description: |
result of issued receipt
IssueUpdate:
required:
- Action
type: object
properties:
Action:
$ref: '#/components/schemas/IssueUpdateActionEnum'
description: |
accept receipt action [accept,view]
IssueUpdateActionEnum:
type: string
enum:
- accept
- view
- download
- print
- link
- send
- upload
IssueUpdateLink:
required:
- Action
properties:
Action:
$ref: '#/components/schemas/IssueUpdateActionEnum'
Target:
$ref: '#/components/schemas/IssueUpdateLink_Target'
Handout:
type: boolean
default: false
description: |
accept receipt action: link
IssueUpdateDownload:
required:
- Action
properties:
Action:
$ref: '#/components/schemas/IssueUpdateActionEnum'
Format:
$ref: '#/components/schemas/IssueUpdateFormatEnum'
description: |
accept receipt action [download]
IssueUpdateFormatEnum:
type: string
enum:
- text/html
- text/plain
- application/pdf
- image/png
- image/jpeg
- text/vnd.esc-pos;charset=utf-8
IssueUpdatePrint:
required:
- Action
properties:
Action:
$ref: '#/components/schemas/IssueUpdateActionEnum'
Format:
$ref: '#/components/schemas/IssueUpdateFormatEnum'
Width:
type: integer
EscPosBrand:
$ref: '#/components/schemas/IssueUpdateEscPosBrandEnum'
description: |
print receipt action [print]
IssueUpdateEscPosBrandEnum:
type: string
enum:
- none
- epson
- tousei
IssueUpdateSend:
required:
- Action
properties:
Action:
$ref: '#/components/schemas/IssueUpdateActionEnum'
Format:
$ref: '#/components/schemas/IssueUpdateFormatEnum'
Target:
$ref: '#/components/schemas/IssueUpdateSend_Target'
description: |
accept receipt action [send]
IssueUpdateUpload:
required:
- Action
properties:
Action:
$ref: '#/components/schemas/IssueUpdateActionEnum'
Format:
$ref: '#/components/schemas/IssueUpdateFormatEnum'
Filename:
type: string
Filecontent:
type: string
format: binary
description: |
accept receipt
IssueRequestState:
required:
- OperationId
- State
type: object
description: |
reflects a single state event of a issue request
allOf:
- $ref: '#/components/schemas/OperationState'
- type: object
properties:
QueueItemID:
type: string
format: uuid
nullable: true
PaymentRequest:
required:
- Action
- Protocol
- cbPayItem
type: object
properties:
Protocol:
$ref: '#/components/schemas/PaymentProtocolEnum'
Action:
$ref: '#/components/schemas/PaymentActionEnum'
cbPayItem:
$ref: '#/components/schemas/PayItem'
AcceptUnderPayment:
type: boolean
default: false
AcceptOverPayment:
type: boolean
default: true
cbTerminalID:
maxLength: 1023
type: string
description: "The unique identification of the input-station/terminal within\
\ a cash-register/pos-system identified by `ftCashBoxID`. \n"
nullable: false
default: undefined
ftCashBoxID:
type: string
description: |
identification of the cash register
format: uuid
nullable: false
default: 00000000-0000-0000-0000-000000000000
ftPosSystemID:
type: string
description: |
identification of the used software of the cash register
format: uuid
nullable: false
default: 00000000-0000-0000-0000-000000000000
PaymentProtocolEnum:
type: string
description: |
a list of supported protocols use_first can be used to use first detected payment protocol for the specific cashboxid/terminalid combination use_all triggers all available payment protocols for the specific cashboxid/terminalid combination and uses first successfull use_auto triggers a automaticaly selected, single payment protocol, best match for given PayItemCase use_none asks the customer, to select one
default: use_auto
enum:
- use_first
- use_all
- use_auto
- use_none
- bluecode
- hobex_zvt
- hobex_restapi
- hobex_softpos_posit
- gp_softpos_gptom
- gp_mpas
- gp_zvt
- payone_softpos_wpi
- payone_serverapi
- payone_fistdata
PaymentActionEnum:
type: string
description: |
a list of supported actions not each protocol supports each action
enum:
- payment
- cancel
- refund
- pre_authorization
- other
PaymentResponse:
required:
- Protocol
- ftPayItems
- ftQueueId
type: object
properties:
Protocol:
$ref: '#/components/schemas/PaymentProtocolEnum'
ftQueueID:
type: string
description: |
identification of the queue used for processing
format: uuid
nullable: false
default: 00000000-0000-0000-0000-000000000000
ftPayItems:
type: array
items:
$ref: '#/components/schemas/PayItem'
PayRequestState:
required:
- OperationId
- State
type: object
description: |
reflects as single state event of a pay request
allOf:
- $ref: '#/components/schemas/OperationState'
- type: object
properties:
PayItemID:
type: string
format: uuid
nullable: true
StorageTypeEnum:
type: string
enum:
- OperationItem
- OperationStateJournal
- PayItem
- ChargeItem
- QueueItem
- IssueItem
- ActionJournal
- ReceiptJournal
OperationItem:
required:
- LastState
- OperationId
properties:
OperationID:
type: string
description: |
operationid
format: uuid
nullable: false
Method:
type: string
Path:
type: string
Header:
type: object
Request:
type: object
Response:
type: object
LastState:
$ref: '#/components/schemas/OperationStateEnum'
description: |
reflects a single operation
issue_body:
oneOf:
- $ref: '#/components/schemas/IssueRequest'
- $ref: '#/components/schemas/IssueRequestSimple'
- $ref: '#/components/schemas/IssueRequestQueueItem'
QueueId_QueueItemId_body:
discriminator:
propertyName: Action
mapping:
accept: '#/components/schemas/IssueUpdate'
view: https://api.swaggerhub.com/domains/fiskaltrust/fiskaltrust-model/2.0#/components/schemas/IssueUpdate
download: '#/components/schemas/IssueUpdateDownload'
print: '#/components/schemas/IssueUpdatePrint'
link: '#/components/schemas/IssueUpdateLink'
send: '#/components/schemas/IssueUpdateSend'
upload: '#/components/schemas/IssueUpdateUpload'
oneOf:
- $ref: '#/components/schemas/IssueUpdate'
- $ref: '#/components/schemas/IssueUpdateLink'
- $ref: '#/components/schemas/IssueUpdateDownload'
- $ref: '#/components/schemas/IssueUpdatePrint'
- $ref: '#/components/schemas/IssueUpdateSend'
- $ref: '#/components/schemas/IssueUpdateUpload'
IssueRequest_body:
oneOf:
- $ref: '#/components/schemas/IssueRequest'
- $ref: '#/components/schemas/IssueRequestSimple'
- $ref: '#/components/schemas/IssueRequestQueueItem'
QueueId_QueueItemId_body_1:
discriminator:
propertyName: Action
mapping:
accept: '#/components/schemas/IssueUpdate'
view: https://api.swaggerhub.com/domains/fiskaltrust/fiskaltrust-model/2.0#/components/schemas/IssueUpdate
download: '#/components/schemas/IssueUpdateDownload'
print: '#/components/schemas/IssueUpdatePrint'
link: '#/components/schemas/IssueUpdateLink'
send: '#/components/schemas/IssueUpdateSend'
upload: '#/components/schemas/IssueUpdateUpload'
oneOf:
- $ref: '#/components/schemas/IssueUpdate'
- $ref: '#/components/schemas/IssueUpdateLink'
- $ref: '#/components/schemas/IssueUpdateDownload'
- $ref: '#/components/schemas/IssueUpdatePrint'
- $ref: '#/components/schemas/IssueUpdateSend'
- $ref: '#/components/schemas/IssueUpdateUpload'
inline_response_200:
discriminator:
propertyName: StorageType
mapping:
OperationItem: '#/components/schemas/OperationItem'
OperationStateJournal: '#/components/schemas/OperationState'
PayItem: '#/components/schemas/PayItem'
ChargeItem: '#/components/schemas/ChargeItem'
oneOf:
- $ref: '#/components/schemas/OperationItem'
- $ref: '#/components/schemas/OperationState'
- $ref: '#/components/schemas/PayItem'
- $ref: '#/components/schemas/ChargeItem'
inline_response_200_1:
type: object
properties:
CashBoxID:
type: string
format: uuid
AccessToken:
type: string
format: byte
IssueUpdateLink_Target:
type: object
properties:
Host:
type: string
format: uri
Path:
type: string
IssueUpdateSend_Target:
type: object
properties:
Scheme:
type: string
enum:
- email
- sms
- whatsapp
Address:
type: string
Attach:
type: string
enum:
- none
- pdf
- png
Send:
type: boolean
default: true
responses:
Unauthorized:
description: Access token is not set or invalid.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
unauthorized:
$ref: '#/components/examples/unauthorized'
ServerError:
description: The server encountered an unexpected error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
serverError:
$ref: '#/components/examples/server-error'
NotFound:
description: The requested resource was not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
notFound:
$ref: '#/components/examples/not-found'
PairResponse:
description: |
response credentials
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_200_1'
examples:
unauthorized:
value:
type: about:blank
title: Unauthorized
detail: Access token not set or invalid. The requested resource could not
be returned
status: 401
server-error:
value:
type: about:blank
title: Server Error
detail: The server encountered an unexpected error
status: 500
not-found:
value:
type: about:blank
title: Not found
detail: The requested resource was not found
status: 404
PayRequestHobexPaymentMinimum_1:
description: |
request a payment amount is EUR 1.50 chooses a payment-device assigned to `cbTerminalId` by itself
value:
Action: payment
Protocol: use_auto
cbPayItem:
Description: Card
Amount: 1.5
cbTerminalId: 1
PayRequestHobexRestApiCancelMinimum_1:
description: |
request a cancellation of an previoiuse payment protocoll comes from previouse payment depending on the payment service, the `cbTerminalId` need to be same as previouse action to cancel
value:
Action: cancel
Protocol: hobex_restapi
cbPayItem:
Description: Card
Amount: 1.5
ftPayItemCaseData:
Provider:
Protocol: hobex_restapi
Action: payment
ProtocolRequest:
transaction:
transactionType: 1
transactionId: "20181009140821075"
tid: "3510224"
currency: EUR
reference: "123"
amount: 1.5
language: DE
ProtocolResponse:
transactionId: "20181009140821075"
originalTransactionId: ""
tid: "3510224"
receipt: "632030"
approvalCode: "00884601"
reference: "123"
transactionDate: 2018-10-09T14:07:00.9436463+02:00
cardNumber: XXXXXXXXXXXX5401
cardExpiry: "1220"
brand: Maestro
cardIssuer: MAESTRO
transactionType: SELL
currency: EUR
amount: 1.5
responseCode: "0"
responseText: OK
cvm: 3
Moment: 2020-06-29T17:45:40.505Z
cbTerminalId: 1
PayRequestHobexRestApiRefundMinimum_1:
description: |
request a refund refunded (given back to the consumer) amount is EUR 1.00 chooses a payment-device assigned to `cbTerminalId` by itself
value:
Action: refund
Protocol: use_auto
cbPayItem:
Description: Card
Amount: 1.0
cbTerminalId: 1
PayRequestHobexRestApiPreAuthMinimum_1_1:
description: |
request a preauthorization authorize for an amount of EUR 12.0, and capture later EUR 7.0, and release later EUR 5.0 chooses a payment-device assigned to `cbTerminalId` by itself
value:
Action: pre_authorization
Protocol: use_auto
AcceptUnderPayment: true
cbPayItem:
Description: Card
Amount: 12.0
cbTerminalId: 1
PayRequestHobexRestApiPreAuthMinimum_1_2:
description: |
request capture of EUR 7.0 of a preauthorization
value:
Action: payment
Protocol: hobex_restapi
cbPayItem:
Description: Card
Amount: 7.0
ftPayItemCase: 14757170079003049989
ftPayItemCaseData:
Provider:
Protocol: hobex_restapi
Action: pre_authorization
ProtocolRequest:
transaction:
transactionType: 2
transactionId: "20191106143525590"
tid: "3512197"
currency: EUR
reference: "1234"
amount: 12
ProtocolResponse:
transactionId: "20191106143525590"
originalTransactionId: ""
tid: "3512197"
receipt: "527242"
approvalCode: "00168826"
reference: "1234"
transactionDate: 2019-11-06T14:35:25.5908109+01:00
cardNumber: XXXXXXXXXXXX1227
cardExpiry: "0121"
brand: MasterCard
cardIssuer: MasterCard
transactionType: PREAUTH
currency: EUR
amount: 12.0
responseCode: "0"
responseText: OK
cvm: 0
cbTerminalId: 1
PayRequestHobexRestApiPreAuthMinimum_1_3:
description: |
request cancel of EUR 5.0 of a preauthorization
value:
Action: cancel
Protocol: hobex_restapi
cbPayItem:
Description: Card
Amount: 5.0
AllowUnderPayment: true
ftPayItemCase: 14757170079003049989
ftPayItemCaseData:
Provider:
Protocol: hobex_restapi
Action: pre_authorization
ProtocolRequest:
transaction:
transactionType: 2
transactionId: "20191106143525590"
tid: "3512197"
currency: EUR
reference: "1234"
amount: 12
ProtocolResponse:
transactionId: "20191106143525590"
originalTransactionId: ""
tid: "3512197"
receipt: "527242"
approvalCode: "00168826"
reference: "1234"
transactionDate: 2019-11-06T14:35:25.5908109+01:00
cardNumber: XXXXXXXXXXXX1227
cardExpiry: "0121"
brand: MasterCard
cardIssuer: MasterCard
transactionType: PREAUTH
currency: EUR
amount: 12.0
responseCode: "0"
responseText: OK
cvm: 0
cbTerminalId: 1
PayResponseHobexRestApiPaymentMinimum_1:
description: |
response to PayRequestHobexPaymentMinimum_1
value:
Protocol: hobex_restapi
ftQueueId: 00000000-0000-0000-0000-xxxxxxxxxxxx
ftPayItems:
- ftPayItemId: 00000000-0000-0000-0000-xxxxxxxxxxxx
Description: Card
Amount: 1.5
ftPayItemCase: 14757170079003049989
ftPayItemCaseData:
Receipt:
- Line1
- Line2
- Line3
- Line4
Provider:
Protocol: hobex_restapi
Action: payment
ProtocolRequest:
transaction:
transactionType: 1
transactionId: "20181009140821075"
tid: "3510224"
currency: EUR
reference: "123"
amount: 1.5
language: DE
ProtocolResponse:
transactionId: "20181009140821075"
originalTransactionId: ""
tid: "3510224"
receipt: "632030"
approvalCode: "00884601"
reference: "123"
transactionDate: 2018-10-09T14:07:00.9436463+02:00
cardNumber: XXXXXXXXXXXX5401
cardExpiry: "1220"
brand: Maestro
cardIssuer: MAESTRO
transactionType: SELL
currency: EUR
amount: 1.5
responseCode: "0"
responseText: OK
cvm: 3
Moment: 2020-06-29T17:45:40.505Z
PayResponseHobexRestApiCancelMinimum_1:
description: |
response to PayRequestHobexCancelMinimum_1
value:
Protocol: hobex_restapi
ftQueueId: 00000000-0000-0000-0000-xxxxxxxxxxxx
ftPayItems:
- ftPayItemId: 00000000-0000-0000-0000-xxxxxxxxxxxx
Quantity: -1000
Description: Card
Amount: -1.5
ftPayItemCase: 14757170079003115525
ftPayItemCaseData:
Receipt:
- Line1
- Line2
- Line3
- Line4
Provider:
Protocol: hobex_restapi
Action: cancel
ProtocolRequest:
transactionId: "20180809152649657"
tid: "3510009"
ProtocolResponse:
transactionId: "20180918141600323"
originalTransactionId: "20180809152649657"
tid: "3510009"
receipt: "551870"
approvalCode: "230744"
reference": null
transactionDate: 2018-09-18T14:16:00.3231109+02:00
cardNumber: XXXXXXXXXXXX5401
cardExpiry: "1220"
brand: Maestro
cardIssuer: MAESTRO
transactionType: VOID
currency: EUR
amount": 1
responseCode: "0"
responseText: OK
cvm: 0
Moment: 2018-09-18T12:16:00.32Z
PayResponseHobexRestApiRefundMinimum_1:
description: |
response to PayRequestHobexRestApiRefundMinimum_1
value:
Protocol: hobex_restapi
ftQueueId: 00000000-0000-0000-0000-xxxxxxxxxxxx
ftPayItems:
- ftPayItemId: 00000000-0000-0000-0000-xxxxxxxxxxxx
Quantity: -1
Description: Card
Amount: -1.0
ftPayItemCase: 14757170079003181061
ftPayItemCaseData:
Receipt:
- Line1
- Line2
- Line3
- Line4
Provider:
Protocol: hobex_restapi
Action: cancel
ProtocolRequest:
transaction:
transactionId: "20191106143525590"
tid: "3512197"
currency: EUR
reference: "1234"
amount: 1
ProtocolResponse:
transactionId: "20191106143525590"
originalTransactionId: ""
tid: "3512197"
receipt: "527242"
approvalCode: "00168826"
reference: "1234"
transactionDate: 2019-11-06T14:35:25.5908109+01:00
cardNumber: XXXXXXXXXXXX1227
cardExpiry: "0121"
brand: MasterCard
cardIssuer: MASTERCARD
transactionType: REFUND
currency: EUR
amount: 1.0
responseCode: "0"
responseText: OK
cvm: 3
Moment: 2019-11-06T13:35:25.59Z
PayResponseHobexRestApiPreAuthMinimum_1_1:
description: |
response to PayRequestHobexRestApiPreAuthMinimum_1_1
value:
Protocol: hobex_restapi
ftQueueId: 00000000-0000-0000-0000-xxxxxxxxxxxx
ftPayItems:
- ftPayItemId: 00000000-0000-0000-0000-xxxxxxxxxxxx
Description: Card
Amount: 0
ftPayItemCase: 14757170079003049989
ftPayItemCaseData:
Receipt:
- Line1
- Line2
- Line3
- Line4
Provider:
Protocol: hobex_restapi
Action: pre_authorization
ProtocolRequest:
transaction:
transactionType: 2
transactionId: "20191106143525590"
tid: "3512197"
currency: EUR
reference: "1234"
amount: 12
ProtocolResponse:
transactionId: "20191106143525590"
originalTransactionId: ""
tid: "3512197"
receipt: "527242"
approvalCode: "00168826"
reference: "1234"
transactionDate: 2019-11-06T14:35:25.5908109+01:00
cardNumber: XXXXXXXXXXXX1227
cardExpiry: "0121"
brand: MasterCard
cardIssuer: MasterCard
transactionType: PREAUTH
currency: EUR
amount: 12.0
responseCode: "0"
responseText: OK
cvm: 0
Moment: 2019-11-06T13:35:25.59Z
PayResponseHobexRestApiPreAuthMinimum_1_2:
description: "response to PayRequestHobexRestApiPreAuthMinimum_1_2 capture of\
\ \n"
value:
Protocol: hobex_restapi
ftQueueId: 00000000-0000-0000-0000-xxxxxxxxxxxx
ftPayItems:
- ftPayItemId: 00000000-0000-0000-0000-xxxxxxxxxxxx
Description: Card
Amount: 7.0
ftPayItemCase: 14757170079003181061
ftPayItemCaseData:
Receipt:
- Line1
- Line2
- Line3
- Line4
Provider:
Protocol: hobex_restapi
Action: payment
ProtocolRequest:
transaction:
transactionId: "20191108075925144"
tid: "3512197"
currency: EUR
reference: "1234"
amount: 7.0
ProtocolResponse:
transactionId: "20191108092959089"
originalTransactionId: "20191108075925144"
tid: "3512197"
receipt: "541586"
approvalCode: "812634"
reference: "1234"
transactionDate: 2019-11-08T09:29:58.9177136+01:00
cardNumber: XXXXXXXXXXXX1227
cardExpiry: "0121"
brand: MasterCard
cardIssuer: MasterCard
transactionType: CAPTURE
currency: EUR
amount: 7.0
responseCode: "0"
responseText: OK
cvm: 0
Moment: 2019-11-08T08:29:58.91Z
PayResponseHobexRestApiPreAuthMinimum_1_3:
description: |
response to PayRequestHobexRestApiPreAuthMinimum_1_3
value:
Protocol: hobex_restapi
ftQueueId: 00000000-0000-0000-0000-xxxxxxxxxxxx
ftPayItems:
- ftPayItemId: 00000000-0000-0000-0000-xxxxxxxxxxxx
Description: Card
Amount: 0
ftPayItemCase: 14757170079003115525
ftPayItemCaseData:
Receipt:
- Line1
- Line2
- Line3
- Line4
Provider:
Protocol: hobex_restapi
Action: cancel
ProtocolRequest:
transaction:
transactionType: 7
transactionId: "20191108075925144"
tid: "3512197"
currency: EUR
reference: "1234"
amount: 5
ProtocolResponse:
transactionId: "20191108092959089"
originalTransactionId: "20191108075925144"
tid: "3512197"
receipt: "541586"
approvalCode: "812634"
reference: "1234"
transactionDate: 2019-11-08T09:29:58.9177136+01:00
cardNumber: XXXXXXXXXXXX1227
cardExpiry: "0121"
brand: MasterCard
cardIssuer: MasterCard
transactionType: VOID
currency: EUR
amount: 5.0
responseCode: "0"
responseText: OK
cvm: 0
Moment: 2019-11-08T08:29:58.91Z
requestBodies:
PairRequest:
description: |
use to get credentials for initial setup
content:
application/json:
schema:
type: object
properties:
Pin:
maxLength: 1023
type: string
securitySchemes:
CashBoxId:
type: apiKey
name: x-cashbox-id
in: header
CashBoxAccessToken:
type: apiKey
name: x-cashbox-accesstoken
in: header
callbacks:
OperationFinalized:
OperationCallbackFinalizedUrl:
post:
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OperationItem'
responses:
"200":
description: |
successfull
"201":
description: |
successfull created
default:
description: "unexpected error \n"
OperationState:
OperationCallbackStateUrl:
post:
parameters:
- name: x-operation-id
in: header
required: true
style: simple
explode: false
schema:
$ref: '#/components/schemas/x-operation-id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OperationState'
responses:
"200":
description: |
successfull
"201":
description: |
successfull created
default:
description: unexpected error