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.

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: "

example receipt

\n \"fiskaltrust\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