API

Table of Contents

Welcome to Tickncook public API Documentation!

Introduction #

Goals #

This API has been opened, to let any entity integrate with Tickncook systems. It allows to create/modify catalogs, orders, to kitchens and accounrs.

Contacts #

To request credentials and for any question, remark or request for this public API, you can send an email to , don’t hesitate to contact our geek team, they are pretty reactive!

Online documentation #

For more details, all the details of the explained API in this page, can be found in the following online swagger documentation : https://api.tickncook.com/api/swagger/public/

Entities #

Accounts #

Accounts are entities, that gather kitchens together. An account can contain as much kitchens as you want, and will be shown in Tickncook top select box.
This can be seen as an image of a restaurant chain.

Kitchens #

A Kitchen is a physical location of a restaurant. It has to be contained in an account.

Users #

A user is an association of email, password and roles.
A user can have one or many of the following roles, following the hierarchy:

  • KITCHEN_USER: Associated with a kitchenId, can see and accept individual order items, change order status.
  • KITCHEN_ADMIN: KITCHEN_USER + Can add kitchen_users of the kitchen it administrates, modify and delete them.
  • ACCOUNT_ADMIN: associated with an accountId, It has KITCHEN_ADMIN of all the kitchens of the account, and can modify also some informations related to the account (account name, billing address, currency.)

 

 

Tickncook API endpoints #

Authentication #

Once you have credentials given by our team, you will be able to generate a token to communicate with Tickncook.

API Endpoint: https://api.tickncook.com/api/swagger/public/#/Authentication/clientAuth

curl --location --request POST 'https://api.tickncook.com/client/auth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"clientId": "clientId",
"clientSecret": "clientSecret"
}'

This will generate a JWToken, that will be valid for 24 hours. After that you will have to generate a new one. This token will have to be passed in the Authorization header of all further communications.

Catalogs #

Example of catalog to be created #

 

Tickncook stores a simplified version of catalogs generally stored into the POS system, because as it is only a Display system (KDS), it does not have to store complex details as modifiers sets, price modifier sets, complex menu sets. Pushing products and creating a catalog in Tickncook is relatively simple, then.
Catalogs in Tickncook are created with the following structure :

  • Catalog object : available for an entire account, it has a name and a posRef.
  • Categories: Inside a catalog, group product by categories, it has a name and a posRef.
  • Products: Instance of a product
  • SKU (Stock Keeping Unit): A single instance of a product.

For example, in the following API calls, let’s say that we want to create a catalog with the following structure :

Catalog: test-catalog (posRef test-catalog-ref)

  • Categories:
    • Burgers (posRef burgers)
      • Products:
        • Cheese burger: (posRef cheese-burger-ref)
          • Skus:
            • Normal (posRef cheese-burger-normal-ref)
            • Big (posRef cheese-burger-big-ref)
        • Farmer burger: (posRef farmer-burger-ref)
          • Skus
            • Normal (posRef farmer-burger-normal-ref)
            • Big (posRef farmer-burger-big-ref)
    • Drinks (posRef drinks)
      • Products:
        • Cola soda (posRef cola-soda-ref)
          • Skus:
            • 33cl (posRef cola-soda-33-ref)
            • 50cl (posRef cola-soda-50-ref)

 

We have to create and synchronize all these entities in Tickncook, before being able to actually create and push orders. The orders items will always contain only skus.
In several use cases, there will be a 1-1 mapping between products and skus, as not all the POS systems make a difference between a product and a sku.

 

Create a catalog with only 1 http call (recommended way) #

API Endpoint: https://api.tickncook.com/api/swagger/public/#/Products%2C%20categories%2C%20options%20and%20catalogs/catalogBulkUpdate

curl --location --request PUT 'https://api.tickncook.com/account/{accountId}/catalog/bulk' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data-raw '{
 "name": "test-catalog",
 "posRef": "test-catalog-posref"
 "categories": [
  {
    "name": "burgers",
    "posRef": "burgers",
    "metaCategory": "MAIN_DISHES",
    "products": [
      {
        "name": "Cheese burger",
        "posRef": "cheese-burger-ref",
        "skus": [
          {
            "name": "normal",
            "skuRef": "cheese-burger-normal-ref"
          },
          {
            "name": "big",
            "skuRef": "cheese-burger-big-ref"
          }
        ]
      }
    ]
   }
 ]
}'

