Skip to main content
API docs by Redocly

fiskaltrust PosDealer API (0.0)

Download OpenAPI specification:Download

fiskaltrust: hello@fiskaltrust.eu License: This documentation and samples are released under the MIT license.

This API provides functionalities for PosDealers to onboard PosOperators and configure and rollout their Middleware installations.

All operations that the PosDealer API offers are also available in the fiskaltrust.Portal, if you prefer to use a graphical user interface over this API.

API design principles

The PosDealer API was designed in a RESTful and follows those design principles. The API accepts and returns JSON data and uses standard HTTP status codes for responses.

Authentication

The PosDealer API can only be used with the access data of a PosDealer. These credentials can be found on the fiskaltrust.Portal in the API Access section of your account profile.
You will need both AccountId and AccessToken to use this API. These values can be obtained from the fiskaltrust.Portal only; access data will not be sent via, e.g., E-Mail by fiskaltrust.

Please note that you can change the AccessToken of your account (Company / Overview / Reset), e.g., if your credentials got leaked. The AccountId is unchangeable.

If you face authorization problems, check your account's assigned roles in fiskaltrust.Portal (Company / Overview) and ensure you have the appropriate permissions to access the account of your PosOperator.

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.

Create and manage Outlets

List outlets of a PosOperator

This request lists all outlets of the PosOperator (i.e. the merchant) that is specified in the URL by their respective account ID.
Account IDs of connected PosOperators can either be obtained via the /api/posoperators endpoint, or via fiskaltrust's Portal.

Please note:

  • While outlets have unique GUIDs, this API heavily uses the numeric outlet number to be closer to the workflows established in the Portal.
  • The outlet number 2 is reserved for internal usage and can neither be obtained nor edited.

path Parameters
posOperatorId
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new outlet in the account of a PosOperator

This request creates a new outlet in the account of a PosOperator (i.e. a merchant) that is specified in the URL by their respective account ID.
Account IDs of connected PosOperators can either be obtained via the /api/posoperators endpoint, or via fiskaltrust's Portal.

Please note:

  • While outlets have unique GUIDs, this API heavily uses the numeric outlet number to be closer to the workflows established in the Portal.
  • The outlet number 2 is reserved for internal usage and can neither be obtained nor edited.

path Parameters
posOperatorId
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
required
locationId
string or null

The location ID can be used to e.g. track merchant-internal IDs of locations, and is also used to store the SIRET number for French merchants.

outletNumber
integer or null <int32> [ 3 .. 2147483647 ]

The unique numeric identifier of an outlet. If not included in the request, the next available number will be assigned.

name
required
string [ 1 .. 200 ] characters

The name of the outlet, e.g. "Main Store" or "Outlet 1".

address
required
string [ 1 .. 250 ] characters

The address of the outlet (street, house number, etc.).

contactName
string or null <= 150 characters

The name of the contact person at the outlet.

telephone
string or null <= 50 characters

The telephone number of the outlet.

fax
string or null <= 50 characters

The fax number of the outlet.

postalCode
required
string [ 1 .. 20 ] characters

The postal code of the outlet (may consist of numbers and characters in some countries).

city
required
string [ 1 .. 80 ] characters

The city of the outlet.

county
string or null <= 50 characters

The county of the outlet, if applicable.

stateOrProvince
string or null <= 50 characters

The state or province of the outlet, if applicable.

country
required
string = 2 characters

The country of the outlet in ISO 3166-1 alpha-2 format (e.g. "IT" or "AT").

Responses

Request samples

Content type
application/json
{
  • "locationId": "string",
  • "outletNumber": 3,
  • "name": "string",
  • "address": "string",
  • "contactName": "string",
  • "telephone": "string",
  • "fax": "string",
  • "postalCode": "string",
  • "city": "string",
  • "county": "string",
  • "stateOrProvince": "string",
  • "country": "st"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "locationId": "string",
  • "outletNumber": 0,
  • "name": "string",
  • "address": "string",
  • "contactName": "string",
  • "telephone": "string",
  • "fax": "string",
  • "postalCode": "string",
  • "city": "string",
  • "county": "string",
  • "stateOrProvince": "string",
  • "country": "string"
}

Get a specific outlet of a PosOperator

This request returns a specific outlets of the PosOperator (i.e. the merchant) that is specified in the URL by their respective account ID.
Account IDs of connected PosOperators can either be obtained via the /api/posoperators endpoint, or via fiskaltrust's Portal.

Please note:

  • While outlets have unique GUIDs, this API heavily uses the numeric outlet number to be closer to the workflows established in the Portal.
  • The outlet number 2 is reserved for internal usage and can neither be obtained nor edited.

