Product

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

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

Please do not round any price values (explained here)

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 šŸ“¶ EQUALS, ENUM

translatedDescription map<string, string>? A mapping of language codes to translated product descriptions. šŸ”½ NONE

translatedName map<string, string>? 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

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

NameTypeDescription

cloudId*

integer

Query Parameters

NameTypeDescription

sort

string

filter

string

page

integer

limit

integer

include

array

Include other entities [1]

Headers

NameTypeDescription

If-None-Match

string

ETag to return results only if changed.

Authorization*

string

Bearer accessToken

[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

NameTypeDescription

cloudId*

integer

productId*

integer

Headers

NameTypeDescription

If-None-Match

string

ETag to return results only if changed.

Authorization*

string

Bearer accessToken

Create products

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

Path Parameters

NameTypeDescription

cloudId*

integer

Headers

NameTypeDescription

Authorization*

string

Bearer accessToken

Request Body

NameTypeDescription

array

Array of products. Maximum size 100.

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

NameTypeDescription

cloudId*

integer

Headers

NameTypeDescription

If-Match

string

ETag to update only if not changed.

Authorization*

string

Bearer accessToken

Request Body

NameTypeDescription

array

Array of products. Maximum size 100.

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

NameTypeDescription

cloudId*

integer

productId*

integer

Headers

NameTypeDescription

If-Match

string

ETag to update only if not changed.

Authorization*

string

Bearer accessToken

Request Body

NameTypeDescription

object

Product

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

NameTypeDescription

cloudId*

integer

productId*

integer

Headers

NameTypeDescription

If-Match*

string

ETag to update only if not changed.

Authorization*

string

Bearer accessToken

Request Body

NameTypeDescription

object

Part of product object

Delete product

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

Path Parameters

NameTypeDescription

cloudId*

integer

productId*

integer

Headers

NameTypeDescription

If-Match

string

ETag ignored (temporarily) when deleting an entity.

Authorization*

string

Bearer accessToken

Request Body

NameTypeDescription

productIsIngredient

string

Strategy when product is an ingredient [1]

productHasIngredients

string

Strategy when product has ingredients [1]

[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

NameTypeDescription

cloudId*

integer

Headers

NameTypeDescription

Authorization*

string

Bearer accessToken

Options product

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

Path Parameters

NameTypeDescription

cloudId*

integer

productId*

integer

Headers

NameTypeDescription

Authorization*

string

Bearer accessToken

Last updated