FORMAT: 1A
HOST: https://insights-live-eu.qnips.com/api/beta/
# Insights API (BETA VERSION)
The Qnips Insights API can be used to obtain transaction reports.
## Authorization
Basic access authentication of a dashboard account
Example:
username: `john.doe@example.com` password: `m2vIisIYEj0Z4yc`
Base64 encoding of `john.doe@example.com:m2vIisIYEj0Z4yc`: `am9obi5kb2VAZXhhbXBsZS5jb206bTJ2SWlzSVlFajBaNHlj`
Final value of the `Authorization` header: `BASIC am9obi5kb2VAZXhhbXBsZS5jb206bTJ2SWlzSVlFajBaNHlj`
## Obtaining stores [/Stores]
Before requesting a transaction report, users need to select a store for which they want to see the transactions.
To get the information of all available stores, please use the following resource.
An available store:
- has permission to the Insights API
- account has access to it
This endpoint is rate limited to 10 request per 60 seconds.
### Obtaining stores [GET]
+ Request
+ Headers
Authorization : Basic Authorization of a dashboard user (see introduction for more information)
+ Response 200
+ Body
[
{
"Id": "HAN-WDNDM838",
"Name": "API Demo Store 1",
"CustomId": "Demo 1",
},
{
"Id": "HAN-WDNDM839",
"Name": "API Demo Store 2",
"CustomId": "Demo 2",
}
]
## Transaction order report [/Orders?storeId={storeId}&from={from}&till={till}&cardId={cardId}&take={take}&skip={skip}&orderBy={orderBy}&sort={sort}]
This interface provides a transaction order report.
- The `till` date has to be greater than the `from` date.
- The `till` & `from` dates can at most be 92 days apart.
- The `take` parameter defaults to 100 and maximum is 3500.
- The `take` and `skip` parameters can be used for pagination
Example: `take=50` & `skip=150` will skip the orders 1-150 and retrieve orders 151-200
- `NULL` Properties are omitted.
- The properties marked with '*1' are omitted if 0.
- Date properties are in UTC.
- `storeId`, `till` & `from` are required.
T- his endpoint is rate limited to 10 request per 60 seconds.
Allowed `orderBy` values:
|Value|Data type|Default|
|:---:|:---:|:---:|
|OrderedForDate|*string*|X|
|SubmissionDate|*string*||
|PaymentDate|*string*||
|LastUpdatedDate|*string*||
Allowed `sort` values:
|Value|Data type|Default|
|:---:|:---:|:---:|
|asc|*string*|X|
|desc|*string*||
### Transaction order report [GET]
### Property Description
|Property|Data type|Description|
|:---:|:---:|:---|
|**TotalTransactionCount**|*int*|The total amount of transactions available in the requested time period for the store|
|**Transactions**|*Array[Object]*|Array of [`Transaction`](#refTransaction) objects holding the information about the transaction|
### `Transaction` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**Guid**|*string*|A guid|
|**ReceiptNumber**|*String*|The receipt number|
|**BasketId**|*String*|The basket identifier|
|**MenuCardId**|*Integer*|The id of the menu card|
|**Channel**|*String*|The source where the order came from|
|**PaymentState**|*String*|The current payment state|
|**IsCancelled**|*Boolean*|If the order was cancelled|
|**SubmissionDate**|*DateTime*|The date the order was submitted|
|**OrderedForDate**|*DateTime*|The date the order was ordered for|
|**LastUpdatedDate**|*DateTime*|The date the order was last modified in any way|
|**UserDetails**|*Object*|The [`UserDetails`](#refUserDetails) object holding information about the user|
|**DeliveryOption**|*Object*|The [`DeliveryOption`](#refDeliveryOption) object holding the information about the delivery option|
|**DeliveryLocation**|*Object*|The [`DeliveryLocation`](#refDeliveryLocation) object holding the information about the delivery location|
|**CurrencyCode**|*String*|The currency code|
|**Total**|*Integer*|The total amount paid in cents|
|**SubTotal**|*Integer*|The sub total amount paid in cents|
|**AdditionalCosts**|*Array[Object]*|An array of [`AdditionalCost`](#refAdditionalCost) objects that are holding information about the additional cost to the order|
|**Rewards**|*Object*|The [`Rewards`](#refRewards) object holding information about the rewards for the whole transaction *1|
|**Tax**|*Object*|The [`Tax`](#refTax) object holding information about the user tax for the whole transaction *1|
|**PaymentDetails**|*Object*|The [`PaymentDetails`](#refPaymentDetails) object holding the information about the payment|
|**Products**|*Array[Object]*|An array of [`Product`](#refProduct) objects that are holding information about the items ordered|
### `UserDetails` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**ProfileId**|*String*|The id of the user|
|**FullName**|*String*|The full name of the user|
|**PhoneNumber**|*String*|The phone number of the user|
|**Email**|*String*|The email of the user|
|**IsRegistered**|*Boolean*|Whether the user is registered or anonymous|
|**IsSsoRegistered**|*Boolean*|Whether the user is sso registered|
### `DeliveryOption` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**Description**|*String*|The description of the delivery option|
|**Name**|*String*|The name of the delivery option|
### `DeliveryLocation` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**Name**|*Integer*|The name of the delivery location|
|**InternalName**|*String*|The internal name of the delivery location|
### `AdditionalCost` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**InternalName**|*String*|The internal name of the additional cost|
|**CurrencyCode**|*String*|The currency code|
|**Amount**|*Integer*|The amount in cent of the additional cost|
### `Rewards` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**Amount**|*Integer*|The total amount of the rewards of the entire transaction in pennies|
|**Details**|*Array[Object]*|An array of [`Detail`](#refDetail) objects holding information about rewards|
### `Detail` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**Id**|*Integer*|The database id|
|**Name**|*String*|The name of the type of reward|
|**Value**|*String*|The sum values of the entire (transaction/item/option) of the same type of reward|
### `Tax` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**Amount**|*Integer*|The total amount of the taxes of the entire transaction in pennies|
|**Details**|*Array[Object]*|An array of [`Detail`](#refDetailTax) objects holding information about tax|
### `Detail` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**Id**|*Integer*|The database id|
|**Rate**|*Decimal*|The tax rate|
|**Name**|*String*|The tax name|
|**Amount**|*Integer*|The sum values of the entire (transaction/item/option) of the same type of tax in pennies|
### `PaymentDetails` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**PaymentOption**|*Object*|The [`PaymentOption`](#refPaymentOption) object holding information about the payment option|
|**BalanceTransaction**|*Object*|The [`BalanceTransaction`](#refBalanceTransaction) object holding information about the balance transaction|
|**PspTransactions**|*Array[Object]*|An array of [`PspTransaction`](#refPspTransaction) objects holding information about tax|
|**CostCenter**|*Object*|The [`CostCenter`](#refCostCenter) object holding information about the cost center|
### `PaymentOption` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**Name**|*String*|The name of the payment option|
|**ProviderInfoName**|*String*|The name of the payment provider|
### `BalanceTransaction` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**Description**|*String*|The description of the balance transaction|
|**Reference**|*String*|The reference of system that submitted the balance transaction|
|**CreationDate**|*DateTime*|The date the balance transaction was created|
|**MerchantReference**|*String*|The merchant reference of the balance transaction|
|**State**|*String*|The payment state of the balance transaction|
### `PspTransaction` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**Description**|*String*|The description of the transaction|
|**Reference**|*String*|The reference of system that submitted the transaction|
|**CreationDate**|*DateTime*|The date the transaction was created|
|**MerchantReference**|*String*|The merchant reference of the transaction|
|**PaymentMethod**|*Object*|The payment method of the balance transaction|
### `CostCenter` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**Code**|*String*|The code(equivalent to external id) of the cost center|
|**Name**|*String*|The name of the cost center|
|**BillingAddress**|*Object*|The [`BillingAddress`](#refBillingAddress) object holding information about the billing address|
### `BillingAddress` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**Name**|*String*|The name of the billing address|
|**AddressLine1**|*String*|The first address line of the billing address|
|**AddressLine2**|*String*|The second address line of the billing address|
|**PostalCode**|*String*|The postal code of the billing address|
|**City**|*String*|The city of the billing address|
|**Country**|*String*|The country of the billing address|
### `Product` (object)
|Property|Data type|Description|
|:---:|:---:|:---|
|**PositionId**|*Integer*|The position of the item|
|**Id**|*Integer*|The database id|
|**GTIN**|*String*|The GTIN|
|**PLU**|*String*|The PLU|
|**Name**|*String*|The name of the (product/component)|
|**InternalName**|*String*|The name of the (product/component)|
|**Quantity**|*Integer*|The billable quantity|
|**Price**|*Integer*|The price of the (product/component)|
|**Total**|*Integer*|The total of the (product/component)|
|**Rewards**|*Integer*|The [`Rewards`](#refRewards) object holding information about the rewards *1|
|**Tax**|*Integer*|The [`Tax`](#refTax) object holding information about the tax *1|
|**Components**|*Array[Object]*|An array of [`Product`](#refProduct) objects holding the information of the component. Only products have components|
+ Parameters
+ storeId (required, string, `HAN-WDNDM838`)...the store id
+ from (required, datetime, `2024-01-13`)...from date format yyyy-MM-dd
+ till (required, datetime, `2024-01-14`)...till date format yyyy-MM-dd
+ cardId (optional, int, `10168`)...filter transactions for this menu card
+ take (optional, int, `100`)...how many orders you want to request
+ skip (optional, int, `200`)...how many orders you want to skip
+ orderBy (optional, string, `OrderedForDate`)...the property the orders should be filtered by
+ sort (optional, string, `asc`)...the order the orders are sorted in
+ Request
+ Headers
Authorization : Basic Authorization of a dashboard user (see introduction for more information)
+ Response 200
+ Body
{
"TotalTransactionCount": 1234,
"Transactions": [
{
"Guid": "6c6acc68-b752-496b-bd17-0f4071aba808",
"ReceiptNumber": 435120241007108,
"BasketId": "4c70d4df-aab7-4483-b35f-cbd3028d12aa",
"MenuCardId": 10134,
"Channel": "App",
"PaymentState": "Succeeded",
"IsCancelled": false,
"SubmissionDate": "2024-01-30T07:06:52.933Z",
"OrderedForDate": "2024-01-31T00:00:00Z",
"LastUpdatedDate": "2024-01-31T00:00:00.000Z"
"UserDetails": {
"ProfileId": "171b267d-4590-4499-afdd-19a02f1dd45d",
"FullName": "John Doe",
"PhoneNumber": "012345678901",
"Email": "john.doe@email.com",
"IsRegistered": true,
"IsSsoRegistered": false
},
"DeliveryOption": {
"Description": "Collect in Restaurant (for Pickup)",
"Name": "Pick-up"
},
"DeliveryLocation": {
"Name": "Station A",
"InternalName": "Soup station"
},
"CurrencyCode": "EUR",
"Total": 201,
"SubTotal": 187,
"AdditionalCosts": [
{
"InternalName": "compulsory gratuity",
"CurrencyCode": "EUR",
"Amount": "1"
}
],
"Rewards": {
"Amount": 1,
"Details": [
{
"Amount": 1,
"Details": [
{
"Id": 123,
"Name": "Coupon",
"Value": 1
}
]
}
]
},
"Tax": {
"Amount": 13,
"Details": [
{
"Id": 12,
"Rate": 7.0,
"Name": "VAT_7.0",
"Amount": 13
}
]
},
"PaymentDetails": {
"PaymentOption": {
"Name": "Invoice",
"ProviderInfoName": "Free text"
},
"BalanceTransaction": {
"Description": "payment with reservation",
"Reference": "888812a34ea37bf35e4f",
"CreationDate": "2024-01-31T00:00:00Z",
"MerchantReference": "afc9466577174e818a79a3702d913f1b",
"State": "Succeeded"
},
"PspTransactions": [
{
"Description": "updated based on payment status",
"Reference": "c67841e1d66a47cc9a84699022b934a4",
"CreationDate": "2024-07-31T09:48:03.6246933+00:00",
"MerchantReference": "ed2d50381be147c993827d92946d5241",
"PaymentMethod": "voucher"
}
],
"CostCenter": {
"Code": "H38UJ",
"Name": "Conference Room",
"BillingAddress": {
"Name": "Conference Room A"
"AddressLine1": "Doyle Shoals",
"AddressLine2": "Suite 908",
"PostalCode": "26483",
"City": "Millerchester",
"Country": "Ireland"
}
}
},
"Products": [
{
"PositionId": 0,
"Id": 1234567890,
"GTIN": "00346730941986",
"PLU": "QNP-1234567890",
"Name": "Croissant au chocolat",
"InternalName": "Croissant",
"Quantity": 1,
"Price": 140,
"Total": 150,
"Rewards": {
"Amount": 1,
"Details": [
{
"Id": 123,
"Name": "Coupon",
"Value": 1
}
]
},
"Tax": {
"Amount": 13,
"Details": {
"Id": 12,
"Rate": 7.0,
"Name": "VAT_ToGo_7.0",
"Amount": 13
}
},
"Components": [
{
"PositionId": 0,
"Id": 1234567890,
"GTIN": "00346730941986",
"PLU": "QNP-0987654321",
"Name": "Bread",
"InternalName": "Bread",
"Quantity": 1,
"Price": 140,
"Total": 150,
"Rewards": {
"Amount": 1,
"Details": [
{
"Id": 123,
"Name": "Coupon",
"Value": 1
}
]
},
"Tax": {
"Amount": 13,
"Details": {
"Id": 12,
"Rate": 7.0,
"Name": "VAT_ToGo_7.0",
"Amount": 13
}
}
}
]
}
],
}
]
}