path Parameters
posOperatorId
required
string <uuid>
outletNumber
required
integer <int32>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "locationId": "string",
  • "outletNumber": 0,
  • "name": "string",
  • "address": "string",
  • "contactName": "string",
  • "telephone": "string",
  • "fax": "string",
  • "postalCode": "string",
  • "city": "string",
  • "county": "string",
  • "stateOrProvince": "string",
  • "country": "string"
}

Update an outlet of a PosOperator

This request updates a specific outlets of the PosOperator (i.e. the merchant) that is specified in the URL by their respective account ID. As this is a PUT and not a PATCH endpoint, existing data is overwritten; make sure to pass all properties in each call.
Account IDs of connected PosOperators can either be obtained via the /api/posoperators endpoint, or via fiskaltrust's Portal.

Please note:

  • While outlets have unique GUIDs, this API heavily uses the numeric outlet number to be closer to the workflows established in the Portal.
  • The outlet number 2 is reserved for internal usage and can neither be obtained nor edited.

path Parameters
posOperatorId
required
string <uuid>
outletNumber
required
integer <int32>
header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
required
locationId
string or null
name
required
string [ 1 .. 200 ] characters

The name of the outlet, e.g. "Main Store" or "Outlet 1".

address
required
string [ 1 .. 250 ] characters

The address of the outlet (street, house number, etc.).

contactName
string or null <= 150 characters

The name of the contact person at the outlet.

telephone
string or null <= 50 characters

The telephone number of the outlet.

fax
string or null <= 50 characters

The fax number of the outlet.

postalCode
required
string [ 1 .. 20 ] characters

The postal code of the outlet (may consist of numbers and characters in some countries).

city
required
string [ 1 .. 80 ] characters

The city of the outlet.

county
string or null <= 50 characters

The county of the outlet, if applicable.

stateOrProvince
string or null <= 50 characters

The state or province of the outlet, if applicable.

country
required
string = 2 characters

The country of the outlet in ISO 3166-1 alpha-2 format (e.g. "IT" or "AT").

Responses

Request samples

Content type
application/json
{
  • "locationId": "string",
  • "name": "string",
  • "address": "string",
  • "contactName": "string",
  • "telephone": "string",
  • "fax": "string",
  • "postalCode": "string",
  • "city": "string",
  • "county": "string",
  • "stateOrProvince": "string",
  • "country": "st"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "locationId": "string",
  • "outletNumber": 0,
  • "name": "string",
  • "address": "string",
  • "contactName": "string",
  • "telephone": "string",
  • "fax": "string",
  • "postalCode": "string",
  • "city": "string",
  • "county": "string",
  • "stateOrProvince": "string",
  • "country": "string"
}

Create CashBoxes

Execute a template to create a CashBox

This endpoint executes a CashBox template in a PosOperator's (i.e. merchant's) account.
Templates can be used to create re-usable CashBox configurations, and either create new components or put already existing components (i.e. SCUs) into the defined CashBox.

More details about how to build templates can be found in our documentation.

path Parameters
posOperatorId
required
string <uuid>
query Parameters
outlet_number
required
string
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
{
  • "cashBoxId": "2c22d41c-9df5-4697-bf08-a52c3ca019d5",
  • "accessToken": "string",
  • "configuration": {
    }
}

Invite and manage PosOperators

List connected PosOperators

This endpoint lists all PosOperators (i.e. merchants) that are connected to the PosDealer specified by the accountId header.
For performance the list is served from a short-lived cache (up to 60 seconds old) by default; changes you make through this API (e.g. auto-invite) are reflected immediately. Pass useCache=false to bypass the cache and read the current list directly from Dynamics.
Please note that only active connections (i.e. connections that the PosOperator has accepted) are returned in this version of the API.

query Parameters
useCache
boolean
Default: true
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Invite a new PosOperator

This endpoint invites a new PosOperator (i.e. merchant) to fiskaltrust's Portal and connects them to the PosDealer's account that is specified by the accountId header.
After the request has completed, the PosOperator will receive an email with further instructions to activate their account.

header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
required
required
object (Company)
required
object (Contact)
accessRights
required
string (AccessRights)
Enum: "Undefined" "None" "Read" "ReadWrite" "Full"
object (InvitationDetails)

Responses

Request samples

Content type
application/json
{
  • "company": {
    },
  • "primaryContact": {
    },
  • "accessRights": "Undefined",
  • "details": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "line1": "string",
  • "country": "string",
  • "postalCode": "string",
  • "city": "string",
  • "eMailAddress": "string",
  • "identifiers": {
    }
}

Get connected PosOperator

This request returns a specific PosOperator (i.e. the merchant), that is specified in the URL by their respective account ID, if it is connected to the PosDealer specified by the accountId header.
Please note that only active connections (i.e. connections that the PosOperator has accepted) are returned in this version of the API.