This endpoint is idempotent, meaning that if you call this twice with the exact payload, the second call will have no effect.

Create a catalog #

API Endpoint: https://api.tickncook.com/api/swagger/public/#/Products%2C%20categories%2C%20options%20and%20catalogs/createCatalog

curl --location --request PUT 'https://api.tickncook.com/account/{accountId}/catalog' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data-raw '{
"name": "test-catalog",
"posRef":"test-catalog-ref"
}'

This http request will return back a catalogId, that you will re-use.

 

Create 2 categories in this catalog #

API Endpoint: https://api.tickncook.com/api/swagger/public/#/Products%2C%20categories%2C%20options%20and%20catalogs/createCategory

curl --location --request PUT 'https://api.tickncook.com/account/{accountId}/catalog/category' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data-raw '{
"name": "Burgers",
"posRef":"burgers",
"catalogId":"{catalogId}"
}'

curl --location --request PUT 'https://api.tickncook.com/account/{accountId}/catalog/category' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data-raw '{
"name": "Drinks",
"posRef":"drinks",
"catalogId":"{catalogId}"
}'

 

 

Create products in these categories #

API Endpoint: https://api.tickncook.com/api/swagger/public/#/Products%2C%20categories%2C%20options%20and%20catalogs/createProduct

curl --location --request PUT 'https://api.tickncook.com/account/{accountId}/catalog/product' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data-raw '{
"name": "Cheese burger",
"posRef":"cheese-burger-ref",
"catalogId": "{catalogId}",
"categoryId":"{categoryId}" <=== Category corresponding to the burgers one.
}'

curl --location --request PUT 'https://api.tickncook.com/account/{accountId}/catalog/product' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data-raw '{
"name": "Farmer burger",
"posRef":"farmer-burger-ref",
"catalogId": "{catalogId}",
"categoryId":"{categoryId}" <=== Category corresponding to the burgers one.
}'

curl --location --request PUT 'https://dev.tickncook.com/account/{accountId}/catalog/product' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data-raw '{
"name": "Cola soda",
"posRef":"cola-soda-ref",
"catalogId": "{catalogId}",
"categoryId":"{categoryId}" <=== Category corresponding to the drinks one.
}'

 

 

Create Skus for these products #

API Endpoint: https://api.tickncook.com/api/swagger/public/#/Products%2C%20categories%2C%20options%20and%20catalogs/createSku

curl --location --request PUT 'https://api.tickncook.com/account/{accountId}/catalog/sku' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data-raw '{
"name": "Normal",
"posRef":"cheese-burger-normal-ref",
"catalogId": "{catalogId}",
"categoryId":"{categoryId}",
"productId":"{productId}"
}'

 

And repeat that operation for all the skus (changing of course the productId and categoryId of the particular skus you’re creating)

 

Delete an un-used catalog #

API Endpoint: https://api.tickncook.com/api/swagger/public/#/Products%2C%20categories%2C%20options%20and%20catalogs/createSku

curl --location --request DELETE 'https://api.tickncook.com/catalog/{catalogId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data-raw '{}'

 

 

Check the content of a catalog #

API Endpoint: https://api.tickncook.com/api/swagger/public/#/Products%2C%20categories%2C%20options%20and%20catalogs/getAccountCatalogs
From here you will be able to get the catalog, and if you followed the above steps, it should look like that :

