Product

Warning

Please see the Breaking changes page for more info on the planned changes in validation.

Product schema

id long?
Product ID - cannot be null in PUT/PATCH methods
📶 EQUALS,ENUM 🔽 NONE

_categoryId long
Category ID
📶 EQUALS,ENUM 🔽 NONE

_cloudId integer
Cloud ID
🔽 NONE

_defaultCourseId long?
Course ID
📶 EQUALS,ENUM

_eetSubjectId long?
EET Subject ID
📶 EQUALS,ENUM 🔽 NONE

_supplierId long?
Supplier ID
📶 EQUALS,ENUM 🔽 NONE

allergens int[]
Product allergens in the form of numbers. See the Annex II in the Regulation (EU) No 1169/2011.

alternativeName string?
Product alternative name

currency string?(3)
Currency code
🔽 NONE

deleted boolean
Product deleted - cannot be true in POST/PUT/PATCH methods
📶 EQUALS, ENUM 🔽 BOTH

deliveryNoteIds string?
Delivery note IDs
🔽 NONE

description string?(1000)
Product description
🔽 NONE

discountPercent double
Discount percent
🔽 NONE

discountPermitted boolean
Discount permitted
📶 EQUALS, ENUM

display boolean
Product displayed
📶 EQUALS, ENUM 🔽 BOTH

ean string[]?
EAN codes
📶 EQUALS, ENUM 🔽 BOTH (sort by the first EAN code in the list)

externalId string?
External ID
📶 EQUALS,ENUM 🔽 NONE

features string[]
Product features like spicy, vegan etc. primarily used for EOS

flags integer
Product flags
📶 BITS 🔽 NONE

hexColor string(7)
Product color
🔽 NONE

imageUrl string?
Product image for EOS services. The value of this field can only be deleted by setting it to null. Non-null values will be ignored.

margin string?(50)
Product margin as an exact value (plain number without a currency symbol) or a percentage (number followed by a '%' sign). If the percentage format is used the margin must be <= 100%.
🔽 NONE

marginMin double?
Minimal margin
🔽 NONE

modifiedBy string?(32)
Product modified by
🔽 NONE

name string(400)
Product name
📶 STRING🔽 BOTH

notes string[]?(1000)
Product notes
🔽 NONE

onSale boolean
Discount offer
📶 EQUALS, ENUM

packageItem double?
Item's package
🔽 NONE

packaging double
Number of items in a package
🔽 NONE

packagingMeasurement double?
Measurement packaging for product
🔽 NONE

packagingPriceWithVat double?
Price of the packaging with VAT primarily used for EOS
🔽 NONE

plu string[]?
PLU codes
🔽 EQUALS, ENUM 🔽 BOTH (sort by the first PLU code in the list)

points double
Points for buying the product
🔽 NONE

preparationDuration integer?
The time in seconds needed to prepare the product
🔽 NONE

priceInPointsdouble
Price value in points

priceWithVat double?
Price with VAT
📶 EQUALS, ENUM 🔽 BOTH

priceWithVatB double?
Alternative price with vat B

priceWithVatC double?
Alternative price with vat C

priceWithVatD double?
Alternative price with vat D

priceWithVatE double?
Alternative price with vat E

priceWithoutVat double
Price without VAT
🔽 BOTH

purchasePriceWithoutVat double?
Purchase price without VAT
🔽 NONE

Warning

This field has been deprecated. It is ignored in update requests and not returned in responses.

requiresPriceEntry boolean
Product requires price entry - must be set the same as the flag REQUIRES_PRICE_ENTRY because both values are used by our systems.
📶 EQUALS, ENUM

sortOrder long?
Product sort order
🔽 NONE

stockDeduct boolean
Product is deducted from Warehouse
📶 EQUALS, ENUM

stockOverdraft enum
Stock overdraft allows to set whether the product can be sold even if its quantity in the stock is equal or less than 0 - or just display a warning in that case
🔽 NONE

subtitle string?(500)
Product subtitle
🔽 NONE

supplierProductCode string?
Supplier's product code
🔽 NONE

tags string[]?
Tags for a product, must not contain any of these characters: ,^?*()[]$
📶 EQUALS, ENUM

translatedDescription map\?
A mapping of language codes to translated product descriptions.
🔽 NONE

translatedName map\?
A mapping of language codes to translated product names.
🔽 NONE

unit enum
Product unit
📶 EQUALS 🔽 NONE

unitMeasurement enum?
Units for product measurement
🔽 NONE

vat double
VAT value (a multiplier from range <1.0; 2.0>, f.e. vat=1.234 corresponds to VAT 23.4%)
📶 EQUALS 🔽 BOTH

Warning

For VAT payers this value is validated and it must correspond to one of the configured VAT rates.