path Parameters
posOperatorId
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "line1": "string",
  • "country": "string",
  • "postalCode": "string",
  • "city": "string",
  • "eMailAddress": "string",
  • "identifiers": {
    }
}

Auto-invite a new PosOperator

This endpoint auto-invites a new PosOperator (i.e. merchant) to fiskaltrust's Portal and connects them to the PosDealer's account that is specified by the accountId header.
After the request has completed, the PosOperator account will be automatically created and connected.

header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
required
required
object (Company)
required
object (Contact)
accessRights
required
string (AccessRights)
Enum: "Undefined" "None" "Read" "ReadWrite" "Full"
object (InvitationDetails)

Responses

Request samples

Content type
application/json
{
  • "company": {
    },
  • "primaryContact": {
    },
  • "accessRights": "Undefined",
  • "details": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "line1": "string",
  • "country": "string",
  • "postalCode": "string",
  • "city": "string",
  • "eMailAddress": "string",
  • "identifiers": {
    }
}

Update company master data (DE only)

This endpoint updates the master data for a company, specifically the information required for the notification-sending operation.

path Parameters
posOperatorId
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
required
taxNumber
string or null
object (UpdateCompanyAddress)

Responses

Request samples

Content type
application/json
{
  • "taxNumber": "string",
  • "address": {
    }
}

Response samples

Content type
application/json
"string"

Pos Operator Invitation Management

List pending PosOperator invitations

This endpoint lists all pending (i.e. not yet submitted to the Portal) PosOperator invitations for the PosDealer account specified by the accountId header.
Invitations can be created individually via POST /api/pos-operators-invitation or in bulk via the CSV import endpoint, and submitted later via the PosOperator endpoints.

Please note that completed invitations are not returned here; use GET /api/pos-operators-invitation/history instead.

header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new PosOperator invitation

This endpoint creates a new PosOperator invitation for the PosDealer account specified by the accountId header.
The invitation is only saved — it is not yet submitted to the Portal. Use the /api/posoperators endpoint to submit an invitation immediately instead.

Please note:

  • The contact e-mail address must be unique per account; a 409 is returned if an invitation with the same contact e-mail already exists.
  • Required fields are validated server-side, and a 400 with details is returned on validation errors.

header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
required
required
object (InvitationCompany)
required
object (InvitationContact)
accessRights
string (AccessRights)
Enum: "Undefined" "None" "Read" "ReadWrite" "Full"

Responses

Request samples

Content type
application/json
{
  • "company": {
    },
  • "contact": {
    },
  • "accessRights": "Undefined"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "company": {
    },
  • "contact": {
    },
  • "accessRights": "Undefined",
  • "done": "2019-08-24T14:15:22Z",
  • "resultContactId": "ed9f1128-5488-4a43-a3c3-f78c573de0d2",
  • "resultAccountId": "9045389d-ddc0-4cea-94e0-8d5064070eb2",
  • "success": true
}

Get PosOperator invitation history

This endpoint returns the completed (i.e. already processed) PosOperator invitations for the PosDealer account specified by the accountId header.
The result can optionally be narrowed down by passing the from and to query parameters (ISO-8601 date-time, inclusive).

Please note that at most 50 results are returned per request.

query Parameters
from
string <date-time>
to
string <date-time>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a PosOperator invitation

This endpoint returns the company and contact details of a single invitation, identified by its id in the URL, for the PosDealer account specified by the accountId header.

Please note that a 404 is returned if the invitation does not exist or does not belong to the requesting account.

path Parameters
id
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "company": {
    },
  • "contact": {
    },
  • "accessRights": "Undefined",
  • "done": "2019-08-24T14:15:22Z",
  • "resultContactId": "ed9f1128-5488-4a43-a3c3-f78c573de0d2",
  • "resultAccountId": "9045389d-ddc0-4cea-94e0-8d5064070eb2",
  • "success": true
}

Update a PosOperator invitation

This endpoint updates the company and contact details of an invitation, identified by its id in the URL, for the PosDealer account specified by the accountId header.
As this is a PUT and not a PATCH endpoint, existing data is overwritten; make sure to pass all properties in each call.

Please note:

  • A 404 is returned if the invitation does not exist or does not belong to the requesting account.
  • If the contact e-mail address is changed to one that is already used by another invitation, a 409 is returned.

path Parameters
id
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
required
required
object (InvitationCompany)
required
object (InvitationContact)
accessRights
string (AccessRights)
Enum: "Undefined" "None" "Read" "ReadWrite" "Full"

Responses

Request samples