{
"_id": "6263d7932bb24a838871a014",
"catalogType": "API",
"catalogLang": "EN",
"posRef": "test-catalog-ref",
"accountId": "625de2a3ea632419354f623c",
"name": "test-catalog",
"updatedAt": "2022-04-23T10:40:19.726Z",
"createdAt": "2022-04-23T10:40:19.726Z",
"__v": 0,
"productCategories": [
{
"_id": "6263dbfc900f3f8f1d7012b6",
"tickncookMetaCategory": "STARTERS",
"posRef": "burgers",
"parentCategoryId": null,
"catalogId": "6263d7932bb24a838871a014",
"name": "Burgers",
"updatedAt": "2022-04-23T10:59:08.441Z",
"createdAt": "2022-04-23T10:59:08.441Z",
"__v": 0
},
{
"_id": "6263dc7e900f3f8f1d7012cc",
"tickncookMetaCategory": "STARTERS",
"posRef": "drinks",
"parentCategoryId": null,
"catalogId": "6263d7932bb24a838871a014",
"name": "Drinks",
"updatedAt": "2022-04-23T11:01:18.680Z",
"createdAt": "2022-04-23T11:01:18.680Z",
"__v": 0
}
],
"products": [
{
"_id": "6263df1a900f3f8f1d7012f3",
"posRef": "cheese-burger-ref",
"categoryId": "6263dbfc900f3f8f1d7012b6",
"catalogId": "6263d7932bb24a838871a014",
"name": "Cheese burger",
"updatedAt": "2022-04-23T11:12:26.687Z",
"createdAt": "2022-04-23T11:12:26.687Z",
"__v": 0
},
{
"_id": "6263dfc44ec4fc8f7b9c69ca",
"posRef": "farmer-burger-ref",
"categoryId": "6263dbfc900f3f8f1d7012b6",
"catalogId": "6263d7932bb24a838871a014",
"name": "Farmer burger",
"updatedAt": "2022-04-23T11:15:16.235Z",
"createdAt": "2022-04-23T11:15:16.235Z",
"__v": 0
},
{
"_id": "6263dfd84ec4fc8f7b9c69d3",
"posRef": "cola-soda-ref",
"categoryId": "6263dc7e900f3f8f1d7012cc",
"catalogId": "6263d7932bb24a838871a014",
"name": "Cola soda",
"updatedAt": "2022-04-23T11:15:36.317Z",
"createdAt": "2022-04-23T11:15:36.317Z",
"__v": 0
}
],
"productSkus": [
{
"_id": "6263e2df6a53818fe007bf8a",
"optionListsAvailable": [],
"posRef": "cheese-burger-normal-ref",
"categoryId": "6263dbfc900f3f8f1d7012b6",
"productId": "6263df1a900f3f8f1d7012f3",
"catalogId": "6263d7932bb24a838871a014",
"name": "Normal",
"updatedAt": "2022-04-23T11:28:31.540Z",
"createdAt": "2022-04-23T11:28:31.540Z",
"__v": 0
},
{
"_id": "6263e3056a53818fe007bfa0",
"optionListsAvailable": [],
"posRef": "cheese-burger-big-ref",
"categoryId": "6263dbfc900f3f8f1d7012b6",
"productId": "6263df1a900f3f8f1d7012f3",
"catalogId": "6263d7932bb24a838871a014",
"name": "Big",
"updatedAt": "2022-04-23T11:29:09.523Z",
"createdAt": "2022-04-23T11:29:09.523Z",
"__v": 0
},
{
"_id": "6263e31c6a53818fe007bfaa",
"optionListsAvailable": [],
"posRef": "farmer-burger-big-ref",
"categoryId": "6263dbfc900f3f8f1d7012b6",
"productId": "6263dfc44ec4fc8f7b9c69ca",
"catalogId": "6263d7932bb24a838871a014",
"name": "Big",
"updatedAt": "2022-04-23T11:29:32.175Z",
"createdAt": "2022-04-23T11:29:32.175Z",
"__v": 0
},
{
"_id": "6263e3236a53818fe007bfb4",
"optionListsAvailable": [],
"posRef": "farmer-burger-normal-ref",
"categoryId": "6263dbfc900f3f8f1d7012b6",
"productId": "6263dfc44ec4fc8f7b9c69ca",
"catalogId": "6263d7932bb24a838871a014",
"name": "Normal",
"updatedAt": "2022-04-23T11:29:39.772Z",
"createdAt": "2022-04-23T11:29:39.772Z",
"__v": 0
},
{
"_id": "6263e3536a53818fe007bfbe",
"optionListsAvailable": [],
"posRef": "cola-soda-33-ref",
"categoryId": "6263dc7e900f3f8f1d7012cc",
"productId": "6263dfd84ec4fc8f7b9c69d3",
"catalogId": "6263d7932bb24a838871a014",
"name": "33cl",
"updatedAt": "2022-04-23T11:30:27.181Z",
"createdAt": "2022-04-23T11:30:27.181Z",
"__v": 0
},
{
"_id": "6263e35b6a53818fe007bfc8",
"optionListsAvailable": [],
"posRef": "cola-soda-50-ref",
"categoryId": "6263dc7e900f3f8f1d7012cc",
"productId": "6263dfd84ec4fc8f7b9c69d3",
"catalogId": "6263d7932bb24a838871a014",
"name": "50cl",
"updatedAt": "2022-04-23T11:30:35.408Z",
"createdAt": "2022-04-23T11:30:35.408Z",
"__v": 0
}
],
"optionLists": []
}

 

