POS actions

Send action to specific branch

Send action directly to branch device and response will send to webhook. Branch must be turn on.

Response header Response-url contains webhook URL from request body or default webhook URL.

If you don't sent webhook in request or webhook is null. Response body contain response from default webhook URL.

Code

Value

Description

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

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

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

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

Response status code is primary OK 200. For correct status use code properties in webhook response.

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
}

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

Create order

{
"action": "order/create",
"customer-id": <long>, // _customerId
"table-id": <long>, // _tableId
"user-id": <long>, // _employeeId
"note": <string>,
"external-id": <string>,
"items": [...],
"lock": <boolean>
}

customer-id long? The value corresponds to _customerId

table-id long? The value corresponds to _tableId

user-id long? The value corresponds to _employeeId

note string? Personal note to order

externalId 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
}],
"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

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

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

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

{
"action": "order/create-issue",
"customer-id": <long>, // _customerId
"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 _customerId

table-id long? The value corresponds to _tableId

user-id long? The value corresponds to _employeeId

note string? Personal note to 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)

{
"action": "order/create-issue-pay",
"customer-id": <long>, // _customerId
"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 _customerId

table-id long? The value corresponds to _tableId

user-id long? The value corresponds to _employeeId

note string? Personal note to 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)

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

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

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

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.

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

Value

Description

local

Print on device printer

remote

Print task in format ESC/POS will contain in response (print-config is required)

email

Order will send on email address by value print-email

none

Dont print

{
"characters": <integer>,
"codepage": <byte>,
"print-mini": <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

cut boolean? Is cut supported

append-lines integer? Number of lines appended to print

font integer(0,1)? Font type

Response schema (default)

{
"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-series-id": "0",
"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>, // _orderId
"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": [],
"code": <integer>
}

Mutliple 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-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>, // _orderId
"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>
}
]
}
]
}

post
Pos actions

https://api.dotykacka.cz/v2/clouds/:cloudId/branches/:branchId/pos-actions
Request
Response
Request
Path Parameters
branchId
required
integer
cloudId
required
integer
Headers
Authorization
required
string
Bearer accessToken
Body Parameters
required
array
Some of action request schema
Response
200: OK