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. If you don't sent webhook in request or webhook is null, response body contains response from default webhook URL.

If the default URL is used and the target device doesn't process the request within 21 seconds, a response 404 Not Found is returned.

The number of requests when using the default webhook URL is limited to one request running at same time for the same combination of userId, clientId, cloudId, branchId.

When the limit is exceeded response code 429 - Too Many Requests is returned.

Note that integers in responses from POS Actions are NOT sent as strings.

Result codes

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.
2011	EOS_ORDER	Order is created by EOS, it can't be modified
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).
70302001	BLOCKED_BY_FAILED_PRINT	2.10+ SK Order fiscalization failed because previous fiscal document is not printed. It must be printed first by Print last document action
70302002	ISSUED_FISCALIZATION_FAILED	2.12+ SK Order issued, but fiscalization failed.

Basic request format

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 action

webhook string? Webhook URL for action response

validity 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 1007

idempotency-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.

Hello (1.239.8+)

{
  "action": "order/hello"
}

Returns basic POS metadata can be used for POS liveness checks, timezone configuration, or time shift.

Response format

{
    "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)
}

Create order

{
  "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 _customerId

discount-percent double? (1.238.12+) Value of discount in percent value: 20 = 20%

table-id long? The value corresponds to _tableId

user-id long? The value corresponds to _employeeId

note string? Personal note to order

external-id string? External id of the order

items item[] List of items to be added to new order

lock boolean? (1.234+) If set to true the order will be locked for 45 s for external changes

Update order

{
  "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 _customerId

discount-percent double? Value of discount in percent value: 20 = 20%

note string? Personal note to order

order-id long Order ID for action. The value corresponds to _orderId

lock boolean? (1.234+) If se to true the order will be locked for 45 s for external changes

Add order items

{
    "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
                "manual-price": <double>,
            }],
            "take-away": <boolean>
        }
    ],
    "lock": <boolean>
}

items item[] List of items to be added

order-id long Order ID for action. The value corresponds to _orderId

lock boolean? (1.234+) If set to true the order will be locked for 45 s for external changes

Item

id long Corresponds to _productId

qty double Item / product quantity

note string? Note for item / product

discount-percent double? Value of discount in percent value: 20 = 20%

manual-price double? Product price

manual-points double? Points

tags string[]? Note for item

course-id long? Id of a course. Since Dotypos 1.237

customizations customization[]? Add product with customization Dotypos 1.234+ required

Item Customization

Dotypos 1.234+ required

product-customization-id long Corresponds to _productCustomizationId

product-id long Corresponds to _productId

manual-price double? Customization item price override (default behavior if null or empty) Since Dotypos 2.9

take-away boolean? Whether to sell this item as takeaway. Since Dotypos 1.237.

Split order (1.234)

{
  "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 _orderId

customer-id long? The value corresponds to _customerId

table-id long? The value corresponds to _tableId

note string? Personal note to order

split-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 changes

Issue order

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/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 _orderId

print-config pringConfig[]? Print configuration for print type

print-email string? Email for print type

print-type string? Print type (mode)

take-away boolean? Whether to issue this order as takeaway. Since Dotypos 1.237.

Pay issued order

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 _orderId

payment-method-id long Payment method ID

Create and issue order (1.234)

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/create-issue",
  "customer-id": <long>, // _customerId 
  "discount-percent": <double>, // 20 = 20%
  "table-id": <long>, // _tableId
  "user-id": <long>, // _employeeId
  "note": <string>,
  "external-id": <string>,
  "items": [...],
  "payment-method-id": <long>, // paymentTypeId
  "take-away": <boolean>
}

customer-id long? The value corresponds to _customerId

discount-percent double? (1.238.12+) Value of discount in percent value: 20 = 20%

table-id long? The value corresponds to _tableId

user-id long? The value corresponds to _employeeId

note string? Personal note to order

external-id string? External id of the order

items item[] List of items to be added to new order

payment-method-id long Payment method ID

take-away boolean? Whether to issue this order as takeaway. Since Dotypos 1.237.

Create, issue and pay order (1.234)

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>,
  "external-id": <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 _customerId

discount-percent double? (1.238.12+) Value of discount in percent value: 20 = 20%

table-id long? The value corresponds to _tableId

user-id long? The value corresponds to _employeeId

note string? Personal note to order

external-id string? External id of the order

items item[] List of items to be added to new order

payment-method-id long Payment method ID

print-append string? Text to be appended to printout

print-config pringConfig[]? Print configuration for print type

print-email string? Email for print type

print-type string? Print type (mode)