versionDate timestamp?
Last modification date and time
📶 EQUALS, ENUM, NUMBER 🔽 BOTH

Product.stockOverdraft (enum)

// representation like string
ALLOW, WARN, DISABLE

Product response

{
    "_categoryId": <long>,
    "_cloudId": <integer>,
    "_defaultCourseId": <long>,
    "_eetSubjectId": <long>,
    "_supplierId": <long>,
    "alternativeName": <string>,
    "currency": <string>,
    "deleted": <boolean>,
    "deliveryNoteIds": <string>,
    "description": <string>,
    "discountPercent": <double>,
    "discountPermitted": <boolean>,
    "display": <boolean>,
    "ean": <string[]>,
    "externalId": <string>,
    "flags": <integer>,
    "hexColor": <string>,
    "id": <long>,
    "margin": <string>,
    "marginMin": <double>,
    "modifiedBy": <string>,
    "name": <string>,
    "notes": <string[]>,
    "onSale": <boolean>,
    "packageItem": <double>,
    "packaging": <double>,
    "packagingMeasurement": <double>,
    "plu": <string>,
    "points": <double>,
    "preparationDuration": <integer>,
    "priceInPoints": <double>,
    "priceWithVat": <double>,
    "priceWithVatB": <double>,
    "priceWithVatC": <double>,
    "priceWithVatD": <double>,
    "priceWithVatE": <double>,
    "priceWithoutVat": <double>,
    "purchasePriceWithoutVat": <double>,
    "requiresPriceEntry": <boolean>,
    "sortOrder": <long>,
    "stockDeduct": <boolean>,
    "stockOverdraft": <enum>,
    "subtitle": <string>,
    "supplierProductCode": <string>,
    "tags": <string[]>,
    "translatedDescription": <map<string, string>>,
    "translatedName": <map<string, string>>,
    "unit": <enum>,
    "unitMeasurement": <enum>,
    "vat": <double>,
    "versionDate": <timestamp>
}

Product flags

Bit	Name
0	SHORTCUT
1	REQUIRES_QUANTITY_ENTRY
2	REQUIRES_PRICE_ENTRY
3	TIMEABLE
5	MANUAL_SALE_ITEM
6	TIMEABLE_LOCKED
7	JOINT_SALE_ITEM
8	FISCALIZATION_DISABLED
10	ASSEMBLED_ITEM
11	TAKE_AWAY
12	TAKE_AWAY_ITEM
13	SPECIAL
14	WITH_CUSTOMIZATIONS
15	EXEMPTED_VAT
18	UNCERTIFIED_QUANTITY(18)

Get products

GET https://api.dotykacka.cz/v2/clouds/:cloudId/products

Path Parameters

Name	Type	Description
cloudId*	integer

Query Parameters

Name	Type	Description
sort	string
filter	string
page	integer
limit	integer
include	array	Include other entities [1]

Headers

Name	Type	Description
If-None-Match	string	ETag to return results only if changed.
Authorization*	string	Bearer accessToken

200400404

[1] The following entities can be included in the response:

• customizations- list of customizations
• ingredients - list of ingredients Multiple entities can be included at the same time, f.e.: include=customizations,ingredients

Note that the client must have the proper permissions to read the included entity. The API2 will return HTTP error 403 Forbidden otherwise.

Response when other entities are included

{
    // paging data
    ...
    "data": [
        {
            // product fields
            ...
            "customizations": [
                {
                    // customization fields
                },
                ...
            ],
            "ingredients": [
                {
                    // ingredient fields
                },
                ...
            ]            
        },
        ...
    ]
}

Get product

GET https://api.dotykacka.cz/v2/clouds/:cloudId/products/:productId

Path Parameters

Name	Type	Description
cloudId*	integer
productId*	integer

Headers

Name	Type	Description
If-None-Match	string	ETag to return results only if changed.
Authorization*	string	Bearer accessToken

200400404

Create products

POST https://api.dotykacka.cz/v2/clouds/:cloudId/products

Path Parameters

Name	Type	Description
cloudId*	integer

Headers

Name	Type	Description
Authorization*	string	Bearer accessToken

Request Body

Name	Type	Description
	array	Array of products. Maximum size 100.

200400

// Body request minimum
[
    {
        "_categoryId": <long>,
        "deleted": <boolean>,
        "discountPercent": <double>,
        "discountPermitted": <boolean>,
        "display": <boolean>,
        "flags": <integer>,
        "hexColor": <string>,
        "name": <string>,
        "onSale": <boolean>,
        "packaging": <double>,
        "points": <double>,
        "priceWithoutVat": <double>,
        "requiresPriceEntry": <boolean>,
        "stockDeduct": <boolean>,
        "stockOverdraft": <enum>,
        "unit": <enum>,
        "vat": <double>
    }
]