Content type
application/json
{
  • "company": {
    },
  • "contact": {
    },
  • "accessRights": "Undefined"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "company": {
    },
  • "contact": {
    },
  • "accessRights": "Undefined",
  • "done": "2019-08-24T14:15:22Z",
  • "resultContactId": "ed9f1128-5488-4a43-a3c3-f78c573de0d2",
  • "resultAccountId": "9045389d-ddc0-4cea-94e0-8d5064070eb2",
  • "success": true
}

Delete a PosOperator invitation

This endpoint removes an invitation, identified by its id in the URL, for the PosDealer account specified by the accountId header.

Please note that only pending invitations can be deleted: a 409 is returned for an already-processed invitation (retained for history), and a 404 if the invitation does not exist or does not belong to the requesting account.

path Parameters
id
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
{
  • "Message": "string"
}

Submit a PosOperator invitation

This endpoint submits a previously created invitation, identified by its id in the URL, to fiskaltrust's Portal for the account specified by the accountId header.
The Portal creates the PosOperator's account, contact and connection and sends the invitation e-mail; the record is then stamped with the result and marked completed.

Please note:

  • The configured access rights of the invitation are used as the connection claims.
  • A 409 is returned if the invitation was already processed (recover it first to re-submit) or the contact e-mail is already in use.

path Parameters
id
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
null

Auto-submit a PosOperator invitation

This endpoint auto-submits a previously created invitation, identified by its id in the URL, to fiskaltrust's Portal for the account specified by the accountId header.
Unlike the standard submit, the PosOperator account is created and connected automatically without requiring the merchant to confirm their e-mail.

Please note that auto-invitation only works for new accounts; a 409/400 is returned if a matching account already exists or the invitation was already processed.

path Parameters
id
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
null

Recover a completed PosOperator invitation

This endpoint resets a completed invitation, identified by its id in the URL, back to pending for the account specified by the accountId header.
Only the completion flag is cleared so the invitation returns to the pending list and can be edited and submitted again; the previous run details (last run, last result and result IDs) are retained as an audit trail.

path Parameters
id
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "company": {
    },
  • "contact": {
    },
  • "accessRights": "Undefined",
  • "done": "2019-08-24T14:15:22Z",
  • "resultContactId": "ed9f1128-5488-4a43-a3c3-f78c573de0d2",
  • "resultAccountId": "9045389d-ddc0-4cea-94e0-8d5064070eb2",
  • "success": true
}

Bulk import PosOperator invitations from CSV

This endpoint creates multiple PosOperator invitations at once for the PosDealer account specified by the accountId header, by uploading a single semicolon-separated .csv file.
Download the expected template, including the correct column headers, via GET /api/pos-operators-invitation/import/csv/template.

Please note:

  • The CSV header must exactly match the template; otherwise a 400 is returned.
  • Each row is validated individually; if any row fails validation, the whole import is rejected with a 400 describing the offending lines.
  • Rows whose contact e-mail already has an invitation are skipped and reported in the Skipped result list.

header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: multipart/form-data
file
required
string <binary>

Responses

Response samples

Content type
application/json
null

Download CSV import template

This endpoint returns a semicolon-separated .csv template file containing the correct column headers expected by the bulk invitation import endpoint (POST /api/pos-operators-invitation/import/csv).
Fill in one invitation per row, then upload the completed file to create the invitations.

header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
"string"

Upload invitation PDF document

This endpoint stores a single .pdf document for the PosDealer account specified by the accountId header.
The stored document is attached to the invitation e-mails sent for this account.

Please note that uploading a new document overwrites any previously stored one, and a 400 is returned if the uploaded file is not a .pdf.

header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: multipart/form-data
file
required
string <binary>

Responses

Response samples

Content type
application/json
null

Download invitation PDF document

This endpoint returns the .pdf document currently stored for the PosDealer account specified by the accountId header.

Please note that a 404 is returned if no PDF document has been uploaded for this account.

header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
"string"

Delete invitation PDF document

This endpoint removes the .pdf document stored for the PosDealer account specified by the accountId header.

Please note that the operation is idempotent — it succeeds even if no document is currently stored for the account.

header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
null

Produce products based on entitlements

List available entitlements

This endpoint lists the active entitlements that are available for the given PosDealer in their respective market.
These entitlements are consumed when rollout plans are executed, and converted into products and subscriptions for conencted PosOperators (i.e. merchants) (for more details, refer to "Produce a product based on a rollout plan").

Please note:

  • Entitlements cannot be obtained via this API. The PosDealer API currently does not support any operations that cause monetary transactions; those should be done via the Portal, after obtaining a volume purchase agreement. Please reach out to our sales team for further information.
  • For testing purposes, entitlements can be obtained for free in the Portal's shop in the sandbox, without requiring any payments.
  • More details about the buy & resell process can be found in our documnetation.