take-away boolean? Whether to issue this order as takeaway. Since Dotypos 1.237.

Split and issue order (1.234)

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 _orderId

customer-id long? The value corresponds to _customerId

table-id long? The value corresponds to _tableId

note string? Personal note to order

split-items boolean? List of items to be moved to new order (id should correspond items[].id from Response schema.

print-config pringConfig[]? Print configuration for print type

print-email string? Email for print type

print-type string? Print type (mode)

lock boolean? If set to true the original order will be locked for 45 s for external changes

take-away boolean? Whether to issue this order as takeaway. Since Dotypos 1.237.

Split, issue and pay order (1.234)

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 _orderId

customer-id long? The value corresponds to _customerId

table-id long? The value corresponds to _tableId

note string? Personal note to order

split-items boolean? List of items to be moved to new order (id should correspond items[].id from Response schema.

print-config pringConfig[]? Print configuration for print type

print-email string? Email for print type

print-type string? Print type (mode)

payment-method-id long Payment method ID

lock boolean? If set to true the original order will be locked for 45 s for external changes

take-away boolean? Whether to issue this order as takeaway. Since Dotypos 1.237.

Issue and pay

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 _orderId

payment-method-id long Payment method ID

print-append string? Text to be appended to printout

print-config pringConfig[]? Print configuration for print type

print-email string? Email for print type

print-type string? Print type (mode)

take-away boolean? Whether to issue this order as takeaway. Since Dotypos 1.237.

Cancel order (1.243+)

{
  "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.

Change order status (1.234+, WIP)

{
  "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 _orderId

status-transition string Transition to be performed. Check Order Status page for list of supported transitions.

Get list of open orders (1.235+)

{
  "action": "order/list",
  "table-id": <long>
}

Returns list of data in Multiple orders response format

table-id long? Table ID, list all orders if not presented, null for orders outside table

Change item's course (1.237+)

If 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.

course-changes CourseChange[] List of course changes for items in the given order.

Course Change

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.

Prepare next course (1.237+)

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.

Print last document (SK, 2.10+)

Usable only in case of failed fiscal print - in case BLOCKED_BY_FAILED print error on order issue or in case of pass-through error 100,007

Request:

{
    "action": "sk/print-last-document"
}

Response

{
    "resultCode": <integer>,
}

ResultCode	Name	Description
0	DOCUMENT_PRINTED	Failed document was printed, fiscalization is fixed and new documents can be issued
1	INVALID_COUNTRY	Call was made not for SK register, call is noop in this case
2	NO_DOCUMENT_TO_PRINT	Nothing was printed as no document was failed. Fiscalization is working correctly and new documents can be issued

Set/unset item(s) as takeaway (1.237+)

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.

take-away-changes TakeawayChange[] List of takeaway changes.

Takeaway change

order-item-id long ID of and order item.

take-away boolean Whether this item should be set as takeaway.

Shared types

Print type

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.

Print config

{
    "characters": <integer>,
    "codepage": <byte>,
    "print-mini": <boolean>,
    "print-logo": <boolean>,
    "cut": <boolean>,
    "append-lines": <integer>,
    "font": <integer>
}

characters integer? Width of print in characters

codepage byte?

print-mini boolean? Print in mini mode or standart

print-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 supported

append-lines integer? Number of lines appended to print

font integer(0,1)? Font type

Pass-through error (1.242+)

An 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.

Possible pass-through errors

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)
100007	SK Fiscal print of the order failed. Order is fiscalized, but next actions on fiscal printer will fail. It is required to solve this by calling Print last document action

Response schema (default)

{
    "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.

pass-through-errors [PassThroughError] 1.242+ List of pass-through errors encountered.

Multiple orders response schema

{
    "orders": [
        {
            "order": {
                "id": <long>,
                "bkp": <string>,
                "completed": <timestamp>,
                "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?>, // 2.0
                "order-series-id": "0",
                "paid": <boolean>,
                "pkp": <string>,
                "points": <double>,
                "table-id": <long>, // _tableId
                "price-total": <double>,
                "locked-until": <timestamp>,
                "status": <string> // 1.234+
            },
            "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>
                }
            ]
        }
    ],
    "code": <int>,
    "deviceTimestamp": <long> // 1.239.8+
}

Pos actions

POST https://api.dotykacka.cz/v2/clouds/:cloudId/branches/:branchId/pos-actions

Path Parameters

Name	Type	Description
branchId	integer
cloudId	integer

Headers

Name	Type	Description
Authorization	string	Bearer accessToken

Request Body

Name	Type	Description
	array	Some of action request schema

200