Orders #

Push an order to a kitchen (Idempotent , new recommended way) #

This is a new endpoint, that provides more stability over integrations. This is the only endpoint to talk to, to create/modify/cancel an order into Tickncook.
This endpoint has to be called, with the status at a given moment of an order. If items are removed, added, Tickncook systems will handle all these changes.

API Endpoint: https://api.tickncook.com/api/swagger/public/#/Orders%20-%20by%20posRef/createOrUpdateOrderByPosRef

curl --location --request PUT 'https://api.tickncook.com/kitchen/{kitchenId}/pos/order/order-ref-1234' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data-raw '{
"expectedTime": "2022-04-23T16:19:39.417Z",
"posRef":"order-ref-1234",
"items":[{
"quantity":"1",
"skuRef":"farmer-burger-big-ref",
"productName":"Farmer burger big"
}],
"serviceType":"DELIVERY",
"status":"NEW"
}'

#

Push an order to a kitchen #

API Endpoint: https://api.tickncook.com/api/swagger/public/#/Orders/createPosOrder

curl --location --request PUT 'https://api.tickncook.com/kitchen/{kitchenId}/pos/order' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data-raw '{
"expectedTime": "2022-04-23T16:19:39.417Z",
"posRef":"order-ref-1234",
"items":[{
"quantity":"1",
"skuRef":"farmer-burger-big-ref",
"productName":"Farmer burger big"
}],
"serviceType":"DELIVERY",
"status":"NEW"
}'

We always display the “productName” received in the order model, in Tickncook. It usually is productName + skuName, but you can override that by setting this productName (if the names change depending on special offers, or if you want to display something else into the KDS.) Although, the skuRef should be valid, and referenced as a SKU.posRef in our system, otherwise tickncook api will send back a 400 bad request.

#

More complex order examples #

2 Skus, collection code, and remarks on items #

{
"catalogPosRef": "{{catalogPosRef}}",
"expectedTime": "2022-04-23T16:19:39.417Z",
"posRef":"order-ref-123457",
"items":[
{
"quantity":"1",
"skuRef":"farmer-burger-big-ref",
"productName":"Farmer burger big"
},
{
"quantity":"2",
"skuRef":"cola-soda-33-ref",
"remark":"don't drink too much sugar!!",
"productName":"Coca 33cl"
}
],
"serviceType":"DELIVERY",
"collectionCode": "1234",
"status":"NEW"
}

 

Order with options, modifiers in items #

{
“catalogPosRef”: “{{catalogPosRef}}”, “expectedTime”: “2022-04-23T16:19:39.417Z”, “posRef”:”order-ref-123458″, “items”:[ { “quantity”:”1″, “skuRef”:”farmer-burger-big-ref”, “productName”:”Farmer burger big”, “options”: [ { “name”: “Mustard sauce”, “quantity”: “2” } ] }, { “quantity”:”2″, “skuRef”:”cola-soda-33-ref”, “remark”:”don’t drink too much sugar!!”, “productName”:”Coca 33cl” } ], “serviceType”:”DELIVERY”, “collectionCode”: “1234”, “status”:”NEW” }

 

 

Sandbox Postman collection #

Postman collection #

You can import this collection into postman :  https://www.getpostman.com/collections/7fd924dfcde633a1b770

You’ll have to attach an environment to your collection, and create the following variables :
–  url: https://api/tickncook.com
– clientId: Your client id
– clientSecret : Your client secret
– accountId: The Tickncook account id you’re integrating
– kitchenId: The Tickncook kitchen id you’re integrating

Create sandbox catalog, and test orders with postman collection #

The first step is to run the request “login with client credentials”. Then you’ll be able to generate the full example catalog from this page, by running the folder “Create Sample Catalog”. These requests will create variables into your environment (such as catalogId, etc.)
Then, you can play with Tickncook screen, and try to shoot the order examples you can find in the “Push test orders”

What are your Feelings