header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Produce a queue product based on a rollout plan

This endpoint executes the specified rollout plan in a PosOperator's (i.e. merchant's) account, consuming entitlements from the PosDealer's account.
Executing a rollout plan will create a specific yearly subscription, e.g. for a carefree bundle. These subscriptions are assigned to a Queue (e.g. for the PosArchive standalone product).
The Queue IDs need to be specified correctly in the body of this request.
Details about the rollout plans can be obtained via the /api/rollout-plans endpoint; the rolloutType property specifies if the target of the plan is either an outlet or a Queue.

Please note:

  • This endpoint only works with "move entitlement"-based rollout plans, i.e. those for which the PosDealer needs to obtain entitlements up-front. The PosDealer API currently does not support any operations that cause monetary transactions; those should be done via the Portal, after obtaining a volume purchase agreement. Please reach out to our sales team for further information.
  • For testing purposes, entitlements can be obtained for free in the Portal's shop in the sandbox, without requiring any payments.
  • More details about the buy & resell process can be found in our documnetation.

path Parameters
posOperatorId
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
required
rolloutPlanNumber
string or null

The rollout plan number, e.g. "4445-12345"

queueIds
Array of strings or null <uuid> [ items <uuid > ]

The list of Queue IDs the rollout plan will be applied to. An entitlement will be consumed for each Queue.

Responses

Request samples

Content type
application/json
{
  • "rolloutPlanNumber": "string",
  • "queueIds": [
    ]
}

Response samples

Content type
application/json
{
  • "orderNumber": "string"
}

Produce an outlet product based on a rollout plan

This endpoint executes the specified rollout plan in a PosOperator's (i.e. merchant's) account, consuming entitlements from the PosDealer's account.
Executing a rollout plan will create a specific yearly subscription, e.g. for a carefree bundle. These subscriptions are assigned to an outlet (e.g. for the carefree bundle).
The outlet numbers need to be specified correctly in the body of this request.
Details about the rollout plans can be obtained via the /api/rollout-plans endpoint; the rolloutType property specifies if the target of the plan is either an outlet or a Queue.

Please note:

  • This endpoint only works with "move entitlement"-based rollout plans, i.e. those for which the PosDealer needs to obtain entitlements up-front. The PosDealer API currently does not support any operations that cause monetary transactions; those should be done via the Portal, after obtaining a volume purchase agreement. Please reach out to our sales team for further information.
  • For testing purposes, entitlements can be obtained for free in the Portal's shop in the sandbox, without requiring any payments.
  • More details about the buy & resell process can be found in our documnetation.

path Parameters
posOperatorId
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
required
rolloutPlanNumber
string or null

The rollout plan number, e.g. "4445-12345"

outletNumbers
Array of integers or null <int32> [ items <int32 > ]

The list of outlet numbers the rollout plan will be applied to. An entitlement will be consumed for each Queue.

Responses

Request samples

Content type
application/json
{
  • "rolloutPlanNumber": "string",
  • "outletNumbers": [
    ]
}

Response samples

Content type
application/json
{
  • "Message": "string"
}

Read Middleware configurations

List Queues of a PosOperator

This request lists all Queues of the PosOperator (i.e. the merchant) that is specified in the URL by their respective account ID.
Account IDs of connected PosOperators can either be obtained via the /api/posoperators endpoint, or via fiskaltrust's Portal.

path Parameters
posOperatorId
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Queue data (DE only)

This endpoint partially updates the queue data. Information related to cash register notifications can be updated. The endpoint is only available in Germany.

path Parameters
posOperatorId
required
string <uuid>
queueId
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
required
purchaseDate
string or null <date-time>
commissioningDate
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "purchaseDate": "2019-08-24T14:15:22Z",
  • "commissioningDate": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
"string"

Get queue of a posoperator (DE only)

This endpoint returns data for a specific Queue(DE) of the PosOperator. The endpoint is only available in Germany.

path Parameters
posOperatorId
required
string <uuid>
queueId
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "cashBoxId": "2c22d41c-9df5-4697-bf08-a52c3ca019d5",
  • "outletNumber": 0,
  • "description": "string",
  • "packageName": "string",
  • "packageVersion": "string",
  • "startMoment": "2019-08-24T14:15:22Z",
  • "stopMoment": "2019-08-24T14:15:22Z",
  • "commissioningDate": "2019-08-24T14:15:22Z",
  • "purchaseDate": "2019-08-24T14:15:22Z"
}

Prepare an SCU switch (DE only)

