openapi: 3.0.0
info:
title: fiskaltrust Receipt API
description: |-
fiskaltrust provides a feature richt digital receipt implementation. Receipt visualization can be used by everyone free of charge, simply following the receipt-url. Sharing and Matching enables 3rd party apps to integrate with millions of receipts a day, processed by fiskaltrust.
API design principles
The Receipt API was designed in a RESTful and follows those design principles. The API accepts JSON data and uses standard HTTP status codes for responses. The return types can be different depending on the calls. The default return type is either HTML or JSON
Authentication
The Receipt API can be used in three different modes. End-Users that are using one of the visualizations or features via fiskaltrust can use the features without authentication. While we also allow third party applications to use most of the endpoints without actual authentication, applications must add an additional AppId header to each request. Raw data requests require the application to authenticate with `AppId` and `AppSecret`. Currently these credentials are invite-only so please reach out to hello@fiskaltrust.eu if you are interested.
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.
contact:
name: fiskaltrust
url: https://www.fiskaltrust.eu
email: hello@fiskaltrust.eu
license:
name: This documentation and samples are released under the EUPL license.
url: https://opensource.org/license/eupl
version: "1.0"
servers:
- url: https://receipts-sandbox.fiskaltrust.eu
description: Latest sandbox version
- url: https://receipts-sandbox.fiskaltrust.eu/v1
description: Sandbox
- url: https://receipts.fiskaltrust.eu/v1
description: Production
- url: https://receipts.fiskaltrust.eu
description: Latest production version
security:
- AppId: []
AppSecret: []
tags:
- name: Visualize
description: "With the endpoints for Visualize integrators can use the Receipt API\
\ to retrieve the Receipt in many different formats. Each call to one of these\
\ endpoints marks the receipt as accepted/viewed by the customer and gives the\
\ merchant the chance to have trace information on when the receipts have been\
\ received by their customers.
While integrators can make use of the\
\ digital receipt including the tracking of the customer retrieval without authentication,\
\ it is required that applications that are using the digital receipt visualization\
\ in one or the other form to add an additional Query Parameter `AppId`. This\
\ `AppId` can be requested via the __fiskaltrust.Portal__. When using endpoints\
\ with the `AppId` included the receipt is not marked as accepted/viewed. \n"
- name: Share
description: |
use receipt content in 3rd party apps AppId is used in authentication. AppId can be claimed at fiskaltrust.Portal
- name: Example
description: " \n
\n
\n"
paths:
/:
get:
tags:
- Visualize
summary: Visualize Digital Receipt for Give Away
description: "This endpoint returns the visualization for a receipt that has\
\ been linked to the Give Away. Calling this endpoint marks the receipt as\
\ accepted/viewed.
\n
\nVisit example receipt \
\ \n"
parameters:
- name: c
in: query
description: "Base64Url identifier \n"
required: true
style: form
explode: true
schema:
type: string
format: byte
- name: s1
in: query
description: "signature with key number 1 \n"
required: false
style: form
explode: true
schema:
type: string
format: byte
- name: s2
in: query
description: "signature with key number 2 \n"
required: false
style: form
explode: true
schema:
type: string
format: byte
- name: f
in: query
description: "featureset \n"
required: false
style: form
explode: true
schema:
type: string
format: byte
- name: mcc
in: query
description: |
marketing campaign code. influence visualization of empty / non assigned codes
required: false
style: form
explode: true
schema:
type: string
- name: AppId
in: query
description: |
When an `AppId` is provided then the 3rd party app redirect is disabled. 3rd party apps are required to show a link to original fiskaltrust receipt when they show more details than `ftReceiptIdentification`, date/time and total amount. using the `AppId` parameter, will also not mark the receipt as accepted/viewed.
required: false
style: form
explode: true
schema:
type: string
format: uuid
responses:
"200":
description: |
Success
content:
text/html:
schema:
type: string
image/png:
schema:
type: string
format: byte
application/pdf:
schema:
type: string
format: byte
"301":
description: |
Redirect to digital receipt information, if receipt is not found Redirect to 3rd party application
"500":
description: |
Internal error
security: []
/{QueueId}/{QueueItemId}:
get:
tags:
- Visualize
summary: Visualize the digital receipt
description: "This endpoint returns the visualization for a receipt with the\
\ global unique identifier and marks the receipt as accepted/viewed (by human\
\ user). By using different values for the `Accept` header callers can retrieve\
\ different formats.\n
\nVisit a example receipt\n"
parameters:
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
example: 9330c645-e838-4b65-b77c-0ab6583d5e80
- name: QueueItemId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
example: 8fb08828-3f08-4622-8ba7-363552a5a5c0
- name: AppId
in: query
description: |
When an `AppId` is provided then the 3rd party app redirect is disabled. 3rd party apps are required to show a link to original fiskaltrust receipt when they show more details than `ftReceiptIdentification`, date/time and total amount. using the `AppId` parameter, will also not mark the receipt as accepted/viewed.
required: false
style: form
explode: true
schema:
type: string
format: uuid
responses:
"200":
description: |
Success
content:
text/*:
schema:
type: string
image/*:
schema:
type: string
format: byte
application/pdf:
schema:
type: string
format: byte
"301":
description: |
Redirect to digital receipt information, if receipt is not found Redirect to 3rd party application, when redirect feature is configured same as share button &fiskaltrustReceiptUri=...
"404":
description: |
Not found
"500":
description: |
Internal error
callbacks:
ShareButton:
$ref: '#/components/callbacks/ShareButton'
security: []
put:
tags:
- Share
summary: Execute actions on a shared receipt
description: |
Get raw data of a receipt or executes a specific action with the receipt. Leaves a note, which application claimed the raw data.
parameters:
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
example: 9330c645-e838-4b65-b77c-0ab6583d5e80
- name: QueueItemId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
example: 8fb08828-3f08-4622-8ba7-363552a5a5c0
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueueId_QueueItemId_body'
responses:
"200":
description: |
(OK) Success action: accept => application/json action: download, print
content:
text/*:
schema:
type: string
application/pdf:
schema:
type: string
format: binary
image/*:
schema:
type: string
format: binary
application/json:
schema:
type: object
"201":
description: |
(Created) Success action: send, upload fire and forget send to e-mail fire and forget upload to file-share
"204":
description: |
(No Content) Success action: accept, view
"401":
description: |
Unauthorized
"404":
description: |
Not found
"500":
description: |
Internal error
/{QueueId}/{QueueItemId}/link/qrcode:
get:
tags:
- Visualize
summary: Provides the link to the digital receipt as QRCode
description: |
Provides the link to the digital receipt as QRCode that can be scanned with a Smartphone to retrieve the digital receipt. This endpoint can be used by systems to easily visualize the link in a convenient form.
parameters:
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
- name: QueueItemId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
responses:
"200":
description: |
Success
content:
image/png:
schema:
type: string
format: byte
"404":
description: |
Not found
"500":
description: |
Internal error
security: []
/{QueueId}/{QueueItemId}/png:
get:
tags:
- Visualize
summary: Provides the visualization of the digital receipt as `PNG`
description: |
This endpoint returns the PNG visualization for a receipt with the global unique identifier and marks the receipt as accepted/viewed (by human user). By using different values for the `Accept` header callers can retrieve different formats.
An example of an integration could be a HTML
tag:
```
```
parameters:
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
- name: QueueItemId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
- name: AppId
in: query
description: |
When an `AppId` is provided then the 3rd party app redirect is disabled. 3rd party apps are required to show a link to original fiskaltrust receipt when they show more details than `ftReceiptIdentification`, date/time and total amount. using the `AppId` parameter, will also not mark the receipt as accepted/viewed.
required: false
style: form
explode: true
schema:
type: string
format: uuid
responses:
"200":
description: |
Success
content:
image/png:
schema:
type: string
format: byte
"301":
description: |
redirect to 3rd party application (/png path in QueueId/QueueItemId parameter case), when redirect feature is configured same as share button &fiskaltrustReceiptUri=...
"404":
description: |
Not found
"500":
description: |
Internal error
security: []
/{QueueId}/{QueueItemId}/pdf:
get:
tags:
- Visualize
summary: 'Provides the visualization of the digital receipt as `PDF`. '
description: |
This endpoint returns the PDF visualization for a receipt with the global unique identifier and marks the receipt as accepted/viewed (by human user). By using different values for the `Accept` header callers can retrieve different formats.
Example PDF download
parameters:
- name: QueueId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
- name: QueueItemId
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
- name: AppId
in: query
description: |
When an `AppId` is provided then the 3rd party app redirect is disabled. 3rd party apps are required to show a link to original fiskaltrust receipt when they show more details than `ftReceiptIdentification`, date/time and total amount. using the `AppId` parameter, will also not mark the receipt as accepted/viewed.
required: false
style: form
explode: true
schema:
type: string
format: uuid
responses:
"200":
description: |
Success
content:
application/pdf:
schema:
type: string
format: byte
"301":
description: |
redirect to 3rd party application (/pdf path in QueueId/QueueItemId parameter case), when redirect feature is configured same as share button &fiskaltrustReceiptUri=...
"404":
description: |
Not found
"500":
description: |
Internal error
security: []
components:
schemas:
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
QueueId_QueueItemId_body:
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'
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
securitySchemes:
AppId:
type: apiKey
name: X-App-Id
in: header
AppSecret:
type: apiKey
name: X-App-Secret
in: header
callbacks:
ShareButton:
AppShareButtonUrl:
get:
parameters:
- name: fiskaltrustReceiptUri
in: query
required: true
style: form
explode: true
schema:
type: string
example: https://receipts-sandbox.fiskaltrust.eu/9330c645-e838-4b65-b77c-0ab6583d5e80/8fb08828-3f08-4622-8ba7-363552a5a5c0
responses:
"200":
description: |
Success
default:
description: |
unexpected error