Download OpenAPI specification:Download
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.
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.
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.
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.
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:
| posOperatorId required | string <uuid> |
| accountId required | string <uuid> |
| accessToken required | string |
[- {
- "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"
}
]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:
| posOperatorId required | string <uuid> |
| accountId required | string <uuid> |
| accessToken required | string |
| 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"). |
{- "locationId": "string",
- "outletNumber": 3,
- "name": "string",
- "address": "string",
- "contactName": "string",
- "telephone": "string",
- "fax": "string",
- "postalCode": "string",
- "city": "string",
- "county": "string",
- "stateOrProvince": "string",
- "country": "st"
}{- "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"
}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:
| posOperatorId required | string <uuid> |
| outletNumber required | integer <int32> |
| accountId required | string <uuid> |
| accessToken required | string |
{- "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"
}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:
| posOperatorId required | string <uuid> |
| outletNumber required | integer <int32> |
| accountId required | string <uuid> |
| accessToken required | string |
| 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"). |
{- "locationId": "string",
- "name": "string",
- "address": "string",
- "contactName": "string",
- "telephone": "string",
- "fax": "string",
- "postalCode": "string",
- "city": "string",
- "county": "string",
- "stateOrProvince": "string",
- "country": "st"
}{- "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"
}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.
| posOperatorId required | string <uuid> |
| outlet_number required | string |
| accountId required | string <uuid> |
| accessToken required | string |
{- "cashBoxId": "2c22d41c-9df5-4697-bf08-a52c3ca019d5",
- "accessToken": "string",
- "configuration": {
- "helpers": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "package": "string",
- "version": "string",
- "configuration": {
- "property1": null,
- "property2": null
}, - "url": [
- "string"
]
}
], - "ftCashBoxId": "c46ca7e4-eca1-4fbe-b4c2-5e7ceeb420f9",
- "ftSignaturCreationDevices": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "package": "string",
- "version": "string",
- "configuration": {
- "property1": null,
- "property2": null
}, - "url": [
- "string"
]
}
], - "ftQueues": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "package": "string",
- "version": "string",
- "configuration": {
- "property1": null,
- "property2": null
}, - "url": [
- "string"
]
}
], - "timeStamp": 0
}
}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.
| accountId required | string <uuid> |
| accessToken required | string |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "line1": "string",
- "country": "string",
- "postalCode": "string",
- "city": "string",
- "eMailAddress": "string",
- "identifiers": {
- "vatId": "string",
- "taxId": "string",
- "fibuNr": "string",
- "gln": "string",
- "siren": "string"
}
}
]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.
| accountId required | string <uuid> |
| accessToken required | string |
required | object (Company) |
required | object (Contact) |
| accessRights required | string (AccessRights) Enum: "Undefined" "None" "Read" "ReadWrite" "Full" |
object (InvitationDetails) |
{- "company": {
- "name": "string",
- "email": "string",
- "addressLine1": "string",
- "addressLine2": "string",
- "postalCode": "string",
- "city": "string",
- "country": "string",
- "website": "string",
- "phoneNumber": "string",
- "identifiers": {
- "vatId": "string",
- "taxId": "string",
- "fibuNr": "string",
- "gln": "string",
- "siren": "string"
}
}, - "primaryContact": {
- "firstName": "string",
- "lastName": "string",
- "email": "string",
- "title": "string",
- "suffix": "string",
- "phone": "string"
}, - "accessRights": "Undefined",
- "details": {
- "pdfAttachment": "string",
- "additionalText": "string"
}
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "line1": "string",
- "country": "string",
- "postalCode": "string",
- "city": "string",
- "eMailAddress": "string",
- "identifiers": {
- "vatId": "string",
- "taxId": "string",
- "fibuNr": "string",
- "gln": "string",
- "siren": "string"
}
}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.
| posOperatorId required | string <uuid> |
| accountId required | string <uuid> |
| accessToken required | string |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "line1": "string",
- "country": "string",
- "postalCode": "string",
- "city": "string",
- "eMailAddress": "string",
- "identifiers": {
- "vatId": "string",
- "taxId": "string",
- "fibuNr": "string",
- "gln": "string",
- "siren": "string"
}
}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.
| accountId required | string <uuid> |
| accessToken required | string |
required | object (Company) |
required | object (Contact) |
| accessRights required | string (AccessRights) Enum: "Undefined" "None" "Read" "ReadWrite" "Full" |
object (InvitationDetails) |
{- "company": {
- "name": "string",
- "email": "string",
- "addressLine1": "string",
- "addressLine2": "string",
- "postalCode": "string",
- "city": "string",
- "country": "string",
- "website": "string",
- "phoneNumber": "string",
- "identifiers": {
- "vatId": "string",
- "taxId": "string",
- "fibuNr": "string",
- "gln": "string",
- "siren": "string"
}
}, - "primaryContact": {
- "firstName": "string",
- "lastName": "string",
- "email": "string",
- "title": "string",
- "suffix": "string",
- "phone": "string"
}, - "accessRights": "Undefined",
- "details": {
- "pdfAttachment": "string",
- "additionalText": "string"
}
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "line1": "string",
- "country": "string",
- "postalCode": "string",
- "city": "string",
- "eMailAddress": "string",
- "identifiers": {
- "vatId": "string",
- "taxId": "string",
- "fibuNr": "string",
- "gln": "string",
- "siren": "string"
}
}This endpoint updates the master data for a company, specifically the information required for the notification-sending operation.
| posOperatorId required | string <uuid> |
| accountId required | string <uuid> |
| accessToken required | string |
| taxNumber | string or null |
object (UpdateCompanyAddress) |
{- "taxNumber": "string",
- "address": {
- "street": "string",
- "city": "string",
- "postalCode": 0,
- "houseNumber": "string"
}
}"string"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:
| accountId required | string <uuid> |
| accessToken required | string |
[- {
- "name": "string",
- "totalTerms": 0.1,
- "remainingTerms": 0.1
}
]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:
| posOperatorId required | string <uuid> |
| accountId required | string <uuid> |
| accessToken required | string |
| 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. |
{- "rolloutPlanNumber": "string",
- "queueIds": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}{- "orderNumber": "string"
}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:
| posOperatorId required | string <uuid> |
| accountId required | string <uuid> |
| accessToken required | string |
| 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. |
{- "rolloutPlanNumber": "string",
- "outletNumbers": [
- 0
]
}{- "Message": "string"
}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.
| posOperatorId required | string <uuid> |
| accountId required | string <uuid> |
| accessToken required | string |
[- {
- "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"
}
]This endpoint partially updates the queue data. Information related to cash register notifications can be updated. The endpoint is only available in Germany.
| posOperatorId required | string <uuid> |
| queueId required | string <uuid> |
| accountId required | string <uuid> |
| accessToken required | string |
| purchaseDate | string or null <date-time> |
| commissioningDate | string or null <date-time> |
{- "purchaseDate": "2019-08-24T14:15:22Z",
- "commissioningDate": "2019-08-24T14:15:22Z"
}"string"This endpoint returns data for a specific Queue(DE) of the PosOperator. The endpoint is only available in Germany.
| posOperatorId required | string <uuid> |
| queueId required | string <uuid> |
| accountId required | string <uuid> |
| accessToken required | string |
{- "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"
}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:
| ordernumber required | string |
| accountId required | string <uuid> |
| accessToken required | string |
{- "salesorderId": "67e6bbbd-753e-45cb-a914-d8ad0399dffb",
- "salesOrderNumber": "string",
- "salesOrderState": 0,
- "subscriptions": [
- {
- "salesOrderDetailId": "34837d2e-6ba6-4625-956d-bc05704b0d4a",
- "operatorId": "373c4133-3dda-4217-938b-a5730b9cc41a",
- "outletnumber": 0,
- "relatedCashboxID": "0de4645c-7ddf-449c-91a7-aae6c8ae33b5",
- "relatedCashboxAccessToken": "string",
- "relatedQueueID": "89343ad8-297a-437a-989a-7b817cffc9d2",
- "relatedSCUID": "a366a84f-8960-4622-ae7c-8e6e8c642107"
}
]
}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:
| accountId required | string <uuid> |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "number": "string",
- "title": "string",
- "description": "string",
- "includedBusinessFeatures": [
- "string"
], - "includesTemplate": true,
- "preview": true,
- "imageUrl": "string",
- "acountId": "73004a38-3521-43b5-9b16-ae4410d67a1b",
- "businessType": "None",
- "rolloutType": "None",
- "includedProducts": [
- {
- "number": "string",
- "cashBoxTemplateId": "01c23e2d-5a7c-4b13-afb0-e6894d107f8b",
- "name": "string",
- "description": "string"
}
]
}
]| id required | string <uuid> |
| accountId required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "number": "string",
- "title": "string",
- "description": "string",
- "includedBusinessFeatures": [
- "string"
], - "includesTemplate": true,
- "preview": true,
- "imageUrl": "string",
- "acountId": "73004a38-3521-43b5-9b16-ae4410d67a1b",
- "businessType": "None",
- "rolloutType": "None",
- "includedProducts": [
- {
- "number": "string",
- "cashBoxTemplateId": "01c23e2d-5a7c-4b13-afb0-e6894d107f8b",
- "name": "string",
- "description": "string"
}
]
}| number required | string |
| accountId required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "number": "string",
- "title": "string",
- "description": "string",
- "includedBusinessFeatures": [
- "string"
], - "includesTemplate": true,
- "preview": true,
- "imageUrl": "string",
- "acountId": "73004a38-3521-43b5-9b16-ae4410d67a1b",
- "businessType": "None",
- "rolloutType": "None",
- "includedProducts": [
- {
- "number": "string",
- "cashBoxTemplateId": "01c23e2d-5a7c-4b13-afb0-e6894d107f8b",
- "name": "string",
- "description": "string"
}
]
}| posOperatorId required | string <uuid> |
| outletNumber required | integer <int32> |
| accountId required | string <uuid> |
| accessToken required | string |
[- {
- "outletId": "414ee52f-b8bb-444c-8e1a-824bf463e887",
- "outletName": "string",
- "address": {
- "street": "string",
- "city": "string",
- "postalCode": 0,
- "houseNumber": "string"
}, - "lastUpdate": "2019-08-24T14:15:22Z",
- "cashRegisters": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "outletId": "414ee52f-b8bb-444c-8e1a-824bf463e887",
- "software": "string",
- "softwareVersion": "string",
- "serialNumber": "string",
- "manufacturer": "string",
- "model": "string",
- "tseSerialNumber": "string",
- "tseCommissioningDate": "2019-08-24",
- "purchaseDate": "2019-08-24",
- "commissioningDate": "2019-08-24",
- "tseExpiryDate": "2019-08-24",
- "tseBSI": "string",
- "lastUpdate": "2019-08-24T14:15:22Z"
}
]
}
]| posOperatorId required | string <uuid> |
| outletNumber required | integer <int32> |
| accountId required | string <uuid> |
| accessToken required | string |
| 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 |
{- "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"
}{- "Message": "string"
}| posOperatorId required | string <uuid> |
| outletNumber required | integer <int32> |
| id required | string <uuid> |
| accountId required | string <uuid> |
| accessToken required | string |
{- "Message": "string"
}| posOperatorId required | string <uuid> |
| outletNumber required | integer <int32> |
| cashRegisterId required | string <uuid> |
| accountId required | string <uuid> |
| accessToken required | string |
| 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 |
{- "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"
}{- "type": "string",
- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "errors": {
- "property1": [
- "string"
], - "property2": [
- "string"
]
}, - "property1": null,
- "property2": null
}