FORMAT: 1A
HOST: https://integrationapi.qnips.com
# Qnips Integration API
## General Information
The Qnips Integration API can be used to obtain menu card information.
The Qnips backend (**LIVE** = production-environment, **SANDBOX** = test-environment) provides hierarchical information on brands, partnerships, sortiments, stores and menu cards.
To use this API, Qnips will provide you with an `ApiKey`. With it, the API will identify brand and partnerships automatically, so that it only provides the relevant sortiments, stores etc.
## Multilanguage support in menu cards
The API is capable of delivering all strings relevant to menu card in different languages as long as the according
translations are supplied via Menu Card Manager in qnips Dashboard. In case there is no translation for a particular field
(i.e. product name, allergen name, tag name etc.) the returned value will fall back to the default language.
In order to get menu card data in a particular language just set the **Accept-Language**-Header of the GET /Menus/{menuId} request described further below
to a standardized value as specified in https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language
## Authorization
To authenticate to this API, an `ApiKey` is required. Qnips will provide you with an `ApiKey` consisting of a public identifier in GUID/UUID format and a secret key of the following format:
`qnp_integration_{environment}_{key}`
e.g.
`qnp_integration_live_T6ePpfyoXuiaAW1djWxkzUdievYpuE87kMbwR5vJn0We1s8`
To authenticate to the API the secret key needs to be sent as the `Authorization` header of your requests (no authorization scheme):
`Authorization: qnp_integration_live_T6ePpfyoXuiaAW1djWxkzUdievYpuE87kMbwR5vJn0We1s8`
For any matters concerning your `ApiKey` (for example deactivation, rotation, etc.) please provide Qnips with the public GUID/UUID identifier and not the secret key.
## Obtaining stores [/Stores]
Before choosing a menu card, users need to select a store for which they want to see the menu. To get the information of all available stores, please use the following resource.
### Obtaining stores [GET]
+ Request
+ Headers
Authorization: The secret ApiKey provided to you by Qnips
+ Response 200
+ Body
[
{
"Id": 1,
"Name": "API Demo LIVE Store 1",
"PictureUrl": "https://qnips.blob.core.windows.net/livepics/store.jpg",
"LargePictureUrl": "https://qnips.blob.core.windows.net/livepics/store_large.jpg",
"Menus": [
{
"Id": 1,
"Name": "API Demo LIVE Menu 1-1"
},
{
"Id": 2,
"Name": "API Demo LIVE Menu 1-2"
}
]
},
{
"Id": 2,
"Name": "API Demo LIVE Store 2",
"PictureUrl": "https://qnips.blob.core.windows.net/livepics/store2.jpg",
"LargePictureUrl": "https://qnips.blob.core.windows.net/livepics/store2.jpg",
"Menus": [
{
"Id": 3,
"Name": "API Demo LIVE Menu 1-2"
}
]
}
]
## Requesting a menu card [/Menus/{menuId}?type={type}&date={date}&includeMeta={includeMeta}]
This interface provides the information about the menu card with the given id
### Requesting a menu card by id [GET]
### Property Description
|Property|Data type|Description|
|:---:|:---:|:---|
|**MondayOfWeek**|*DateTime*|Date of the given calenderweek's monday.|
|**Rows**|*Array[Object]*|Categories included in this menu card.|
|**Type**|*Integer*|Describes the behaviour of products in this category
`0` = DailyChangingContent
`1` = SameContentEachDay.|
|**Days**|*Object*|The object holding all the weekdays with their respective products in this category.|
|**Allergens**|*Array[Integer]*|List of allergen IDs contained by a product.|
|**SubAllergens0**|*Array[Integer]*|List of sub-allergen IDs contained by a product.|
|**SubAllergens7**|*Array[Integer]*|List of sub-allergen IDs contained by a product.|
|**Traces**|*Array[Integer]*|List of IDs of allergen traces that can be contained by this product.|
|**SubTraces0**|*Array[Integer]*|List of IDs of sub-allergen traces that can be contained by this product.|
|**SubTraces7**|*Array[Integer]*|List of IDs of sub-allergen traces that can be contained by this product.|
|**AdditiveIds**|*Array[Integer]*|List of additive IDs contained by this product.|
|**TagIds**|*Array[Integer]*|List of "CustomTag" IDs assigned to this product.|
|**Ingredients**|*String*|A semicolon-seperated list of ingredients used to prepare this product.
Example: Filet-Steak;Chanterelle;Onion|
|**Prices**
in a product|*Array[Object]*|A list of all prices available for this product. Object structure:
`PriceId`(ID of the PriceTag)
`CurrencyIso` (ISO Code of the currency)
`Value`.|
|**CoverUrls**|*Array[String]*|A list of picture URLs linking to pictures chosen for this product.|
|**WeightInGrams**|*Decimal*|Weight of the product in grams.|
|**VolumeInMilliliters**|*Decimal*|Volume of the product in milliliters.|
|**NutritionFacts**|*Object*|An object containing the nutritional value of this product.
The following nutritional values can be displayed:
`KCal` Kilocalories
`KJ` Kilojoule
`Fats`
`Sats` Saturated fatty acids
`Monounsats` Monounsaturated fatty acids
`Polyunsats` Polyunsaturated fatty acids
`Carbs` Carbohydrates
`Sugar`
`Alcohol`
`Amylum`
`Proteins`
`Roughage`
`Salt`
All of these properties can be displayed either per serving or per 100 grams, which is shown by the suffix `PerServing` or `Per100` (e.g. `FatsPerServing`, `SugarPer100`)|
|**Infos**|*Array[Object]*|A list of objects containing information about this product.
Object structure:
**{
"Title"="Info1",
"Message"="Information about this product",
"PictureUrl"="https://qnips.blob.core.windows.net/prodpics/12345.jpg",
"MediaType"="0",
"AutoPlay"="false"
}**
Available `MediaType`s:
`0` = Image
`1` = Video
`PictureUrl` is used for both `MediaType`s|
|**CO2Info**|*Object*|An object containing information about the amount of CO2 emitted during the production of this product.
Object structure:
**{
"Rating"="A",
"Value"=100,5
}**
`Rating` is a scale from A to E, which describes the severity of the emission
`Value` provides the value of the CO2 emission in grams|
|**Ratings**|*Object*|An object containing the information about the rating.
Object structure:
**{
"1"={
"Value":123.4
}
}**
`"1"` is the id of the rating matching in the `RatingLabels`
`Value` provides the value of the Rating|
|**AppMeta**|*Object*|An object containing metadata about this product.
Object structure:
**{
"DisplayOptions": 7100,
"WeeksToPreview": 4,
"WeekDays": [
0,
1,
2,
3,
4
],
"ShowNextDayTime": "15:00:00"
}**
`DisplayOptions` is a bitmask describing how the product is supposed to be displayed in the app. The reference sheet for the different meanings of the bits can be found below
`WeeksToPreview` shows how many weeks of data should be loaded in advance
`WeekDays` contains the IDs of the weekdays that should be displayed in the app
`ShowNextDayTime` provides the time at which the next day is to be shown
`DailyAllergensTime` provides the time at which the relevant allergens for the day should be displayed
`EmptyMessage` is the message that is to be displayed when the menu card is empty
`EmptyCategoryMessage` is the message that is to be displayed in place of an empty category|
|**Additives**|*Array[Objekt]*|A list of all additives that could be contained by products of this menu card.
Object structure:
**{
"Id": 235,
"Name": "contains Phosphat",
"Label": "10"
}**
`Label` is what is displayed by the app instead of the full name|
|**Tags**|*Array[Object]*|A list of "CustomTags" that are available for products of this menu card.
Object structure:
**{
"Id": 239,
"Name": "contains Beef",
"Label": "",
"IconUrl": "https://qnips.blob.core.windows.net/customtagproposalicons/Rind_Icon.png"
}**|
|**RatingLabels**|*Array[Object]*|A list of "RatingLabels" that are available for products of this menu card.
Object structure:
**{
"Id":1,
"Name":"Vital",
"Type":3,
"IconUrl":"https://qnips.blob.core.windows.net/customtagproposalicons/Rind_Icon.png",
"ThirdPartyId":"Vital_1"
}**|
|**Prices**
in root of the response|*Array[Object]*|A list of pricetags available for the products of this menu card.
Object structure:
**{
"Id": 36,
"Name": "internal"
}**|
### `DisplayOptions`
|Bit|Meaning|
|:---|:---|
|0|Categories will be displayed in a seperate View. If 0: Categories will be displayed as section headers.|
|1|Deprecated|
|2|Display pictures in the list of products.|
|3|Display pictures in the product details view.|
|4|Display allergens & additives in the product details.|
|5|Display allergen traces in the product details.|
|6|Display the recipe in the product details.|
|7|Display nutrition facts in the product details.|
|8|Display allergens in the list of products.|
|9|Display the "CustomTags" in the list of products.|
|10|Display prices in the list of products.|
|11|Display product details.|
|12|Display the rating of the product. The API for product ratings is not yet available. If this is wanted then please discuss this with your contact at Qnips.|
|13|Display the image uploaded with a rating for a product. The API for product ratings is not yet available. If this is wanted then please discuss this with your contact at Qnips.|
### `Allergens`
|Id|Allergen|
|:---|:---|
|0|Grains containing gluten|
|1|Shellfish|
|2|Egg|
|3|Fish|
|4|Peanut|
|5|Soy|
|6|Milk|
|7|Nuts|
|8|Celery|
|9|Mustard|
|10|Sesame|
|11|Sulphites|
|12|Lupin|
|13|Molluscs|
### `SubAllergens0` and `SubTraces0`
|Id|SubAllergen|
|:---|:---|
|0|Wheat|
|1|Rye|
|2|Barley|
|3|Oats|
### `SubAllergens7` and `SubTraces7`
|Id|SubAllergen|
|:---|:---|
|0|Almond|
|1|Hazelnut|
|2|Walnut|
|3|Cashew|
|4|Pecan|
|5|Brazil|
|6|Pistachio|
|7|Macadamia|
### `Type` of `RatingLabel`
|Id|Type|
|:---|:---|
|0|Nutrition|
|1|CO2|
|2|WaterFootprint|
|3|HealthScore|
|4|AnimalTreatment|
|5|Rainforest|
+ Request
+ Headers
Authorization: The secret ApiKey provided to you by Qnips
Accept-Language: A prioritized list of languages that the menu card is to be displayed in. The first language that the menu card provides values for will be chosen from the list and displayed.
+ Parameters
+ menuId (long, required) - The ID of the menu card
+ type (int, required) - The type of platform that the request was sent from.
**0** = App
**1** = Web
+ date (datetime, optional) - The date of the day of which the content is to be displayed. The default value is the server time.
+ includeMeta (boolean, optional) - Decides whether the meta information is to be included. The default value is **true**.
+ Response 200
+ Body
{
"MenuCardId": 1234,
"StoreId": 12,
"Name": "Store 1 Card",
"MondayOfWeek": "2017-10-23T00:00:00Z",
"Rows": [
{
"Id": 2469,
"ThirdPartyId": "Vegan",
"Name": "API Demo LIVE Menu 1-1",
"Type": 0,
"Days": {
"0": [
{
"Id": 5821366,
"Name": "Braised pork goulash with mushroom gravy, a small salad and spaetzle",
"PictureUrl": "https://qnips.blob.core.windows.net/prodpics/16238.jpg",
"Allergens": [
0,
2,
9,
11
],
"SubAllergens0": [
0
],
"SubAllergens7": [],
"AdditiveIds": [],
"TagIds": [],
"CoverUrls": [],
"NutritionFacts": {
"KCalPerServing": 607,
"KJPerServing": 2544,
"FatsPerServing": 25.51,
"SatsPerServing": 5.9,
"CarbsPerServing": 71.15,
"SugarPerServing": 4.27,
"ProteinsPerServing": 22.88,
"SaltPerServing": 5.45
},
"Ratings": {
"1" : {
"Value": 123.4
}
}
}
],
"1": [
{
"Id": 5775966,
"Name": "Cheese bratwurst with bavarian coleslaw, parsley potatoes and sweet mustard",
"PictureUrl": "https://qnips.blob.core.windows.net/prodpics/16241.jpg",
"Allergens": [
6,
9
],
"SubAllergens0": [],
"SubAllergens7": [],
"AdditiveIds": [],
"TagIds": [],
"CoverUrls": [
"https://qnips.blob.core.windows.net/prodpics/16241.jpg"
],
"NutritionFacts": {
"KCalPerServing": 634,
"KJPerServing": 2654,
"FatsPerServing": 39.94,
"SatsPerServing": 15.38,
"CarbsPerServing": 43,
"SugarPerServing": 16.1,
"ProteinsPerServing": 25.36,
"SaltPerServing": 4.16
},
"Infos": []
}
],
"2": [
{
"Id": 5775969,
"Name": "Turkey ragout with grilled vegetables, paprika sauce, fried champignons and rice",
"PictureUrl": "https://qnips.blob.core.windows.net/prodpics/16245.jpg",
"Allergens": [
9
],
"SubAllergens0": [],
"SubAllergens7": [],
"AdditiveIds": [],
"TagIds": [],
"CoverUrls": [
"https://qnips.blob.core.windows.net/prodpics/16245.jpg"
],
"NutritionFacts": {
"KCalPerServing": 591,
"KJPerServing": 2471,
"FatsPerServing": 15.28,
"SatsPerServing": 1.84,
"CarbsPerServing": 88.21,
"SugarPerServing": 7.57,
"ProteinsPerServing": 23.93,
"SaltPerServing": 6.35
}
}
],
"3": [
{
"Id": 5775972,
"Name": "Vegetable stew with tomatoes, cabbage, beans, sour cream and cress",
"PictureUrl": "https://qnips.blob.core.windows.net/prodpics/16249.jpg",
"Allergens": [
0,
2,
4,
5,
6,
9,
10
],
"SubAllergens0": [
0,
1,
2
],
"SubAllergens7": [],
"AdditiveIds": [],
"TagIds": [],
"CoverUrls": [
"https://qnips.blob.core.windows.net/prodpics/16249.jpg"
],
"NutritionFacts": {
"KCalPerServing": 412,
"KJPerServing": 1720,
"FatsPerServing": 18.51,
"SatsPerServing": 9,
"CarbsPerServing": 44.5,
"SugarPerServing": 10.95,
"ProteinsPerServing": 16.36,
"SaltPerServing": 7.45
}
}
],
"4": [
{
"Id": 5775975,
"Name": "Baked plaice with Dijon mustard filling, green sauce and a potatoe-radish salad",
"PictureUrl": "https://qnips.blob.core.windows.net/prodpics/16254.jpg",
"Allergens": [
0,
2,
3,
6,
9
],
"SubAllergens0": [
0
],
"SubAllergens7": [],
"AdditiveIds": [
234
],
"TagIds": [],
"CoverUrls": [
"https://qnips.blob.core.windows.net/prodpics/16254.jpg"
],
"NutritionFacts": {
"KCalPerServing": 654,
"KJPerServing": 2738,
"FatsPerServing": 42.12,
"SatsPerServing": 4.83,
"CarbsPerServing": 48.91,
"SugarPerServing": 14.78,
"ProteinsPerServing": 20.47,
"SaltPerServing": 5.05
}
}
]
}
}
],
"AppMeta": {
"DisplayOptions": 7100,
"WeeksToPreview": 4,
"WeekDays": [
0,
1,
2,
3,
4
],
"ShowNextDayTime": "15:00:00"
},
"Additives": [
{
"Id": 234,
"Name": "waxed",
"Label": "4"
},
{
"Id": 235,
"Name": "contains phosphat",
"Label": "10"
},
{
"Id": 236,
"Name": "contains sweeteners",
"Label": "11"
}
],
"Tags": [
{
"Id": 239,
"Name": "contains beef",
"Label": "",
"IconUrl": "https://qnips.blob.core.windows.net/customtagproposalicons/Rind_Icon.png"
},
{
"Id": 240,
"Name": "contains pork",
"Label": "",
"IconUrl": "https://qnips.blob.core.windows.net/customtagproposalicons/Schwein_Icon.png"
},
{
"Id": 245,
"Name": "vegetarian",
"Label": "",
"IconUrl": "https://qnips.blob.core.windows.net/customtagproposalicons/Vegetarisch_Icon.png"
}
],
"RatingLabels": [
{
"Id": 1,
"Name": "Vital",
"Type": 3,
"IconUrl": "https://qnips.blob.core.windows.net/customtagproposalicons/Vegetarisch_Icon.png",
"ThirdPartyId": "Vital_1"
}
],
"Prices": [
{
"Id": 35,
"Name": "internal"
},
{
"Id": 36,
"Name": "external"
},
{
"Id": 330,
"Name": "small"
},
{
"Id": 331,
"Name": "large"
}
]
}