Performs all backend ("presetup") steps to switch a Queue to a new, already-existing SCU/TSE: it adds the SCU to the CashBox (unless addToCashBox=false), connects it to the Queue (a two-step switch when the Queue is already active, otherwise a direct assignment), and rebuilds the configuration. The target SCU must already exist and be assigned to the same outlet. When the Queue is already active, the switch is completed by the POS sending the Daily-Closing, Initiate-SCU-Switch and Finish-SCU-Switch receipts; this endpoint does not remove the old SCU. Available in Germany (DE) only.

path Parameters
posOperatorId
required
string <uuid>
queueId
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
required
targetScuId
string <uuid>

The already-existing SCU (the new TSE) that the Queue should switch to.

addToCashBox
boolean

Also add the target SCU to the CashBox before linking it to the Queue. Default true. Set to false when the SCU is already a member of the CashBox (e.g. it was added separately).

rebuild
boolean

Publish the CashBox configuration (Helipad rebuild) after linking. Default true. When false, the configuration must be rebuilt separately before the switch takes effect.

triggerCloudRestart
boolean

If true, ask a cloud-hosted CashBox to reload its configuration immediately (empty echo). For locally hosted middleware this has no effect — restarting it is a local/POS action. Best-effort: a failure here does not fail the switch. Default false.

Responses

Request samples

Content type
application/json
{
  • "targetScuId": "02f03f29-07db-4383-9a6d-485281a37efb",
  • "addToCashBox": true,
  • "rebuild": true,
  • "triggerCloudRestart": true
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "scenario": "string",
  • "queueId": "2992a299-8f87-4fbf-a08a-0374fd32dc40",
  • "cashBoxId": "2c22d41c-9df5-4697-bf08-a52c3ca019d5",
  • "targetScuId": "02f03f29-07db-4383-9a6d-485281a37efb",
  • "sourceScuId": "2f57ff68-6812-4caa-a56a-823a0d9f8029",
  • "addedToCashBox": true,
  • "rebuilt": true,
  • "cloudRestartTriggered": true
}

List SCUs of a PosOperator (DE only)

Returns the DE Signature Creation Units (TSEs) registered for the PosOperator, with certificate/serial information where available. Optionally filter to a single outlet via the 'outletNumber' query parameter (e.g. the outlet of the queue being switched), which yields only the SCUs eligible to be attached to that queue's CashBox. Available in Germany (DE) only.

path Parameters
posOperatorId
required
string <uuid>
query Parameters
outletNumber
integer <int64>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an SCU of a PosOperator (DE only)

Returns a single DE Signature Creation Unit (TSE) of the PosOperator by its ID, with certificate/serial information where available. Available in Germany (DE) only.

path Parameters
posOperatorId
required
string <uuid>
scuId
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "outletNumber": 0,
  • "packageName": "string",
  • "packageVersion": "string",
  • "isHidden": true,
  • "serialNumber": "string",
  • "certificationId": "string",
  • "certificateExpirationDate": "2019-08-24T14:15:22Z",
  • "isCertificateExpired": true,
  • "tseState": 0
}

Add an SCU to a CashBox (DE only)

Adds an existing DE SCU to the CashBox (idempotent). The SCU must already exist, belong to the PosOperator and sit on the same outlet as the CashBox. Publishes the configuration afterwards unless rebuild=false. Available in Germany (DE) only. Direct-API only: not reachable through the portal posdealerapiproxy, which forwards GET/POST/PATCH only.

path Parameters
posOperatorId
required
string <uuid>
cashBoxId
required
string <uuid>
scuId
required
string <uuid>
query Parameters
rebuild
boolean
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
null

Remove an SCU from a CashBox (DE only)

Removes a DE SCU from the CashBox (idempotent). IMPORTANT: when retiring the previous SCU after a switch, only call this AFTER the POS has sent the Finish-SCU-Switch receipt — removing the source SCU earlier breaks the switch. Publishes the configuration afterwards unless rebuild=false. Available in Germany (DE) only. Direct-API only: not reachable through the portal posdealerapiproxy, which forwards GET/POST/PATCH only.

path Parameters
posOperatorId
required
string <uuid>
cashBoxId
required
string <uuid>
scuId
required
string <uuid>
query Parameters
rebuild
boolean
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
null

Get a CashBox of a PosOperator

Returns a single CashBox of the PosOperator (i.e. the merchant) as a hybrid payload: the portal-parity dataset read from the fiskaltrust database — the CashBox itself (description, IP address, outlet number, state, timestamp, product type), its Queues (including the German commissioning/purchase/decommissioning dates), one flat market-tagged list of Signature Creation Units (AT/DE/IT/ES/GR/PT), its Helpers, and the Austrian Queue properties (cashbox identification, encryption key, closed-system fields and connected SCUs) — plus the CashBox access token and, verbatim, the full published middleware configuration under configuration (byte-identical to the configuration of the template-execution response, POST /api/posoperators/{posOperatorId}/templates). configuration is null (not an error) when the CashBox has never been rebuilt/published; the database-sourced blocks are returned regardless.

