User Manual

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

email

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

PreviousBase Sales ReportNextRelease notes

Last updated