Zum Hauptinhalt springen
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
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
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 CashBoxe

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
query Parameters
outlet_number
required
string
header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
ftCashBoxId
string or null
Array of objects or null (ftSignatureCreationDevice)
Array of objects or null (ftQueue)
Array of objects or null (Helper)

Responses

Request samples

Content type
application/json
{
  • "ftCashBoxId": "string",
  • "ftSignaturCreationDevices": [
    ],
  • "ftQueues": [
    ],
  • "helpers": [
    ]
}

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.
Please note that only active connections (i.e. connections that the PosOperator has accepted) are returned in this version of the API.

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
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 (DE only)

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. This function is available in germany only.

header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
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": {
    }
}

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
header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
rolloutPlanNumber
string or null

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

queueIds
Array of strings or null <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
header Parameters
accountId
required
string <uuid>
accessToken
required
string
Request Body schema: application/json
rolloutPlanNumber
string or null

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

outletNumbers
Array of integers or null <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
[
  • {
    }
]

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.

    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",
    • "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",
    • "businessType": "None",
    • "rolloutType": "None",
    • "includedProducts": [
      ]
    }