Actions

Send an action directly to a branch's POS device. The device must be online and turned on. The result is not returned in the HTTP response — it is delivered to the webhook URL you specify (or the default webhook configured for your integration).

Result codes

Represent the result of processing. There are NOT the response codes.

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%
  "guest-count": <int>,
  "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%

guest-count int? (2.14+)
Number of guests for the order. Must be greater than 0, otherwise result code 2012 (ORDER_INVALID_GUEST_COUNT) is returned. Since 2.18, if Guest count entry is disabled or unavailable under the POS license, the field is ignored and the order is created without a guest count.

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%
  "guest-count": <int>,
  "note": <string>,
  "lock": <boolean>
}

customer-id long?
The value corresponds to _customerId

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

guest-count int? (2.14+)
Number of guests for the order. Must be greater than 0, otherwise result code 2012 (ORDER_INVALID_GUEST_COUNT) is returned. Send null to clear the guest count; if the field is omitted, the guest count stays unchanged. Since 2.18, if Guest count entry is disabled or unavailable under the POS license, the field is ignored and the guest count stays unchanged.

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>,
                "qty": <int>
            }],
            "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 unit price including VAT

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 including VAT (default behavior if null or empty)
Since Dotypos 2.9

qty int?
Quantity of customization item (default behavior if null or empty is 1)
Since Dotypos 2.17

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
  "guest-count": <int>,
  "print-config": {},
  "print-email": <string>,
  "print-type": <string>,
  "take-away": <boolean>
}

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

guest-count int? (2.14+)
Number of guests to set on the order before it is issued. Same rules as for Update order: must be greater than 0 (2012), null clears the value, omitted field leaves it unchanged, and since 2.18 an unavailable Guest count entry feature causes the field to be ignored.

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

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

{
  "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
  "guest-count": <int>,
  "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

guest-count int? (2.14+)
Number of guests to set on the order before it is issued. Same rules as for Update order: must be greater than 0 (2012), null clears the value, omitted field leaves it unchanged, and since 2.18 an unavailable Guest count entry feature causes the field to be ignored.

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>
}

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>
}

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

Change item's course (1.237+)

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

{
  "action": "order/prepare-next-course",
  "order-id": <long>
}

order-id long
ID of an order.

Print last document (SK, 2.10+)

Request:

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

Response

{
    "resultCode": <integer>,
}

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

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

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

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

Headers

Request Body