path Parameters
posOperatorId
required
string <uuid>
cashBoxId
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
{
  • "cashBoxId": "2c22d41c-9df5-4697-bf08-a52c3ca019d5",
  • "accessToken": "string",
  • "cashBox": {
    },
  • "queues": [
    ],
  • "signatureCreationUnits": [
    ],
  • "helpers": [
    ],
  • "queueATProperties": [
    ],
  • "configuration": {
    }
}

Generate an InStore-App pairing PIN for a CashBox

Generates a fresh 4-digit PIN for pairing the fiskaltrust InStore-App with the CashBox. The PIN is issued by the fiskaltrust receipt service, is valid for 5 minutes and can be redeemed once in the InStore-App. Pairing hands the CashBox credentials to the app instance that redeems the PIN and invalidates the previous pairing of the CashBox — which is why a ReadWrite claim on the PosOperator connection is required. Returns the PIN as a JSON string, e.g. "1234". The Portal's Rollout CashBoxes success view uses this endpoint to offer InStore-App pairing right after a CashBox was created for a connected PosOperator.

path Parameters
posOperatorId
required
string <uuid>
cashBoxId
required
string <uuid>
header Parameters
accountId
required
string <uuid>
accessToken
required
string

Responses

Response samples

Content type
application/json
"string"

Retrieve order details

Get Details of an Order

