POS actions
Send action to specific branch
Send action directly to a branch device and response will send to webhook. Branch device must be turned on.
Response header Response-url contains webhook URL from request body or default webhook URL.
Note that integers in responses from POS Actions are NOT sent as strings.
If you don't sent webhook in request or webhook is null. Response body contain response from default webhook URL.
The number of requests is limited to one request running at same time for the same combination of userId, clientId, cloudId, branchId.
Response status code is primary OK 200. For correct status use
code properties in webhook response.Represent the result of processing. There are NOT the response codes.
Code | Value | Description |
0 | CODE_OK | ​ |
100
| CODE_OTHER | ​ |
1001
| REQUEST_ERROR | ​ |
1002
| CONFIGURATION_ERROR | Current configuration of cash register does not allow to perform requested POS action. |
1003
| MISSING_ACTION | Your request is missing action parameter |
1004
| UNKNOWN_ACTION | Requested action is unknown or no more supported |
1005
| DATA_FORMAT_ERROR | ​ |
1006
| LICENSE_ERROR | License of the Cash Register is not sufficient to perform requested POS action. |
1007
| EXPIRED_REQUEST | validity of request is expired |
1008 | USER_NOT_FOUND | user-id of request was not found in App |
1009 | ACTION_NOT_ALLOWED_FOR_COUNTRY | 1.242+ Executed action is not allowed for current POS country. |
1999
| SERVER_ERROR | ​ |
2001
| ORDER_LOCKED | Requested order is locked to another service/user |
2002
| ORDER_NOT_FOUND | Order with given id not found |
2003
| ORDER_PAYMENT_METHOD_NOT_FOUND | Payment method with given id not found |
2004
| ORDER_PAID | Order is already paid |
2005
| ORDER_ISSUED | Order is already issued |
2006
| ORDER_NOT_ISSUED | Order is not issued yet |
2007 | INVALID_PRINT_EMAIL | SK print-email is required to be a valid email for give print-type. |
2008 | INVALID_PRINT_TYPE | SK print-type none is not supported. |
2009 | ORDER_NOT_EMPTY | Order is not empty, there are some items in it. |
2010 | ORDER_ALREADY_CANCELED | Order can't be canceled as it is already canceled. |
2999
| ORDER_OTHER | ​ |
3001
| REGISTER_CLOSED | Cash Register is closed. You need to open the cash register to be able to do any order modifications. |
4001 | PRODUCT_NOT_FOUND | Requested product was not found in database of Cash Register |
5001 | ORDER_ITEM_NOT_FOUND | The item of the selected order is not presented on the order. |
5002 | ORDER_ITEM_LOW_QUANTITY | Requested change cannot be performed due to low quantity of order item. |
5003 | ORDER_ITEM_NEGATIVE_QUANTITY | Requested change cannot be performed due to negative quantity change in request. |
6001 | ORDER_TRANSITION_UNKNOWN | The requested transition is not known (maybe old version of Dotypos App). |
6002 | ORDER_TRANSITION_DENIED | The requeste transition could not be performed. |
7001 | COURSE_CHANGE_NOT_ALLOWED_FOR_PRODUCT | The specified course is not allowed for the given product. |
7002 | COURSE_CHANGE_ITEM_ALREADY_PREPARED | Unable to change item's course because this item has already been prepared. |
8001 | TAKE_AWAY_NOT_ENABLED | Takeaway is disabled on POS. |
8002 | TAKE_AWAY_NOT_ALLOWED_FOR_PRODUCT | Takeaway is not allowed for given product (see response for details). |
8003 | TAKE_AWAY_NOT_ALLOWED_FOR_ORDER | Takeaway is not allowed for whole orders. |
8004 | TAKE_AWAY_NOT_ENABLED_FOR_ORDERS_WITH_NO_TAKEAWAY_ITEMS | Unable to set the order as takeaway because the order does not contain any items with takeaway allowed. |
10001 | CUSTOMIZATION_NOT_FOUND | No customization found for the given id (see response for details). |
10002 | CUSTOMIZATION_CATEGORY_NOT_FOUND | No customization category found for the given id (see response for details). |
10003 | PRODUCT_NOT_FOUND (when working with customizations) | No product found for the given id (see response for details). |
10004 | PRODUCT_NOT_FOUND_IN_CUSTOMIZATION | Product with given id couldn't be found in given customization (see response for details). |
10005 | INVALID_SELECTED_QUANTITY | The given quantity of a product is not within customization's bounds (see response for details). |
All request shares some basic parameters listed below. For better readability are those parameters are not shown in all methods.
{
"action": <string>,
"webhook": <string>,
"validity": <long>, // Unix timestamp
"idempotency-key": <string> | null
}
action string
Name of actionwebhook string?
Webhook URL for action responsevalidity long?
Validity of request in Unix timestamp. If the time on cash register is greater than this value, the request will not be performed with response code 1007idempotency-key string? (Since Dotypos 2.1)
Optional identification of a webhook call. It provides way for you to identify retried (same) webhook calls. When webhook parameter is filled, Dotypos will call the given URL with the Idempotency-Key header containing this value. If you do not specify idempotency-key, it will be automatically generated and sent.{
"action": "order/hello"
}
Returns basic POS metadata can be used for POS liveness checks, timezone configuration, or time shift.
{
"device": <string>,
"timezone": <string>,
"version:": {
"id": <string>, // "com.touchpo.android"
"code": <long>,
"name": <string>,
},
"code": <int>,
"deviceTimestamp": <long> // Current UTC timestamp of device (in ms)
}
{
"action": "order/create",
"customer-id": <long>, // _customerId
"discount-percent": <double>, // 20 = 20%
"table-id": <long>, // _tableId
"user-id": <long>, // _employeeId
"note": <string>,
"external-id": <string>,
"items": [...],
"lock": <boolean>
}
customer-id long?
The value corresponds to _customerIddiscount-percent double? (1.238.12+)
Value of discount in percent value: 20 = 20%table-id long?
The value corresponds to _tableIduser-id long?
The value corresponds to _employeeIdnote string?
Personal note to orderexternal-id string?
External id of the orderlock boolean? (1.234+)
If set to true the order will be locked for 45 s for external changes{
"action": "order/update",
"order-id": <long>, // _orderId
"customer-id": <long>, // _customerId
"discount-percent": <double>, // 20 = 20%
"note": <string>,
"lock": <boolean>
}
customer-id long?
The value corresponds to _customerIddiscount-percent double?
Value of discount in percent value: 20 = 20%note string?
Personal note to orderorder-id long
Order ID for action. The value corresponds to _orderIdlock boolean? (1.234+)
If se to true the order will be locked for 45 s for external changes{
"action": "order/add-item",
"order-id": <long>, //_orderId
"items": [
{
"id": <long>, // _productId
"qty": <doble>, // quantity
"note": <string>,
"discount-percent": <double>, // 20 = 20%
"manual-price": <double>,
"manual-points": <double>,
"tags": <string[]>,
"course-id": <long> | null,
"customizations": [{
"product-customization-id": <long>, // _productCustomizationId
"product-id": <long> // _productId
}],
"take-away": <boolean>
}
],
"lock": <boolean>
}
order-id long
Order ID for action. The value corresponds to _orderIdlock boolean? (1.234+)
If set to true the order will be locked for 45 s for external changesid long
Corresponds to _productIdqty double
Item / product quantitynote string?
Note for item / productdiscount-percent double?
Value of discount in percent value: 20 = 20%manual-price double?
Product pricemanual-points double?
Pointstags string[]?
Note for itemcourse-id long?
Id of a course.
Since Dotypos 1.237Dotypos 1.234+ required
product-customization-id long
Corresponds to _productCustomizationIdproduct-id long
Corresponds to _productIdtake-away boolean?
Whether to sell this item as takeaway.
Since Dotypos 1.237.{
"action": "order/split",
"order-id": <long>, // _orderId
"customer-id": <long>, // _customerId
"table-id": <long>, // _tableId
"note": <string>,
"split-items": [
{
"id": "123",
"qty": "12"
}
],
"lock": <boolean>
}
order-id long
Order ID of order to split. The value corresponds to _orderIdcustomer-id long?
The value corresponds to _customerIdtable-id long?
The value corresponds to _tableIdnote string?
Personal note to ordersplit-items boolean?
List of items to be moved to new order (id should correspond items[].id from Response schema.lock boolean?
If set to true the newly created order will be locked for 45 s for external changesNot allowed in following countries: Slovakia.
We allow you to invoke optional notifications displayed for staff on the POS for issued orders via POS Action. If you want to use this feature, contact us. We will enable functionality for your API application.
Since Dotypos 1.241
{
"action": "order/issue",
"order-id": <long>, // _orderId
"print-config": {},
"print-email": <string>,
"print-type": <string>,
"take-away": <boolean>
}
order-id long
Order ID for action. The value corresponds to _orderIdprint-email string?
Email for print typetake-away boolean?
Whether to issue this order as takeaway.
Since Dotypos 1.237.Not allowed in following countries: Slovakia.
{
"action": "order/pay",
"order-id": <long>, // _orderId
"payment-method-id": <long> // paymentTypeId
}
order-id long
Order ID for action. The value corresponds to _orderIdNot allowed in following countries: Slovakia.
We allow you to invoke optional notifications displayed for staff on the POS for issued orders via POS Action. If you want to use this feature, contact us. We will enable functionality for your API application.
Since Dotypos 1.241
{
"action": "order/create-issue",
"customer-id": <long>, // _customerId
"discount-percent": <double>, // 20 = 20%
"table-id": <long>, // _tableId
"user-id": <long>, // _employeeId
"note": <string>,
"items": [...],
"payment-method-id": <long>, // paymentTypeId
"take-away": <boolean>
}
customer-id long?
The value corresponds to _customerIddiscount-percent double? (1.238.12+)
Value of discount in percent value: 20 = 20%table-id long?
The value corresponds to _tableIduser-id long?
The value corresponds to _employeeIdnote string?
Personal note to ordertake-away boolean?
Whether to issue this order as takeaway.
Since Dotypos 1.237.We allow you to invoke optional notifications displayed for staff on the POS for issued orders via POS Action. If you want to use this feature, contact us. We will enable functionality for your API application.
Since Dotypos 1.241
{
"action": "order/create-issue-pay",
"customer-id": <long>, // _customerId
"discount-percent": <double>, // 20 = 20%
"table-id": <long>, // _tableId
"user-id": <long>, // _employeeId
"note": <string>,
"items": [...],
"payment-method-id": <long>, // paymentTypeId
"print-append": <string>,
"print-config": {},
"print-email": <string>,
"print-type": <string>,
"take-away": <boolean>
}
customer-id long?
The value corresponds to _customerIddiscount-percent double? (1.238.12+)
Value of discount in percent value: 20 = 20%table-id long?
The value corresponds to _tableIduser-id long?
The value corresponds to _employeeIdnote string?
Personal note to orderprint-append string?
Text to be appended to printoutprint-email string?
Email for print typetake-away boolean?
Whether to issue this order as takeaway.
Since Dotypos 1.237.Not allowed in following countries: Slovakia.
We allow you to invoke optional notifications displayed for staff on the POS for issued orders via POS Action. If you want to use this feature, contact us. We will enable functionality for your API application.
Since Dotypos 1.241
{
"action": "order/split-issue",
"order-id": <long>, // _orderId
"customer-id": <long>, // _customerId
"table-id": <long>, // _tableId
"note": <string>,
"split-items": [
{
"id": "123",
"qty": "12"
}
],
"print-config": {},
"print-email": <string>,
"print-type": <string>,
"lock": <boolean>,
"take-away": <boolean>
}
order-id long
Order ID of order to split. The value corresponds to _orderIdcustomer-id long?
The value corresponds to _customerIdtable-id long?
The value corresponds to _tableIdnote string?
Personal note to ordersplit-items boolean?
List of items to be moved to new order (id should correspond items[].id from Response schema.print-email string?
Email for print typelock boolean?
If set to true the original order will be locked for 45 s for external changestake-away boolean?
Whether to issue this order as takeaway.
Since Dotypos 1.237.We allow you to invoke optional notifications displayed for staff on the POS for issued orders via POS Action. If you want to use this feature, contact us. We will enable functionality for your API application.
Since Dotypos 1.241
{
"action": "order/split-issue-pay",
"order-id": <long>, // _orderId
"customer-id": <long>, // _customerId
"table-id": <long>, // _tableId
"note": <string>,
"split-items": [
{
"id": "123",
"qty": "12"
}
],
"print-config": {},
"print-email": <string>,
"print-type": <string>,
"payment-method-id": <long>, // paymentTypeId
"lock": <boolean>,
"take-away": <boolean>
}
order-id long
Order ID of order to split. The value corresponds to _orderIdcustomer-id long?
The value corresponds to _customerIdtable-id long?
The value corresponds to _tableIdnote string?
Personal note to ordersplit-items boolean?
List of items to be moved to new order (id should correspond items[].id from Response schema.print-email string?
Email for print typelock boolean?
If set to true the original order will be locked for 45 s for external changestake-away boolean?
Whether to issue this order as takeaway.
Since Dotypos 1.237.We allow you to invoke optional notifications displayed for staff on the POS for issued orders via POS Action. If you want to use this feature, contact us. We will enable functionality for your API application.
Since Dotypos 1.241
{
"action": "order/issue-and-pay",
"order-id": <long>, // _orderId
"payment-method-id": <long>, // paymentTypeId
"print-append": <string>,
"print-config": {},
"print-email": <string>,
"print-type": <string>,
"take-away": <boolean>
}
order-id long
Order ID for action. The value corresponds to _orderIdprint-append string?
Text to be appended to printoutprint-email string?
Email for print typetake-away boolean?
Whether to issue this order as takeaway.
Since Dotypos 1.237.{
"action": "order/cancel",
"order-id": <long> // _orderId
}
order-id long
Order ID for action. The value corresponds to _orderId. Order must be empty - it can't have any items.{
"action": "order/perform-status-transition",
"order-id": <long>, // _orderId
"status-transition": <string>
}
This endpoint is in active development phase. List of available transitions and their limitations could be changed in any further release of Dotypos App.
order-id long
Order ID for action. The value corresponds to _orderIdstatus-transition string
Transition to be performed. Check Order Status page for list of supported transitions.{
"action": "order/list",
"table-id": <long>
}
table-id long?
Table ID, list all orders if not presented, null for orders outside tableIf there are multiple course changes for the same item, only the last is applied.
{
"action": "order/change-item-course",
"order-id": <long>,
"course-changes":[{
"order-item-id": <long>,
"new-course-id": <long> | null
}]
}
order-id long
ID of the order.order-item-id long
ID of an order item.new-course-id long?
ID of a new course for the given item within an order.Response field
next-course-id describes the next available response for this order.{
"action": "order/prepare-next-course",
"order-id": <long>
}
order-id long
ID of an order.If there are multiple takeaway changes for the same order item, only the last one will be applied.
{
"action": "order/set-item-takeaway",
"take-away-changes": [{
"order-item-id": <long>, // id of an order item, NOT product
"take-away": <boolean>
}],
"order-id": <long>
}
order-id long
ID of an order.order-item-id long
ID of and order item.take-away boolean
Whether this item should be set as takeaway.local | Print on device printer |
remote | Print task in format ESC/POS will contain in response (print-config is required)
SK - change Using remote also requires print-email field to be sent. Response will contain the base64 encoded representation of the receipt file (print-png field). If, for some reason, receipt couldn't have been base64 encoded, the original file stays on POS (see Pass-through errors).
1.243+ If fiscal printout is not available for remote printing, print won't be added and pass-through-errors will contain error 100006. |
email | Receipt will be sent to the email address specified in print-email.
SK - change Also email of Order's customer can be accepted. If email sending fails (see Pass-through errors), POS will try to fill at least base64 representation of receipt (as stated in the description of remote print-type above).
1.243+ If fiscal printout is not available, email won't be sent and pass-through-errors will contain error 100006. |
none | Dont print
SK - change Not allowed in Slovakia. Returns an error. |
{
"characters": <integer>,
"codepage": <byte>,
"print-mini": <boolean>,
"print-logo": <boolean>,
"cut": <boolean>,
"append-lines": <integer>,
"font": <integer>
}
characters integer?
Width of print in characterscodepage byte?print-mini boolean?
Print in mini mode or standartprint-logo boolean?
1.243+
Print logo on receipt (if the logo is configured for any receipt print task in the register)cut boolean?
Is cut supportedappend-lines integer?
Number of lines appended to printfont integer(0,1)?
Font typeAn error that occured during Order processing but didn't cause the processing to fail. Might be interpreted as a warning to the user.
{
"code": <integer>,
"description": <string>,
"localized-description": <string>
}
code integer
Error code.description string
General description of a pass-through error in English.localized-description string
Localized description of a pass-through error in language specified in the request. If no language is specified in the request, defaults to POS' language.code | description |
|---|---|
100001 | SK Fiscal receipt file not found. Usually when order is successfully fiscalized, but the fiscal module didn't fill the path to the receipt file.
The fiscal receipt was probably printed locally. |
100002 | SK Fiscal receipt email not sent. Email with fiscal receipt couldn't have been sent.
print-png field of response should contain the Base64 encoded receipt file instead (see next). |
100003 | SK Fiscal receipt base64 creation failed. Could not encode the receipt file in Base64.
print-png field in response is null. In case this happens, the receipt file won't be deleted from POS (it can be retrieved manually - contact support). |
100004 | SK Fiscal receipt possibly incomplete. Might happen when the fiscal module haven't finished writing/creating the receipt file even after extensive amount of time.
The electronic receipt sent to customer might have been incomplete.
The receipt file won't be deleted from POS (it can be retrieved manually - contact support). |
100005 | SK Fiscal receipt possibly old. When the receipt file we found was created more than 60 seconds prior to the processing.
The electronic receipt sent to customer might not be the correct one.
The receipt file won't be deleted from POS (it can be retrieved manually - contact support). |
100006 | Can't obtain fiscal receipt printout. Fiscal receipts can be printed only locally (fiscal receipt is printed only on paper by fiscal the printer) |
{
"order": {
"id": <long>,
"bkp": <string>,
"completed": <timestamp>,
"canceled-date": <timestamp>, // 1.243+
"currency": <string(3)>,
"customer-id": <long>, // _customerI
"course-id": <long>, // 1.234+
"user-id": <long>, // _employeeId
"external-id": <string>,
"fik": <string>,
"flags": <integer>,
"created": <timestamp>,
"note": <string>,
"order-number": <string?>, // 1.243+
"order-series-id": <string>,
"paid": <boolean>,
"pkp": <string>,
"points": <double>,
"table-id": <long>, // _tableId
"price-total": <double>,
"locked-until": <timestamp>,
"status": <string> // 1.234+
},
"next-course-id": <long> | null,
"items": [
{
"id": <long>, // _orderItemId
"price-with-vat": {
"unit-billed": <double>,
"total": <double>,
"unit": <double>
},
"price-without-vat": {
"unit-billed": <double>,
"total": <double>,
"unit": <double>
},
"customizations": [],
"course-id": <long>, // 1.234+
"name": <string>,
"packaging": <double>,
"points": <double>,
"product-id": <long>, // _productId
"price-in-points": <double>, // 1.234+
"qty": <double>,
"tags": <string[]>,
"vat": <double>,
"take-away": <boolean>
}
],
"print": [string],
"print-png": <string?>, // 1.242+
"code": <integer>,
"pass-through-errors": [PassThroughError], // 1.242+
"deviceTimestamp": <long> // 1.239.8+
}
print [string]
Contains the base64 representation of receipt.
1.243+ If the register has configured multiple receipt print tasks, there will be added print content for each of them. All configured filters and print configurations for the task will be applied. Fiscalized receipt content is added only if it is available, otherwise print won't be added and pass-through-errors will contain error 100006.print-png string?
1.242+, SK
Contains the base64 representation of a receipt returned by the fiscal module when print-type: "remote" or when print-type: "email" and email sending fails.{
"orders": [
{
"order": {
"id": <long>,
"bkp": <string>,
"completed": <timestamp>,