POS actions

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.

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.

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)

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.

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)

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

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

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

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

POS actions

Result codes

Basic request format

Hello (1.239.8+)

Response format

Create order

Update order

Add order items

Item

Item Customization

Split order (1.234)

Issue order

Pay issued order

Create and issue order (1.234)

Create, issue and pay order (1.234)

Split and issue order (1.234)

Split, issue and pay order (1.234)

Issue and pay

Cancel order (1.243+)

Change order status (1.234+, WIP)

Get list of open orders (1.235+)

Change item's course (1.237+)

Course Change

Prepare next course (1.237+)

Print last document (SK, 2.10+)

Request:

Response

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

Takeaway change

Shared types

Print type

Print config

Pass-through error (1.242+)

Possible pass-through errors

Response schema (default)

Multiple orders response schema

Pos actions

Path Parameters

Headers

Request Body