This request returns the details of an order (including its status) that is specified in the URL by its respective ordernumber.
The ordernumber is returned as a result of the Produce a Product /api/posoperators/{{posoperatorid}}/produce/outlets endpoints. The SalesOrderState can have one of the following values:

  • 0: New
  • 1: Submitted
  • 2: Failed
  • 3: Completed

    • path Parameters
    ordernumber
    required
    string
    header Parameters
    accountId
    required
    string <uuid>
    accessToken
    required
    string

    Responses

    Response samples

    Content type
    application/json
    {
    • "salesorderId": "67e6bbbd-753e-45cb-a914-d8ad0399dffb",
    • "salesOrderNumber": "string",
    • "salesOrderState": 0,
    • "subscriptions": [
      ]
    }

    Retrieve rollout plans

    List available rollout plans

    This endpoint lists all available rollout plans that are available for the given PosDealer in their respective market.
    The rollout plans returned by this endpoint can be executed to create products and subscriptions for conencted PosOperators (i.e. merchants), based on entitlements that need to be purchased via the Portal first (for more details, refer to Produce a product based on a rollout plan).

    Please note:

    • This endpoint only returns "move entitlement"-based rollout plans, i.e. those for which the PosDealer needs to obtain entitlements up-front. The PosDealer API currently does not support any operations that cause monetary transactions; those should be done via the Portal, after obtaining a volume purchase agreement. Please reach out to our sales team for further information.
    • For testing purposes, entitlements can be obtained for free in the Portal's shop in the sandbox, without requiring any payments.
    • More details about the buy & resell process can be found in our documnetation.

    query Parameters
    skipAllowList
    boolean
    Default: false
    header Parameters
    accountId
    required
    string <uuid>

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Gets rollout plan for specified market and id.

    path Parameters
    id
    required
    string <uuid>
    header Parameters
    accountId
    required
    string <uuid>

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "number": "string",
    • "title": "string",
    • "description": "string",
    • "includedBusinessFeatures": [
      ],
    • "includesTemplate": true,
    • "preview": true,
    • "imageUrl": "string",
    • "acountId": "73004a38-3521-43b5-9b16-ae4410d67a1b",
    • "businessType": "None",
    • "rolloutType": "None",
    • "includedProducts": [
      ]
    }

    Gets rollout plan for specified market and rolout number.

    path Parameters
    number
    required
    string
    header Parameters
    accountId
    required
    string <uuid>

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "number": "string",
    • "title": "string",
    • "description": "string",
    • "includedBusinessFeatures": [
      ],
    • "includesTemplate": true,
    • "preview": true,
    • "imageUrl": "string",
    • "acountId": "73004a38-3521-43b5-9b16-ae4410d67a1b",
    • "businessType": "None",
    • "rolloutType": "None",
    • "includedProducts": [
      ]
    }

    List cashbox rollout templates

    Lists the cashbox templates available to the PosDealer for technical rollout in their market, applying the same visibility rules as the Portal: own templates, templates made public for PosDealers (0x40), fully public templates (0x80), and templates shared with the dealer (0x30) by a connected PosCreator (free, non-deactivated templates only). Only actual templates are listed (the cashbox template product number and the legacy template number 201); all other product numbers (cloud, move/entitlement, etc.) are excluded. Returns the template fields available to non-admins, including the full configuration (Content) for every accessible template — access to a template implies access to its configuration.

    header Parameters
    accountId
    required
    string <uuid>

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Get a cashbox rollout template

    Returns a single cashbox rollout template by id, including its full configuration (Content), if the PosDealer may roll it out (same visibility rules as the list endpoint). Used to resolve the template configuration when creating a cashbox via the documented POST /api/posoperators/{posOperatorId}/templates endpoint.

    path Parameters
    cashBoxTemplateId
    required
    string <uuid>
    header Parameters
    accountId
    required
    string <uuid>

    Responses

    Response samples

    Content type
    application/json
    {
    • "cashBoxTemplateId": "01c23e2d-5a7c-4b13-afb0-e6894d107f8b",
    • "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
    • "name": "string",
    • "description": "string",
    • "content": "string",
    • "imageUrl": "string",
    • "linkUrl": "string",
    • "mode": 0,
    • "productNumber": "string",
    • "cashBoxType": 0
    }

    Service metadata

    /version

    Responses

    Response samples

    Content type
    application/json
    [
    • "string"
    ]

    Third Party Cash Register Operations

    Lists all 3rd party cash registers of the requested pos operator

    path Parameters
    posOperatorId
    required
    string <uuid>
    outletNumber
    required
    integer <int32>
    header Parameters
    accountId
    required
    string <uuid>
    accessToken
    required
    string

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Adds 3rd party cash register of a pos Operator.

    path Parameters
    posOperatorId
    required
    string <uuid>
    outletNumber
    required
    integer <int32>
    header Parameters
    accountId
    required
    string <uuid>
    accessToken
    required
    string
    Request Body schema: application/json
    required
    id
    string <uuid>
    software
    required
    string non-empty
    softwareVersion
    required
    string non-empty
    serialNumber
    required
    string non-empty
    manufacturer
    required
    string non-empty
    model
    required
    string non-empty
    tseSerialNumber
    required
    string non-empty
    tseCommissioningDate
    required
    string <date-time>
    purchaseDate
    required
    string <date-time>
    commissioningDate
    required
    string <date-time>
    tseExpiryDate
    required
    string <date-time>
    tseBSI
    required
    string non-empty

    Responses

    Request samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "software": "string",
    • "softwareVersion": "string",
    • "serialNumber": "string",
    • "manufacturer": "string",
    • "model": "string",
    • "tseSerialNumber": "string",
    • "tseCommissioningDate": "2019-08-24T14:15:22Z",
    • "purchaseDate": "2019-08-24T14:15:22Z",
    • "commissioningDate": "2019-08-24T14:15:22Z",
    • "tseExpiryDate": "2019-08-24T14:15:22Z",
    • "tseBSI": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "Message": "string"
    }

    Deletes 3rd party cash register of the pos operator.

    path Parameters
    posOperatorId
    required
    string <uuid>
    outletNumber
    required
    integer <int32>
    id
    required
    string <uuid>
    header Parameters
    accountId
    required
    string <uuid>
    accessToken
    required
    string

    Responses

    Response samples

    Content type
    application/json
    {
    • "Message": "string"
    }

    Updates 3rd party cash register of the pos operator.

    path Parameters
    posOperatorId
    required
    string <uuid>
    outletNumber
    required
    integer <int32>
    cashRegisterId
    required
    string <uuid>
    header Parameters
    accountId
    required
    string <uuid>
    accessToken
    required
    string
    Request Body schema: application/json
    required
    id
    string <uuid>
    software
    required
    string non-empty
    softwareVersion
    required
    string non-empty
    serialNumber
    required
    string non-empty
    manufacturer
    required
    string non-empty
    model
    required
    string non-empty
    tseSerialNumber
    required
    string non-empty
    tseCommissioningDate
    required
    string <date-time>
    purchaseDate
    required
    string <date-time>
    commissioningDate
    required
    string <date-time>
    tseExpiryDate
    required
    string <date-time>
    tseBSI
    required
    string non-empty

    Responses

    Request samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "software": "string",
    • "softwareVersion": "string",
    • "serialNumber": "string",
    • "manufacturer": "string",
    • "model": "string",
    • "tseSerialNumber": "string",
    • "tseCommissioningDate": "2019-08-24T14:15:22Z",
    • "purchaseDate": "2019-08-24T14:15:22Z",
    • "commissioningDate": "2019-08-24T14:15:22Z",
    • "tseExpiryDate": "2019-08-24T14:15:22Z",
    • "tseBSI": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "type": "string",
    • "title": "string",
    • "status": 0,
    • "detail": "string",
    • "instance": "string",
    • "errors": {
      },
    • "property1": null,
    • "property2": null
    }