Replace or create products

PUT https://api.dotykacka.cz/v2/clouds/:cloudId/products

Path Parameters

Name	Type	Description
cloudId*	integer

Headers

Name	Type	Description
If-Match	string	ETag to update only if not changed.
Authorization*	string	Bearer accessToken

Request Body

Name	Type	Description
	array	Array of products. Maximum size 100.

200

// Body request minimum
[
    {
        "_categoryId": <long>,
        "deleted": <boolean>,
        "discountPercent": <double>,
        "discountPermitted": <boolean>,
        "display": <boolean>,
        "flags": <integer>,
        "hexColor": <string>,
        "id": <long>,
        "name": <string>,
        "onSale": <boolean>,
        "packaging": <double>,
        "points": <double>,
        "priceWithoutVat": <double>,
        "requiresPriceEntry": <boolean>,
        "stockDeduct": <boolean>,
        "stockOverdraft": <enum>,
        "unit": <enum>,
        "vat": <double>
    }
]

Replace or create product

PUT https://api.dotykacka.cz/v2/clouds/:cloudId/products/:productId

Path Parameters

Name	Type	Description
cloudId*	integer
productId*	integer

Headers

Name	Type	Description
If-Match	string	ETag to update only if not changed.
Authorization*	string	Bearer accessToken

Request Body

Name	Type	Description
	object	Product

200400500

// Body request minimum
{
    "_categoryId": <long>,
    "deleted": <boolean>,
    "discountPercent": <double>,
    "discountPermitted": <boolean>,
    "display": <boolean>,
    "flags": <integer>,
    "hexColor": <string>,
    "id": <long>,
    "name": <string>,
    "onSale": <boolean>,
    "packaging": <double>,
    "points": <double>,
    "priceWithoutVat": <double>,
    "requiresPriceEntry": <boolean>,
    "stockDeduct": <boolean>,
    "stockOverdraft": <enum>,
    "unit": <enum>,
    "vat": <double>
}

Partial update of Product

PATCH https://api.dotykacka.cz/v2/clouds/:cloudId/products/:productId

Path Parameters

Name	Type	Description
cloudId*	integer
productId*	integer

Headers

Name	Type	Description
If-Match*	string	ETag to update only if not changed.
Authorization*	string	Bearer accessToken

Request Body

Name	Type	Description
	object	Part of product object

200404

Delete product

DELETE https://api.dotykacka.cz/v2/clouds/:cloudId/products/:productId

Path Parameters

Name	Type	Description
cloudId*	integer
productId*	integer

Headers

Name	Type	Description
If-Match	string	ETag ignored (temporarily) when deleting an entity.
Authorization*	string	Bearer accessToken

Request Body

Name	Type	Description
productIsIngredient	string	Strategy when product is an ingredient [1]
productHasIngredients	string	Strategy when product has ingredients [1]

200404409: Conflict If product are used in EOS integration cannot be deleted.

{
    // Response
}

[1] Can be one of the following: ERROR, PRESERVE, DELETE. An example BODY can look like this:

{
    "productIsIngredient": "DELETE",
    "productHasIngredients": "ERROR"
}

If no request BODY is sent (default) or a JSON object with the strategy ERROR is sent and the product has own ingredients or is an ingredient of another product then the API returns an error response with status 409 Conflict with a BODY like in this example:

{
    "timestamp": "2021-01-20T15:54:06.319+01:00",
    "status": "409",
    "error": "Conflict",
    "message": "The product is an ingredient",
    "resolution": {
        "productIsIngredient": [
            "ERROR",
            "PRESERVE",
            "DELETE"
        ],
        "productHasIngredients": [
            "ERROR",
            "PRESERVE",
            "DELETE"
        ]
    }
}

If a request with a strategy DELETE is issued and the product has own ingredients or is an ingredient of another product then the related ingredients are deleted. If a request with a strategy PRESERVE is issued then no ingredients are deleted (ingredients will be preserved).

If a request with a strategy DELETE is issued and the user does not have the permission to delete ingredients then the API returns the following error response:

{
    "timestamp": "2021-01-20T15:51:13.362+01:00",
    "status": "403",
    "error": "Forbidden",
    "message": "No permission to delete product ingredients"
}

Options products

OPTIONS https://api.dotykacka.cz/v2/clouds/:cloudId/products

Path Parameters

Name	Type	Description
cloudId*	integer

Headers

Name	Type	Description
Authorization*	string	Bearer accessToken

200

Options product

OPTIONS https://api.dotykacka.cz/v2/clouds/:cloudId/products/:productId

Path Parameters

Name	Type	Description
cloudId*	integer
productId*	integer

Headers

Name	Type	Description
Authorization*	string	Bearer accessToken

200