DataKey V3 Data API
2TouchPOS DataKey Data API V3
2013 Xenios LLC 82 Saint Paul Street Rochester, NY 14604 Phone 585.325.5242 • Fax 585.325.6989
Table of Contents About this Document .................................................................................................................................... 3 What is DataKey? .......................................................................................................................................... 4 API Details ..................................................................................................................................................... 5 Service Endpoint ....................................................................................................................................... 5 Method Credentials .............................................................................................................................. 5 Method Results ..................................................................................................................................... 5 Example Use .............................................................................................................................................. 6 Data Identification .................................................................................................................................... 7 Enterprise Reference Numbers (ERNs) ................................................................................................. 7 Local Reference Identifier (LRIs) ........................................................................................................... 7 Local Reference Number (LRNs) ........................................................................................................... 7 Ticket Methods ......................................................................................................................................... 8 GetMetaData ........................................................................................................................................ 8 Get Menu Item Usage ........................................................................................................................... 8 Get Modifier Usage............................................................................................................................... 9 Get Ticket Details ................................................................................................................................ 10 Time Clock Methods ............................................................................................................................... 22 GetAdjustedTimeClockData ................................................................................................................ 22 GetRawTimeClockData ....................................................................................................................... 23
2
About this Document This document was written for 2TouchPOS version 3.03.5600 and version 3 of the DataKey API.
3
What is DataKey? DataKey is a web service enabling you to retrieve your 2TouchPOS historical data.
2TouchPOS
Cloud Storage
Your Application
Version 1 provides ticket detail data and inventory summary data. A ticket is comprised of menu items, modifiers, payments, gift card increases and gift certificate increases. Inventory summary data reports the total number of menu items and modifiers sold and their quantity used. Version 3 adds card holder name for credit card payments and auto-generated identifiers.
4
API Details Service Endpoint The DataKey Browser download service is available at: http://DataKey.2TPos.com/2TouchPOS/DataKey/V3/DownloadService/DownloadService.svc
Method Credentials All service methods take your Application Id, the Site Id and Auth Code as credentials. Requests with an invalid Application Id, Site Id, or Auth Code combination will be rejected. The result will indicate the failure in the status and the status reason will be ‘Invalid application id/ site Id / authorization code’.
Method Results All service methods return results of the request. Check the result Status to ensure the operation succeeded. If the operation failed, the reason will be in the result’s Reason field.
5
Example Use Here is a C#.Net example of calling the DownloadService and retrieving MetaData. Visual Studio created a wrapper library for the web service. Line 8 shows creating a DownloadServiceClient. Line 9 shows calling the GetMetaDataAsync method which asynchronously retrieves the ResultOfTicketMetadata results. Line 11 shows checking the result Status before continuing Lines 12-17 show doing something with the result Data if the operation was a success Line 21 shows doing something with the error message when the operation failed.
1 public async Task RefreshData_Executed() 2 { 3 Executing = true; 4 ErrorMessage = string.Empty; 5 6 try 7 { 8 DownloadServiceClient client = new DownloadServiceClient(); 9 ResultOfTicketMetadata result = await client.GetMetaDataAsync(appId, CredentialsVM.SiteId, CredentialsVM.AuthCode); 10 11 if (result.Status == Status.Success) 12 { 13 TicketMetadata ticketMetaData = result.Data; 14 15 16 17 18 19
20 21 22 23 24 25 26 27 21 22 23 }
this.EarliestBusinessDate = ticketMetaData.EarliestBusinessDate; this.LatestBusinessDate = ticketMetaData.LatestBusinessDate; this.EarliestClosedOnDate = ticketMetaData.EarliestClosedOnDate; this.LatestClosedOnDate = ticketMetaData.LatestClosedOnDate; } else
{ ErrorMessage = result.Reason; } } catch (Exception ex) { ErrorMessage = ex.Message; } Executing = false;
6
Data Identification We now offer three ways for you and your integration partners to align data from multiple locations. Enterprise Reference Numbers allow you to identify data in 2Touch. Local Reference Identifiers and Local Reference Numbers allow you to identify data in the receiving software. ERNs LRNs and LRIs
Pros
You control the values Automatically supplied. Mapping is centralized
Cons
You have to maintain the values at each location. You have to match the data in every 3rd party application.
Enterprise Reference Numbers (ERNs) Enterprise reference numbers are identifiers you control and enter into 2Touch to identify departments, categories, menu items, pricing levels, modifier groups, unique modifiers, modifier options, course, employees, job descriptions, stations, station types, payment types, discounts, and coupons. Since you control ERNs, you can make them the same at every location.
Local Reference Identifier (LRIs) Local Reference Identifiers are globally unique values automatically generated and supplied by 2Touch. Third party software can use these values to identify equivalent data. LRIs were introduced in the DataKey V3. Data collected in previous versions will not have an LRI. Data collected in V3 or after will have LRIs.
Local Reference Number (LRNs) Local Reference Numbers are locally unique and supplied by 2Touch. The numbers generated are unique within each location and relative to each data type. For example, no two menu items at a location will have the same LRN. The numbers are not unique between data types. A menu item and a modifier might have the same LRN. The numbers are not unique between locations. Two different menu items from two locations might have the same LRN. In order to properly identify the data, you must use the LRN, the data type, and the location. LRNs were introduced in the DataKey V3. Data collected in previous versions will not have an LRN. Data collected in V3 or after will have LRNs.
7
Ticket Methods GetMetaData GetMetaData returns summary information about your data. Specifically, it returns the earliest business date, latest business date, earliest ticket closed on date, and latest ticket closed on date. This method should be used to ensure data is available before calling other methods. Parameters Name applicationId siteId authCode
Type Guid Guid Guid
Returns ResultOfTicketMetaData: Name Status Reason Location Data
Type Enum String String Ticket Meta Data
Notes Success = 0, Failure = 1 The reason for a failure The Site Id
TicketMetaData: Name Earliest Business Date Earliest Closed On Date Latest Business Date Latest Closed On Date
Type Notes Date Time Date only Date Time Date Time Date only Date Time
Get Menu Item Usage Get Menu Item Usage returns summary data about the menu items used during the provided time period. Parameters Name Type applicationId Guid siteId Guid authCode Guid From Date Date Time To Date Date Time From Date and to Date are filters on ticket business dates. They are inclusive. Returns ResultOfMenuItemUsageSummary: Name Status Reason
Type Enum String
Notes Success = 0, Failure = 1 The reason for a failure 8
Location String The SiteId Data Menu Item Usage Summary Menu Item Usage Summary: Name Details Net Sales Tax Total
Type Menu Item Usage[] Decimal Decimal Decimal
Menu Item Usage: Name ERN LRI LRN Inventory Usage Name Quantity Sales Amount
Data Type string Unique Identifier Int double string double Decimal
Max Length 36 36
Nullable Y Y Y N N N N
Get Modifier Usage Get Modifier Usage returns summary data about the modifiers used during the provided time period. Parameters Name Type siteId Guid applicationId Guid authCode Guid From Date Date Time To Date Date Time From Date and to Date are filters on ticket business dates. They are inclusive. Returns Result Of Array Of Modifier Group Usage Summary: Name Status Reason Location Data
Type Enum String String Modifier Group Usage Summary[]
Notes Success = 0, Failure = 1 The reason for a failure The SiteId
Modifier Group Usage Summary: Name
Data Type
Max Length Nullable
9
ERN LRI LRN Modifiers Name Quantity
string 36 Unique Identifier 36 Int Modifier Usage[] string double
Y Y Y N N N
Modifier Usage: Name ERN LRI LRN Inventory Usage Name Price Level Price Level ERN Price Level LRI Price Level LRN Quantity
Type string Unique Identifer Int double string String String Unique Identifier Int double
Max Length 36 36
Nullable Y Y
36 36
Y N N N Y Y Y N
Get Ticket Details GetTicketDetails returns complete data about tickets. Parameters Name applicationId siteId authCode Business Date
Type Guid Guid Guid Date Time
Returns Result Of Array Of Ticket DTO: Name Status Reason Location Data
Data type Enum String String Ticket DTO[]
Description Success = 0, Failure = 1 The reason for a failure The Site Id
Ticket DTO: A Ticket Header contains summary data for a ticket as well as Menu Items, Payments, Gift Card Increases, and Gift Certificate Increases. Field Datatype Max Nullable Description Length Id Unique N Unique Id of this record Identifier Amount Due Decimal Y The total amount due from the customer
10
Annual ZCount
Int
APIVersion Float Auto Tab String Employee Id Auto Tab String Employee ERN Auto Tab Unique Employee LRI identifier Auto Tab Int Employee LRN Auto Gratuity Decimal House Amount Auto Gratuity Decimal Total Amount
N
25
N Y
36
Y
36
Y Y
The number of Z's since the beginning of the year. The format is YYYYdddd where YYYY is the year and dddd is the number of Zs processed this year. The DataKey version used to upload the ticket. The Id of the employee that owns the ticket when this is an AutoTab ticket The ERN of the employee that owns the ticket when this is an AutoTab ticket The LRI of the employee that owns the ticket when this is an AutoTab ticket The LRN of the employee that owns the ticket when this is an AutoTab ticket
Y
The amount of the Auto Gratuity tip kept by the establishment.
Y
25
N
Employee String 36 ERN Employee LRI Unique 36 identifier Employee Int LRN Future Float Payment Gift Card Gift Card Increases Increas DTO[] Gift Gift Certificate Certificate Increases Increas DTO[] Guest Count Int
Y
The amount of tip from the check as determined by the Auto Gratuity Percent and the Sub-Total, Total, Discounted SubTotal or Discounted Total depending on the system settings. The business date of this ticket. The Date and Time the ticket was closed. The total cost of menu items and modifiers The Date and Time the ticket was created. Note that due to split checks and item transfers, the ticket header could be created after a line item. The employeeId of the employee that owns the ticket. This could be the employee that opened the ticket or closed the ticket based on your settings. The owner could have been transferred to another employee. The ERN of the employee that owns the ticket.
Y
The LRI of the employee that owns the ticket.
Y
The LRN of the employee that owns the ticket.
Y
The Payment amount taken on an a Future Order prior to completing the order.
Gross Sale Amount
Y
Business Date Closed On Cost Created On
Date Date Time Float Date Time
Employee Id String
Decimal
N N Y N
Y
Y
Y
The number of people on a ticket when usinig table management. Guest count is not necessarily required are can be null. The total gross sale amount
11
Menu Items
Menu Item DTO[] Decimal
Net Sale Amount Order Origin String
Payments
Y
3
Payment DTO[] Decimal
Promo Amount Station Name String
Y
The total of the ticket line items without taxes.
Y
Where the order started. A value of NULL means the order was started at a POS Station. A value of 'W' means the order started from 2TouchPOS' Online Ordering module.
Y Y
The total of the promo amounts
25
N
Station ERN String Station LRI Unique Idenfifier Station LRN Int Tab Name String
36 36
Y Y
The name of the station where the ticket was closed. When the ticket was completed by a driver drop, StationName is the delivery station's name. The ERN of the station where the ticket was closed. The LRI of the station where the ticket was closed.
25
Y Y
Table Name
25
Y
36 36
Y Y Y
The LRN of the station where the ticket was closed. The name given to the tab. A null value indicates a transaction that wasn't placed on a table or tab and 2TouchPOS is set to not require names. The name of the tab is provided when the ticket is associated with a table. The name of the table for this ticket. The value will be null when not affiliated with a table. The amount of Tax from Tax 1 The ERN of Tax 1 The LRN of Tax 1
Y Y Y Y Y
The LRI of Tax 1 The name of Tax 1 The amount of Tax from Tax 2 The ERN of Tax 2 The LRN of Tax 2
36 36
Y Y Y Y Y
The LRI of Tax 2 The name of Tax 2 The amount of Tax from Tax 3 The ERN of Tax 3 The LRN of Tax 3
25 20
Y Y N
12
N
The LRI of Tax 3 The name of Tax 3 A 2TouchPOS generated identifier for the ticket. The format is YYYYMMDDhhmmTTTXXXXX where YYYY is the year, MM is the month, DD is the day, hh is the hour in 24-hour format, mm is the minute, TTT is the terminal number, XXXX is the sequential ticket number for that day. Indicates the type of transaction. The valid values are Transaction, Comp, Spill.
String
Tax1Amount Decimal Tax1ERN String Tax1 LRI Unique Identifier Tax1 LRI Int Tax1Name String Tax2Amount Decimal Tax2ERN String Tax2 LRI Unique Identifier Tax2 LRI Int Tax2Name String Tax3Amount Decimal Tax3ERN String Tax3 LRI Unique Identifier Tax3 LRI Int Tax3Name String Ticket String Number
Ticket Type
String
25 36 36
25
12
Menu Item DTO: Column Id Ticket Id Amount Due
Data type Max Length Unique Identifier Unique Identifier Decimal
Nullable Description N
Primary Key
N
Foreign Key to the Ticket
Y
20 36 36
Y Y Y Y
NetSaleAmount plus taxes. This is the amount the customer pays. Z report identifier. The number of Z's since the beginning of the year. The format is YYYYdddd where YYYY is the year and dddd is the number of Zs processed this year. The amount deducted from an automatically applied coupon The business date of this ticket item. Indicates that the item had a surcharge applied to it because it was not paid for in cash. The cost of the item as entered into 2TouchPOS. The name of the course this item was served in. The ERN of the course this item was served in. The LRN of the course this item was served in.
25
Y N N
The LRI of the course this item was served in. The date and time this item was rung onto the ticket. The name of the department the item is in.
36
Y
The ERN of the department the item is in.
36
Y
The LRI of the department the item is in.
Y
The LRN of the department the item is in.
Y
The amount the item was discounted by
36 50
Y Y
36
Y
36
Y
Annual ZCount Int
Y
Auto Coupon Amount Business Date Cash Discount Surcharge Cost Course Name Course ERN Course LRI
Decimal
Y
Date Time Bit
Y Y
Float String String Unique Identifier Int Date Time String
Course LRN Created On Department Name Department String ERN Department LRI Unique Identifier Department Int LRN Discount Decimal Amount Discount ERN String Discount String Employee Id Discount String Employee ERN Discount Unique Employee LRI Identifier Discount Int Employee LRN Discount LRI Unique Identifier Discount LRN Int Discount Name String Employee Id String Employee ERN String
36
Y
The ERN of the discount applied to this item. The name of the employee receiving the employee discount applied to the item. The ERN of the employee receiving the employee discount applied to the item. The LRI of the employee receiving the employee discount applied to the item. The LRN of the employee receiving the employee discount applied to the item. The LRI of the discount applied to this item.
25 25 36
Y Y N Y
The LRN of the discount applied to this item. The name of the discount applied to this item. The employee Id of the employee that rang in this item. The ERN of the employee that rang in this item.
Y
13
Employee LRI Unique Identifier Employee LRN Int ERN String Gross Sale Decimal Amount Inventory Usage Float LRI Unique Identifier LRN Int Name String Net Sale Decimal Amount Order Type String Order Type String ERN Order Type LRI Unique Identifier Order Type Int LRN Original Ticket String Number PLU String Price Level String ERN Price Level LRI Unique Identifier Price Level Int LRN Price Level String Name Promo Amount Decimal Quantity Sold Float Refund Flag Bit Reward Points Float Earned Reward Points Float Redeem Reward Card String Number Reporting String Category ERN Reporting Unique Category LRI Identifier Reporting Int Category LRN Reporting String Category Name Seat Number Int
36
Y
The LRI of the employee that rang in this item.
36
Y Y Y Y Y
The LRN of the employee that rang in this item. The ERN of the item. The Price per item * quantity. This before discounts and taxes. The quantity * the inventory factor The LRI of the item
50
Y N Y
The LRN of the item The name of the item. Gross Sale Amount after discounts but before taxes.
15 36
Y Y
The name of the order type. The ERN of the order type.
36
Y
The LRI of the order type
Y
The LRN of the order type
20
Y
The ticket number this menu item was original rung on.
14 36
Y Y
The price look up of the item. The ERN of the price level the menu item was sold at.
36
Y
The LRI of the price level the menu item was sold at.
Y
The LRN of the price level the menu item was sold at.
Y
The name of the price level the menu item was sold at.
Y Y N Y
Promotional Amount Redeemed to purchase this item. The quantity of the item sold. Indicates if this line item represents a return. The number of rewards points earned
Y
36
25
9
Y
36
Y
The number of rewards points redeemed to purchase this item. The Reward Card Number points were added to or subtracted from. The ERN of the category this item is reported in.
36
Y
The LRI of the category this item is reported in.
Y
The LRN of the category this item is reported in.
N
The name of the category this item is reported in.
Y
The seat number ordering the item.
25
14
Sort Order
Int
Station Name Station ERN Station LRI
String String Unique Identifier Station LRN Int Tax1Amount Decimal Tax1Name String Tax1ERN String Tax1 LRI Unique Identifier Tax1 LRN Int Tax2Amount Decimal Tax2Name String Tax2ERN String Tax2 LRI Unique Identifier Tax2 LRN Int Tax3Amount Decimal Tax3Name String Tax3ERN String Tax3 LRI Unique Identifier Tax3 LRN Int Taxable Amount Decimal
N 25 36 36
N Y Y
The sort order of the menu items and modifiers entered on the ticket. The name of the station where the item was rung. The ERN of the station where the item was rung. The LRI of the station where the item was rung.
25 36 36
Y Y Y Y Y
The LRN of the station where the item was rung. The amount of Tax from Tax 1 The name of Tax 1 The ERN of Tax 1 The LRI of Tax 1
25 36 36
Y Y Y Y Y
The LRN of Tax 1 The amount of Tax from Tax 2 The name of Tax 2 The ERN of Tax 2 The LRI of Tax 2
25 36 36
Y Y Y Y Y
The LRN of Tax 2 The amount of Tax from Tax 3 The name of Tax 3 The ERN of Tax 3 The LRI of Tax 3
Y Y
The LRN of Tax 3 The value that taxes were calculated on.
ModifiersDTO: Column
Data type
Max Length
Id
Nullable Description
Unique Identifier Menu Item Id Unique Identifier Parent Modifier Id Unique Identifier Amount Due Decimal
N
Primary Key
N
Foreign Key to the Menu Item
Y
Auto Coupon Amount Cash Discount Surcharge Cost
Decimal
Y
Bit
Y
Float
Y
Course Name Course ERN Course LRI
String String Unique Identifier Int
Y Y Y
The modifier that this modifier modified. If NULL, this modifier modifies the Menu Item directly. Net Sale Amount plus taxes. This is the amount the customer pays. The amount deducted from an automatically applied coupon. Indicates that the item had a surcharge applied to it because it was not paid for in cash. The cost of this modifier. Cost is defined as the per unit cost *quantity * inventory factors. The name of the course this item was served in. The ERN of the course this item was served in. The LRI of the course this item was served in.
Y
The LRN of the course this item was served in.
Course LRN
Y
20 36 36
15
Created On Discount Amount Discount ERN Discount LRI Discount LRN Discount Employee Id Discount Employee ERN Discount Employee LRI Discount Employee LRN Discount Name Employee Id Employee ERN Employee LRI Employee LRN Gross Sale Amount Inventory Usage Modifier Group Modifier Group ERN Modifier Group LRI Modifier Group LRN Modifier Option Modifier Option ERN Modifier Option LRI Modifier Option LRN Modifiers
Date Time Decimal String Unique Identifier Int String
36 36
N Y Y Y
The date and time this item was rung onto the ticket. The amount the item was discounted by The ERN of the discount applied to this item. The LRI of the discount applied to this item.
50
Y Y
String
36
Y
Unique Identifier Int
36
Y
String String
25 25
Y N
String Unique Identifier Int Decimal
36 36
Y Y
The LRN of the discount applied to this item. The name of the employee receiving the employee discount applied to the item. The ERN of the employee receiving the employee discount applied to the item. The LRI of the employee receiving the employee discount applied to the item. The LRN of the employee receiving the employee discount applied to the item. The name of the discount applied to this modifier. The employee Id of the employee that rang in this item. The ERN of the employee that rang in this item. The LRI of the employee that rang in this item.
Y
25 36
N Y Y
The LRN of the employee that rang in this item. The Price per item * quantity. This before discounts and taxes. The quantity * the inventory factor The Name of the modifier group the modifier is in. The ERN of the modifier group the modifier is in
Unique Identifier Int
36
Y
The LRI of the modifier group the modifier is in
Y
The LRN of the modifier group the modifier is in
String String
50 36
Y Y
The Name of the modifier option. The ERN of the modifier option.
Unique Identifier Int
36
Y
The LRI of the modifier option.
Y
The LRN of the modifier option.
Float String String
Y Y
Modifier DTO[] Net Sale Amount Decimal
Y Y
Original Ticket String Number PLU String Price Level Name String
20
Y
14 25
Y Y
Price Level ERN
36
Y
String
The Gross Sale Amount less discounts but before taxes The ticket number this menu item was original rung on. The price look up of the item. The name of the price level the menu item was sold at. The ERN of the price level the menu item was sold at.
16
Price Level LRI Price Level LRN Promo Amount Quantity Sold Refund Flag Reward Points Earned Reward Points Redeem Reporting Category Name Reporting Category ERN Reporting Category LRI Reporting Category LRN Segment Name Segment ERN Segment LRI Segment LRN Sort Order Station Name Station ERN Station LRI Station LRN Tax1Amount Tax1Name Tax1ERN Tax1 LRI Tax1 LRN Tax2Amount Tax2Name Tax2ERN Tax2 LRI Tax2 LRN Tax3Amount Tax3Name Tax3ERN Tax3 LRI Tax3 LRN
Unique Identifier Int
36
Y
The LRI of the price level the menu item was sold at.
Y
String
25
N
The LRN of the price level the menu item was sold at. Promotional amount redeemed to purchase this item. The quantity of the item sold. True if this modifier is being refunded. The number of reward points earned in purchasing this modifier. The number of rewards points used to purchase this modifier. The name of the reporting category for this modifier.
String
36
Y
The ERN of the reporting category for this modifier.
Unique Identifier Int
36
Y
The LRI of the reporting category for this modifier.
Y
The LRN of the reporting category for this modifier.
String String Unique Identifier Int Int
30 36 36
Y Y Y
Then name of the segment this item is divided into. Then ERN of the segment this item is divided into. Then LRI of the segment this item is divided into.
4
Y N
String String Unique Identifier Int Decimal String String Unique Identifier Int Decimal String String Unique Identifier Int Decimal String String Unique Identifier Int
25 36 36
N Y Y
Then LRN of the segment this item is divided into. The sort order of the menu items and modifiers entered on the ticket. The name of the station where the item was rung. The ERN of the station where the item was rung. The LRI of the station where the item was rung.
25 36 36
Y Y Y Y Y
The LRN of the station where the item was rung. The amount of Tax from Tax 1 The name of Tax 1 The ERN of Tax 1 The LRI of Tax 1
25 36 36
Y Y Y Y Y
The LRN of Tax 1 The amount of Tax from Tax 2 The name of Tax 2 The ERN of Tax 2 The LRI of Tax 2
25 36 36
Y Y Y Y Y
The LRN of Tax 2 The amount of Tax from Tax 3 The name of Tax 3 The ERN of Tax 3 The LRI of Tax 3
Y
The LRN of Tax 3
Decimal Float Bit Float
Y Y N Y
Float
Y
17
Taxable Amount Unique Modifier Name Unique Modifier ERN Unique Modifier LRI Unique Modifier LRN
Decimal String
25
Y N
The value that taxes were calculated on. The unique name of this modifier
String
36
Y
The ERN of the unique modifier
Unique Identifier Int
36
Y
The LRI of the unique modifier
Y
The LRN of the unique modifier
Gift Card Increase DTO: Column
Data type Max Length Id Unique Identifier Ticket Id Unique Identifier Amount Due Decimal
Nullable Description
Annual Z Count
Y
N
Primary Key
N
Y N Y
The ID of the ticket this Gift Card Increase is associated with Net Sale Amount plus taxes. This is the amount the customer pays. Z report identifier. The number of Z's since the beginning of the year. The format is YYYYdddd where YYYY is the year and dddd is the number of Zs processed this year. The business date of this ticket item. The date and time this item was rung onto the ticket. The amount the item was discounted by
36
Y
The ERN of the discount applied to this item.
36
Y
The LRI of the discount applied to this item.
Y
The LRN of the discount applied to this item.
25
Y
The name of the discount applied to this item.
25 36
N Y
The employee Id of the employee that rang in this item. The ERN of the employee that rang in this item.
36
Y
The LRI of the employee that rang in this item.
Y
The LRN of the employee that rang in this item.
Y
The amount the gift card was increased by
15 36
N Y
The name of the order type. The ERN of the order type.
36
Y
The LRI of the order type.
Y
The LRN of the order type.
Int
Business Date Date Created On Date Time Discount Decimal Amount Discount String ERN Discount LRI Unique Identifier Discount Int LRN Discount String Name Employee Id String Employee String ERN Employee Unique LRI Identifier Employee Int LRN Gift Increase Decimal Amount Order Type String Order Type String ERN Order Type Unique LRI Identifier Order Type Int
N
18
LRN Original String Ticket Number Quantity Sold Float Reward Float Points Earned Reward Float Points Redeem Reward Card String Number Seat Number Int Sort Order Int Station ERN String Station LRI Unique Identifier Station LRN Int Station Name String
20
9
Y
The ticket number this menu item was original rung on.
Y Y
The quantity of the item sold. The number of rewards points earned
Y
The number of rewards points used to purchase this modifier.
Y
36 36
Y Y
The Reward Card Number points were added to or subtracted from. The seat number ordering the item. The sort order of the menu items and modifiers entered on the ticket. The ERN of the station where the item was rung. The LRI of the station where the item was rung.
25
Y N
The LRN of the station where the item was rung. The name of the station where the item was rung.
Y N
Gift Certificate Increases: Column
Data type Max Length Id Unique Identifier Ticket Id Unique Identifier Amount Due Decimal
Nullable Description
Annual Z Count
Y
N
Primary Key
N
Y N Y
The ID of the ticket this Gift Certificate Increase is associated with Net Sale Amount plus taxes. This is the amount the customer pays. Z report identifier. The number of Z's since the beginning of the year. The format is YYYYdddd where YYYY is the year and dddd is the number of Zs processed this year. The business date of this ticket item. The date and time this item was rung onto the ticket. The amount the item was discounted by
36
Y
The ERN of the discount applied to this item.
36
Y
The LRI of the discount applied to this item.
Y
The LRN of the discount applied to this item.
25
Y
The name of the discount applied to this item.
25 36
N Y
The employee Id of the employee that rang in this item. The ERN of the employee that rang in this item.
36
Y
The LRI of the employee that rang in this item.
Int
Business Date Date Created On Date Time Discount Decimal Amount Discount String ERN Discount LRI Unique Identifier Discount Int LRN Discount String Name Employee Id String Employee String ERN Employee Unique LRI Identifier
N
19
Employee Int LRN Gift Increase Decimal Amount Order Type String Order Type String ERN Order Type Unique LRI Identifier Order Type Int LRN Original String Ticket Number Quantity Sold Float Reward Float Points Earned Reward Float Points Redeem Reward Card String Number Seat Number Int Sort Order Int Station ERN String Station LRI Unique Identifier Station LRN Int Station Name String
Y
The LRN of the employee that rang in this item.
Y
The amount the gift certificate was increased by
15 36
N Y
The name of the order type. The ERN of the order type.
36
Y
The LRI of the order type.
Y
The LRN of the order type.
Y
The ticket number this menu item was original rung on.
Y Y
The quantity of the item sold. The number of rewards points earned
Y
The number of rewards points used to purchase this modifier.
Y
20
9
36 36
Y Y
The Reward Card Number points were added to or subtracted from. The seat number ordering the item. The sort order of the menu items and modifiers entered on the ticket. The ERN of the station where the item was rung. The LRI of the station where the item was rung.
25
Y N
The LRN of the station where the item was rung. The name of the station where the item was rung.
Y N
Payment DTO: Records a payment where a payment is cash, credit card, or coupon. Rewards and Loyalty purchases are recorded against the menu item. Column Data type Max Nullable Description Length Id Unique N Primary Key Identifier Ticket Id Unique N Foreign Key to the Ticket Identifier Annual Z Count Int Y The number of Z's since the beginning of the year. The format is YYYYdddd where YYYY is the year and dddd is the number of Zs processed this year. Business Date Date Time N The business date of the payment. Card Holder Name String 26 Y The card holder’s name for credit card payments Card Type String 20 Y AMEX, DISCOVER, MASTERCARD, DINERS, VISA Change Given Decimal Y
20
Change Kept Coupon Name Coupon ERN
Decimal String String
Coupon LRI
Y
Coupon LRN
Unique 36 Identifier Int
Coupon Percent
Float
Y
20 36
Y Y Y
Y
Coupon Type String CreditCardNumberLast4Digits String Employee Name String
50 4 25
Y Y N
Employee ERN
String
36
Y
Employee LRI
Y
Employee LRN
Unique 36 Identifier Int
Foreign Amount Incentive Card Number
Decimal String
Y Y
Payment Taken On Payment Type Payment Name Payment ERN Payment LRI
N N N Y Y
Payment LRN Station Name
Date Time Int String 50 String 36 Unique 36 Identifier Int String 25
Station ERN
String
36
Y
Station LRI
Y
Station LRN
Unique 36 Identifier Int
Tip Amount
Decimal
Y
Tip House Amount Total Amount
Decimal Decimal
Y Y
9
Y
Y N
Y
Name of the coupon The ERN of the coupon used in this transaction The LRI of the coupon used in this transaction The LRN of the coupon used in this transaction The percent reduction in cost due to the coupon The type of coupon used Last 4 digits of the credit card The employee Id of the employee that rang in this item. The ERN of the employee that rang in this item. The LRI of the employee that rang in this item. The LRN of the employee that rang in this item. The amount paid in foreign currency The card number used to make a loyalty/reward card payment Date and time that the payment was taken Type of payment Name of the payment type The ERN of the payment type The LRI of the payment type The LRN of the payment type The name of the station where the payment was taken. The ERN of the station where the payment was taken. The LRI of the station where the payment was taken. The LRN of the station where the payment was taken. The amount of tip including the amount the house keeps from the tip. Amount the house keeps from the tip. The total amount paid including the tip amount
21
Time Clock Methods Time clock data is not locked after any amount of time. That is, an adjustment to a time clock entry can be made at any time in the future. Therefore, who clocked in when and how long they worked could change at any time. Note that a clock out is required before the data for the individual interaction to be uploaded.
GetAdjustedTimeClockData GetAdjustedTimeClockData returns adjusted time clock entries whose clock out time is after the from date and before the to date at the time of the request. Parameters Name applicationId siteId authCode fromDate toDate
Type Notes Guid Guid Guid DateTime This is filtering on the Clock Out time. DateTime This is filtering on the Clock Out time.
Returns ResultOfArrayOfTimeClockState: Name Status Reason RequestedOn Location Data
Type Enum String DateTime String TimeClockState[]
Notes Success = 0, Failure = 1 The reason for a failure The date and time of the request The Site Id An array of the TimeClockData
TimeClockState: Name
Data Type
Max Length
AutoGratuityTips
Decimal
N
ClockInTime ClockOutTime CreditCardTips
Date Time Date Time Decimal
N N N
CustomerAccountTips Decimal DeclaredCashTips Employee ERN Employee LRI Employee LRN EmployeeFirstName EmployeeLastName Id
Decimal String Unique Identifier Int String String Guid
Nullable Notes
N Y Y
The amount of tips collected via Auto Gratuity The date and time of the clock in The date and time of the clock out The amount of tips from credit card transactions The amount of tips from payments to customer accounts The amount of cash tips declared The ERN of the employee. The LRI of the employee.
Y N N N
The LRN of the employee. The employee’s first name. The employee’s last name. Unique Id for this record
N
36 36
25 25
22
JobType ERN JobType LRI JobType LRN JobTypeName PayRate Sales
String Unique Identifier Int String Decimal Decimal
36 36
25
Y Y
The ERN assigned to the job type. The LRI assigned to the job type.
Y N N N
The LRN assigned to the job type. The name of the job type The payrate for this clock in/out The amount of sales generated for this clock in/out
GetRawTimeClockData GetRawTimeClockData returns the raw data for time clock interactions. The way the DataKey captures time clock data is through a sequence of TimeClockStates. The first state is normally created when the user clocks in. This state is also used to capture the clock out time so long as no adjustments are made. Each new state represents the best data at that moment. What Triggers and Adjustment?
Adjusting any of the following creates an adjustment record.
Clock in time Clock out time Job type Pay Rate Cash Tips Credit card Tips Account tips Auto Gratuity tips Sales total
Creating a clock in entry creates an adjustment record. Deleting a clock entry also creates an adjustment record. How is the Data Related
In every scenario, a TimeClockEntry is created. The TimeClockEntry ties all of the details together. In the majority of cases, you will have a TimeClockEntry and an associated TimeClockState. If adjustments have been performed, they will be related to the TimeClockEntry and point to new TimeClockStates. TimeClockAdjustments are ordered. When processing adjustments, it is important to process them in order.
23
Special Cases
If the user clocks in, then the TimeClockEntry will have a TimeClockState. If the manager clocks in an employee then the TimeClockEntry’s TimeClockState will be null. The manager clock in will be captured as an adjustment. The adjustments state represents the clock in. If the TimeClockEntry is deleted, the last TimeClockAdjustment’s TimeClockState will be null. Parameters Name applicationId siteId authCode fromDate toDate
Type Guid Guid Guid DateTime DateTime
Returns ResultOfRawTimeClockData: Name
Type
Notes
24
Status Reason RequestedOn Location Data
Enum String DateTime String RawTimeClockData
Success = 0, Failure = 1 The reason for a failure The date and time of the request The Site Id An array of the TimeClockData
RawTimeClockData: Name Type Notes Adjustments TimeClockAdjustment[] The array of adjustments Entries TimeClockEntry[] The array of time clock entries TimeClockAdjustment: Name
Data Type
Max Length
Nullable Notes
Adjustment Ordering Adjustment Time Adjustor ERN
Int
N
DateTime String
36
N Y
Adjustor LRI
36
Y
Adjustor LRN
Unique Identifier Int
AdjustorFirstName
String
25
N
AdjustorLastName
String
25
N
Id TimeClockEntryId
Guid Guid
N N
TimeClockState
TimeClockState
Y
Y
An integer indicating the order in which this adjustment occurred The date and time the adjustment occurred The ERN of the employee that made the adjustment The LRI of the employee that made the adjustment The LRN of the employee that made the adjustment The first name of the employee that made the adjustment The last name of the employee that made the Unique Id for this record The id of the time clock entry being adjusted The resulting state from this adjustment. See TimeClockState in GetAdjustedTimeClockData
TimeClockEntry: Name Id TimeClockState TimeClockStateId
Type Guid TimeClockState Guid
Notes The id of the time clock entry The time clock state created on clock in. The id of the time clock state created on clock in.
25
2013 Xenios LLC 82 Saint Paul Street Rochester, NY 14604 Phone 585.325.5242 • Fax 585.325.6989
Table of Contents About this Document .................................................................................................................................... 3 What is DataKey? .......................................................................................................................................... 4 API Details ..................................................................................................................................................... 5 Service Endpoint ....................................................................................................................................... 5 Method Credentials .............................................................................................................................. 5 Method Results ..................................................................................................................................... 5 Example Use .............................................................................................................................................. 6 Data Identification .................................................................................................................................... 7 Enterprise Reference Numbers (ERNs) ................................................................................................. 7 Local Reference Identifier (LRIs) ........................................................................................................... 7 Local Reference Number (LRNs) ........................................................................................................... 7 Ticket Methods ......................................................................................................................................... 8 GetMetaData ........................................................................................................................................ 8 Get Menu Item Usage ........................................................................................................................... 8 Get Modifier Usage............................................................................................................................... 9 Get Ticket Details ................................................................................................................................ 10 Time Clock Methods ............................................................................................................................... 22 GetAdjustedTimeClockData ................................................................................................................ 22 GetRawTimeClockData ....................................................................................................................... 23
2
About this Document This document was written for 2TouchPOS version 3.03.5600 and version 3 of the DataKey API.
3
What is DataKey? DataKey is a web service enabling you to retrieve your 2TouchPOS historical data.
2TouchPOS
Cloud Storage
Your Application
Version 1 provides ticket detail data and inventory summary data. A ticket is comprised of menu items, modifiers, payments, gift card increases and gift certificate increases. Inventory summary data reports the total number of menu items and modifiers sold and their quantity used. Version 3 adds card holder name for credit card payments and auto-generated identifiers.
4
API Details Service Endpoint The DataKey Browser download service is available at: http://DataKey.2TPos.com/2TouchPOS/DataKey/V3/DownloadService/DownloadService.svc
Method Credentials All service methods take your Application Id, the Site Id and Auth Code as credentials. Requests with an invalid Application Id, Site Id, or Auth Code combination will be rejected. The result will indicate the failure in the status and the status reason will be ‘Invalid application id/ site Id / authorization code’.
Method Results All service methods return results of the request. Check the result Status to ensure the operation succeeded. If the operation failed, the reason will be in the result’s Reason field.
5
Example Use Here is a C#.Net example of calling the DownloadService and retrieving MetaData. Visual Studio created a wrapper library for the web service. Line 8 shows creating a DownloadServiceClient. Line 9 shows calling the GetMetaDataAsync method which asynchronously retrieves the ResultOfTicketMetadata results. Line 11 shows checking the result Status before continuing Lines 12-17 show doing something with the result Data if the operation was a success Line 21 shows doing something with the error message when the operation failed.
1 public async Task RefreshData_Executed() 2 { 3 Executing = true; 4 ErrorMessage = string.Empty; 5 6 try 7 { 8 DownloadServiceClient client = new DownloadServiceClient(); 9 ResultOfTicketMetadata result = await client.GetMetaDataAsync(appId, CredentialsVM.SiteId, CredentialsVM.AuthCode); 10 11 if (result.Status == Status.Success) 12 { 13 TicketMetadata ticketMetaData = result.Data; 14 15 16 17 18 19
20 21 22 23 24 25 26 27 21 22 23 }
this.EarliestBusinessDate = ticketMetaData.EarliestBusinessDate; this.LatestBusinessDate = ticketMetaData.LatestBusinessDate; this.EarliestClosedOnDate = ticketMetaData.EarliestClosedOnDate; this.LatestClosedOnDate = ticketMetaData.LatestClosedOnDate; } else
{ ErrorMessage = result.Reason; } } catch (Exception ex) { ErrorMessage = ex.Message; } Executing = false;
6
Data Identification We now offer three ways for you and your integration partners to align data from multiple locations. Enterprise Reference Numbers allow you to identify data in 2Touch. Local Reference Identifiers and Local Reference Numbers allow you to identify data in the receiving software. ERNs LRNs and LRIs
Pros
You control the values Automatically supplied. Mapping is centralized
Cons
You have to maintain the values at each location. You have to match the data in every 3rd party application.
Enterprise Reference Numbers (ERNs) Enterprise reference numbers are identifiers you control and enter into 2Touch to identify departments, categories, menu items, pricing levels, modifier groups, unique modifiers, modifier options, course, employees, job descriptions, stations, station types, payment types, discounts, and coupons. Since you control ERNs, you can make them the same at every location.
Local Reference Identifier (LRIs) Local Reference Identifiers are globally unique values automatically generated and supplied by 2Touch. Third party software can use these values to identify equivalent data. LRIs were introduced in the DataKey V3. Data collected in previous versions will not have an LRI. Data collected in V3 or after will have LRIs.
Local Reference Number (LRNs) Local Reference Numbers are locally unique and supplied by 2Touch. The numbers generated are unique within each location and relative to each data type. For example, no two menu items at a location will have the same LRN. The numbers are not unique between data types. A menu item and a modifier might have the same LRN. The numbers are not unique between locations. Two different menu items from two locations might have the same LRN. In order to properly identify the data, you must use the LRN, the data type, and the location. LRNs were introduced in the DataKey V3. Data collected in previous versions will not have an LRN. Data collected in V3 or after will have LRNs.
7
Ticket Methods GetMetaData GetMetaData returns summary information about your data. Specifically, it returns the earliest business date, latest business date, earliest ticket closed on date, and latest ticket closed on date. This method should be used to ensure data is available before calling other methods. Parameters Name applicationId siteId authCode
Type Guid Guid Guid
Returns ResultOfTicketMetaData: Name Status Reason Location Data
Type Enum String String Ticket Meta Data
Notes Success = 0, Failure = 1 The reason for a failure The Site Id
TicketMetaData: Name Earliest Business Date Earliest Closed On Date Latest Business Date Latest Closed On Date
Type Notes Date Time Date only Date Time Date Time Date only Date Time
Get Menu Item Usage Get Menu Item Usage returns summary data about the menu items used during the provided time period. Parameters Name Type applicationId Guid siteId Guid authCode Guid From Date Date Time To Date Date Time From Date and to Date are filters on ticket business dates. They are inclusive. Returns ResultOfMenuItemUsageSummary: Name Status Reason
Type Enum String
Notes Success = 0, Failure = 1 The reason for a failure 8
Location String The SiteId Data Menu Item Usage Summary Menu Item Usage Summary: Name Details Net Sales Tax Total
Type Menu Item Usage[] Decimal Decimal Decimal
Menu Item Usage: Name ERN LRI LRN Inventory Usage Name Quantity Sales Amount
Data Type string Unique Identifier Int double string double Decimal
Max Length 36 36
Nullable Y Y Y N N N N
Get Modifier Usage Get Modifier Usage returns summary data about the modifiers used during the provided time period. Parameters Name Type siteId Guid applicationId Guid authCode Guid From Date Date Time To Date Date Time From Date and to Date are filters on ticket business dates. They are inclusive. Returns Result Of Array Of Modifier Group Usage Summary: Name Status Reason Location Data
Type Enum String String Modifier Group Usage Summary[]
Notes Success = 0, Failure = 1 The reason for a failure The SiteId
Modifier Group Usage Summary: Name
Data Type
Max Length Nullable
9
ERN LRI LRN Modifiers Name Quantity
string 36 Unique Identifier 36 Int Modifier Usage[] string double
Y Y Y N N N
Modifier Usage: Name ERN LRI LRN Inventory Usage Name Price Level Price Level ERN Price Level LRI Price Level LRN Quantity
Type string Unique Identifer Int double string String String Unique Identifier Int double
Max Length 36 36
Nullable Y Y
36 36
Y N N N Y Y Y N
Get Ticket Details GetTicketDetails returns complete data about tickets. Parameters Name applicationId siteId authCode Business Date
Type Guid Guid Guid Date Time
Returns Result Of Array Of Ticket DTO: Name Status Reason Location Data
Data type Enum String String Ticket DTO[]
Description Success = 0, Failure = 1 The reason for a failure The Site Id
Ticket DTO: A Ticket Header contains summary data for a ticket as well as Menu Items, Payments, Gift Card Increases, and Gift Certificate Increases. Field Datatype Max Nullable Description Length Id Unique N Unique Id of this record Identifier Amount Due Decimal Y The total amount due from the customer
10
Annual ZCount
Int
APIVersion Float Auto Tab String Employee Id Auto Tab String Employee ERN Auto Tab Unique Employee LRI identifier Auto Tab Int Employee LRN Auto Gratuity Decimal House Amount Auto Gratuity Decimal Total Amount
N
25
N Y
36
Y
36
Y Y
The number of Z's since the beginning of the year. The format is YYYYdddd where YYYY is the year and dddd is the number of Zs processed this year. The DataKey version used to upload the ticket. The Id of the employee that owns the ticket when this is an AutoTab ticket The ERN of the employee that owns the ticket when this is an AutoTab ticket The LRI of the employee that owns the ticket when this is an AutoTab ticket The LRN of the employee that owns the ticket when this is an AutoTab ticket
Y
The amount of the Auto Gratuity tip kept by the establishment.
Y
25
N
Employee String 36 ERN Employee LRI Unique 36 identifier Employee Int LRN Future Float Payment Gift Card Gift Card Increases Increas DTO[] Gift Gift Certificate Certificate Increases Increas DTO[] Guest Count Int
Y
The amount of tip from the check as determined by the Auto Gratuity Percent and the Sub-Total, Total, Discounted SubTotal or Discounted Total depending on the system settings. The business date of this ticket. The Date and Time the ticket was closed. The total cost of menu items and modifiers The Date and Time the ticket was created. Note that due to split checks and item transfers, the ticket header could be created after a line item. The employeeId of the employee that owns the ticket. This could be the employee that opened the ticket or closed the ticket based on your settings. The owner could have been transferred to another employee. The ERN of the employee that owns the ticket.
Y
The LRI of the employee that owns the ticket.
Y
The LRN of the employee that owns the ticket.
Y
The Payment amount taken on an a Future Order prior to completing the order.
Gross Sale Amount
Y
Business Date Closed On Cost Created On
Date Date Time Float Date Time
Employee Id String
Decimal
N N Y N
Y
Y
Y
The number of people on a ticket when usinig table management. Guest count is not necessarily required are can be null. The total gross sale amount
11
Menu Items
Menu Item DTO[] Decimal
Net Sale Amount Order Origin String
Payments
Y
3
Payment DTO[] Decimal
Promo Amount Station Name String
Y
The total of the ticket line items without taxes.
Y
Where the order started. A value of NULL means the order was started at a POS Station. A value of 'W' means the order started from 2TouchPOS' Online Ordering module.
Y Y
The total of the promo amounts
25
N
Station ERN String Station LRI Unique Idenfifier Station LRN Int Tab Name String
36 36
Y Y
The name of the station where the ticket was closed. When the ticket was completed by a driver drop, StationName is the delivery station's name. The ERN of the station where the ticket was closed. The LRI of the station where the ticket was closed.
25
Y Y
Table Name
25
Y
36 36
Y Y Y
The LRN of the station where the ticket was closed. The name given to the tab. A null value indicates a transaction that wasn't placed on a table or tab and 2TouchPOS is set to not require names. The name of the tab is provided when the ticket is associated with a table. The name of the table for this ticket. The value will be null when not affiliated with a table. The amount of Tax from Tax 1 The ERN of Tax 1 The LRN of Tax 1
Y Y Y Y Y
The LRI of Tax 1 The name of Tax 1 The amount of Tax from Tax 2 The ERN of Tax 2 The LRN of Tax 2
36 36
Y Y Y Y Y
The LRI of Tax 2 The name of Tax 2 The amount of Tax from Tax 3 The ERN of Tax 3 The LRN of Tax 3
25 20
Y Y N
12
N
The LRI of Tax 3 The name of Tax 3 A 2TouchPOS generated identifier for the ticket. The format is YYYYMMDDhhmmTTTXXXXX where YYYY is the year, MM is the month, DD is the day, hh is the hour in 24-hour format, mm is the minute, TTT is the terminal number, XXXX is the sequential ticket number for that day. Indicates the type of transaction. The valid values are Transaction, Comp, Spill.
String
Tax1Amount Decimal Tax1ERN String Tax1 LRI Unique Identifier Tax1 LRI Int Tax1Name String Tax2Amount Decimal Tax2ERN String Tax2 LRI Unique Identifier Tax2 LRI Int Tax2Name String Tax3Amount Decimal Tax3ERN String Tax3 LRI Unique Identifier Tax3 LRI Int Tax3Name String Ticket String Number
Ticket Type
String
25 36 36
25
12
Menu Item DTO: Column Id Ticket Id Amount Due
Data type Max Length Unique Identifier Unique Identifier Decimal
Nullable Description N
Primary Key
N
Foreign Key to the Ticket
Y
20 36 36
Y Y Y Y
NetSaleAmount plus taxes. This is the amount the customer pays. Z report identifier. The number of Z's since the beginning of the year. The format is YYYYdddd where YYYY is the year and dddd is the number of Zs processed this year. The amount deducted from an automatically applied coupon The business date of this ticket item. Indicates that the item had a surcharge applied to it because it was not paid for in cash. The cost of the item as entered into 2TouchPOS. The name of the course this item was served in. The ERN of the course this item was served in. The LRN of the course this item was served in.
25
Y N N
The LRI of the course this item was served in. The date and time this item was rung onto the ticket. The name of the department the item is in.
36
Y
The ERN of the department the item is in.
36
Y
The LRI of the department the item is in.
Y
The LRN of the department the item is in.
Y
The amount the item was discounted by
36 50
Y Y
36
Y
36
Y
Annual ZCount Int
Y
Auto Coupon Amount Business Date Cash Discount Surcharge Cost Course Name Course ERN Course LRI
Decimal
Y
Date Time Bit
Y Y
Float String String Unique Identifier Int Date Time String
Course LRN Created On Department Name Department String ERN Department LRI Unique Identifier Department Int LRN Discount Decimal Amount Discount ERN String Discount String Employee Id Discount String Employee ERN Discount Unique Employee LRI Identifier Discount Int Employee LRN Discount LRI Unique Identifier Discount LRN Int Discount Name String Employee Id String Employee ERN String
36
Y
The ERN of the discount applied to this item. The name of the employee receiving the employee discount applied to the item. The ERN of the employee receiving the employee discount applied to the item. The LRI of the employee receiving the employee discount applied to the item. The LRN of the employee receiving the employee discount applied to the item. The LRI of the discount applied to this item.
25 25 36
Y Y N Y
The LRN of the discount applied to this item. The name of the discount applied to this item. The employee Id of the employee that rang in this item. The ERN of the employee that rang in this item.
Y
13
Employee LRI Unique Identifier Employee LRN Int ERN String Gross Sale Decimal Amount Inventory Usage Float LRI Unique Identifier LRN Int Name String Net Sale Decimal Amount Order Type String Order Type String ERN Order Type LRI Unique Identifier Order Type Int LRN Original Ticket String Number PLU String Price Level String ERN Price Level LRI Unique Identifier Price Level Int LRN Price Level String Name Promo Amount Decimal Quantity Sold Float Refund Flag Bit Reward Points Float Earned Reward Points Float Redeem Reward Card String Number Reporting String Category ERN Reporting Unique Category LRI Identifier Reporting Int Category LRN Reporting String Category Name Seat Number Int
36
Y
The LRI of the employee that rang in this item.
36
Y Y Y Y Y
The LRN of the employee that rang in this item. The ERN of the item. The Price per item * quantity. This before discounts and taxes. The quantity * the inventory factor The LRI of the item
50
Y N Y
The LRN of the item The name of the item. Gross Sale Amount after discounts but before taxes.
15 36
Y Y
The name of the order type. The ERN of the order type.
36
Y
The LRI of the order type
Y
The LRN of the order type
20
Y
The ticket number this menu item was original rung on.
14 36
Y Y
The price look up of the item. The ERN of the price level the menu item was sold at.
36
Y
The LRI of the price level the menu item was sold at.
Y
The LRN of the price level the menu item was sold at.
Y
The name of the price level the menu item was sold at.
Y Y N Y
Promotional Amount Redeemed to purchase this item. The quantity of the item sold. Indicates if this line item represents a return. The number of rewards points earned
Y
36
25
9
Y
36
Y
The number of rewards points redeemed to purchase this item. The Reward Card Number points were added to or subtracted from. The ERN of the category this item is reported in.
36
Y
The LRI of the category this item is reported in.
Y
The LRN of the category this item is reported in.
N
The name of the category this item is reported in.
Y
The seat number ordering the item.
25
14
Sort Order
Int
Station Name Station ERN Station LRI
String String Unique Identifier Station LRN Int Tax1Amount Decimal Tax1Name String Tax1ERN String Tax1 LRI Unique Identifier Tax1 LRN Int Tax2Amount Decimal Tax2Name String Tax2ERN String Tax2 LRI Unique Identifier Tax2 LRN Int Tax3Amount Decimal Tax3Name String Tax3ERN String Tax3 LRI Unique Identifier Tax3 LRN Int Taxable Amount Decimal
N 25 36 36
N Y Y
The sort order of the menu items and modifiers entered on the ticket. The name of the station where the item was rung. The ERN of the station where the item was rung. The LRI of the station where the item was rung.
25 36 36
Y Y Y Y Y
The LRN of the station where the item was rung. The amount of Tax from Tax 1 The name of Tax 1 The ERN of Tax 1 The LRI of Tax 1
25 36 36
Y Y Y Y Y
The LRN of Tax 1 The amount of Tax from Tax 2 The name of Tax 2 The ERN of Tax 2 The LRI of Tax 2
25 36 36
Y Y Y Y Y
The LRN of Tax 2 The amount of Tax from Tax 3 The name of Tax 3 The ERN of Tax 3 The LRI of Tax 3
Y Y
The LRN of Tax 3 The value that taxes were calculated on.
ModifiersDTO: Column
Data type
Max Length
Id
Nullable Description
Unique Identifier Menu Item Id Unique Identifier Parent Modifier Id Unique Identifier Amount Due Decimal
N
Primary Key
N
Foreign Key to the Menu Item
Y
Auto Coupon Amount Cash Discount Surcharge Cost
Decimal
Y
Bit
Y
Float
Y
Course Name Course ERN Course LRI
String String Unique Identifier Int
Y Y Y
The modifier that this modifier modified. If NULL, this modifier modifies the Menu Item directly. Net Sale Amount plus taxes. This is the amount the customer pays. The amount deducted from an automatically applied coupon. Indicates that the item had a surcharge applied to it because it was not paid for in cash. The cost of this modifier. Cost is defined as the per unit cost *quantity * inventory factors. The name of the course this item was served in. The ERN of the course this item was served in. The LRI of the course this item was served in.
Y
The LRN of the course this item was served in.
Course LRN
Y
20 36 36
15
Created On Discount Amount Discount ERN Discount LRI Discount LRN Discount Employee Id Discount Employee ERN Discount Employee LRI Discount Employee LRN Discount Name Employee Id Employee ERN Employee LRI Employee LRN Gross Sale Amount Inventory Usage Modifier Group Modifier Group ERN Modifier Group LRI Modifier Group LRN Modifier Option Modifier Option ERN Modifier Option LRI Modifier Option LRN Modifiers
Date Time Decimal String Unique Identifier Int String
36 36
N Y Y Y
The date and time this item was rung onto the ticket. The amount the item was discounted by The ERN of the discount applied to this item. The LRI of the discount applied to this item.
50
Y Y
String
36
Y
Unique Identifier Int
36
Y
String String
25 25
Y N
String Unique Identifier Int Decimal
36 36
Y Y
The LRN of the discount applied to this item. The name of the employee receiving the employee discount applied to the item. The ERN of the employee receiving the employee discount applied to the item. The LRI of the employee receiving the employee discount applied to the item. The LRN of the employee receiving the employee discount applied to the item. The name of the discount applied to this modifier. The employee Id of the employee that rang in this item. The ERN of the employee that rang in this item. The LRI of the employee that rang in this item.
Y
25 36
N Y Y
The LRN of the employee that rang in this item. The Price per item * quantity. This before discounts and taxes. The quantity * the inventory factor The Name of the modifier group the modifier is in. The ERN of the modifier group the modifier is in
Unique Identifier Int
36
Y
The LRI of the modifier group the modifier is in
Y
The LRN of the modifier group the modifier is in
String String
50 36
Y Y
The Name of the modifier option. The ERN of the modifier option.
Unique Identifier Int
36
Y
The LRI of the modifier option.
Y
The LRN of the modifier option.
Float String String
Y Y
Modifier DTO[] Net Sale Amount Decimal
Y Y
Original Ticket String Number PLU String Price Level Name String
20
Y
14 25
Y Y
Price Level ERN
36
Y
String
The Gross Sale Amount less discounts but before taxes The ticket number this menu item was original rung on. The price look up of the item. The name of the price level the menu item was sold at. The ERN of the price level the menu item was sold at.
16
Price Level LRI Price Level LRN Promo Amount Quantity Sold Refund Flag Reward Points Earned Reward Points Redeem Reporting Category Name Reporting Category ERN Reporting Category LRI Reporting Category LRN Segment Name Segment ERN Segment LRI Segment LRN Sort Order Station Name Station ERN Station LRI Station LRN Tax1Amount Tax1Name Tax1ERN Tax1 LRI Tax1 LRN Tax2Amount Tax2Name Tax2ERN Tax2 LRI Tax2 LRN Tax3Amount Tax3Name Tax3ERN Tax3 LRI Tax3 LRN
Unique Identifier Int
36
Y
The LRI of the price level the menu item was sold at.
Y
String
25
N
The LRN of the price level the menu item was sold at. Promotional amount redeemed to purchase this item. The quantity of the item sold. True if this modifier is being refunded. The number of reward points earned in purchasing this modifier. The number of rewards points used to purchase this modifier. The name of the reporting category for this modifier.
String
36
Y
The ERN of the reporting category for this modifier.
Unique Identifier Int
36
Y
The LRI of the reporting category for this modifier.
Y
The LRN of the reporting category for this modifier.
String String Unique Identifier Int Int
30 36 36
Y Y Y
Then name of the segment this item is divided into. Then ERN of the segment this item is divided into. Then LRI of the segment this item is divided into.
4
Y N
String String Unique Identifier Int Decimal String String Unique Identifier Int Decimal String String Unique Identifier Int Decimal String String Unique Identifier Int
25 36 36
N Y Y
Then LRN of the segment this item is divided into. The sort order of the menu items and modifiers entered on the ticket. The name of the station where the item was rung. The ERN of the station where the item was rung. The LRI of the station where the item was rung.
25 36 36
Y Y Y Y Y
The LRN of the station where the item was rung. The amount of Tax from Tax 1 The name of Tax 1 The ERN of Tax 1 The LRI of Tax 1
25 36 36
Y Y Y Y Y
The LRN of Tax 1 The amount of Tax from Tax 2 The name of Tax 2 The ERN of Tax 2 The LRI of Tax 2
25 36 36
Y Y Y Y Y
The LRN of Tax 2 The amount of Tax from Tax 3 The name of Tax 3 The ERN of Tax 3 The LRI of Tax 3
Y
The LRN of Tax 3
Decimal Float Bit Float
Y Y N Y
Float
Y
17
Taxable Amount Unique Modifier Name Unique Modifier ERN Unique Modifier LRI Unique Modifier LRN
Decimal String
25
Y N
The value that taxes were calculated on. The unique name of this modifier
String
36
Y
The ERN of the unique modifier
Unique Identifier Int
36
Y
The LRI of the unique modifier
Y
The LRN of the unique modifier
Gift Card Increase DTO: Column
Data type Max Length Id Unique Identifier Ticket Id Unique Identifier Amount Due Decimal
Nullable Description
Annual Z Count
Y
N
Primary Key
N
Y N Y
The ID of the ticket this Gift Card Increase is associated with Net Sale Amount plus taxes. This is the amount the customer pays. Z report identifier. The number of Z's since the beginning of the year. The format is YYYYdddd where YYYY is the year and dddd is the number of Zs processed this year. The business date of this ticket item. The date and time this item was rung onto the ticket. The amount the item was discounted by
36
Y
The ERN of the discount applied to this item.
36
Y
The LRI of the discount applied to this item.
Y
The LRN of the discount applied to this item.
25
Y
The name of the discount applied to this item.
25 36
N Y
The employee Id of the employee that rang in this item. The ERN of the employee that rang in this item.
36
Y
The LRI of the employee that rang in this item.
Y
The LRN of the employee that rang in this item.
Y
The amount the gift card was increased by
15 36
N Y
The name of the order type. The ERN of the order type.
36
Y
The LRI of the order type.
Y
The LRN of the order type.
Int
Business Date Date Created On Date Time Discount Decimal Amount Discount String ERN Discount LRI Unique Identifier Discount Int LRN Discount String Name Employee Id String Employee String ERN Employee Unique LRI Identifier Employee Int LRN Gift Increase Decimal Amount Order Type String Order Type String ERN Order Type Unique LRI Identifier Order Type Int
N
18
LRN Original String Ticket Number Quantity Sold Float Reward Float Points Earned Reward Float Points Redeem Reward Card String Number Seat Number Int Sort Order Int Station ERN String Station LRI Unique Identifier Station LRN Int Station Name String
20
9
Y
The ticket number this menu item was original rung on.
Y Y
The quantity of the item sold. The number of rewards points earned
Y
The number of rewards points used to purchase this modifier.
Y
36 36
Y Y
The Reward Card Number points were added to or subtracted from. The seat number ordering the item. The sort order of the menu items and modifiers entered on the ticket. The ERN of the station where the item was rung. The LRI of the station where the item was rung.
25
Y N
The LRN of the station where the item was rung. The name of the station where the item was rung.
Y N
Gift Certificate Increases: Column
Data type Max Length Id Unique Identifier Ticket Id Unique Identifier Amount Due Decimal
Nullable Description
Annual Z Count
Y
N
Primary Key
N
Y N Y
The ID of the ticket this Gift Certificate Increase is associated with Net Sale Amount plus taxes. This is the amount the customer pays. Z report identifier. The number of Z's since the beginning of the year. The format is YYYYdddd where YYYY is the year and dddd is the number of Zs processed this year. The business date of this ticket item. The date and time this item was rung onto the ticket. The amount the item was discounted by
36
Y
The ERN of the discount applied to this item.
36
Y
The LRI of the discount applied to this item.
Y
The LRN of the discount applied to this item.
25
Y
The name of the discount applied to this item.
25 36
N Y
The employee Id of the employee that rang in this item. The ERN of the employee that rang in this item.
36
Y
The LRI of the employee that rang in this item.
Int
Business Date Date Created On Date Time Discount Decimal Amount Discount String ERN Discount LRI Unique Identifier Discount Int LRN Discount String Name Employee Id String Employee String ERN Employee Unique LRI Identifier
N
19
Employee Int LRN Gift Increase Decimal Amount Order Type String Order Type String ERN Order Type Unique LRI Identifier Order Type Int LRN Original String Ticket Number Quantity Sold Float Reward Float Points Earned Reward Float Points Redeem Reward Card String Number Seat Number Int Sort Order Int Station ERN String Station LRI Unique Identifier Station LRN Int Station Name String
Y
The LRN of the employee that rang in this item.
Y
The amount the gift certificate was increased by
15 36
N Y
The name of the order type. The ERN of the order type.
36
Y
The LRI of the order type.
Y
The LRN of the order type.
Y
The ticket number this menu item was original rung on.
Y Y
The quantity of the item sold. The number of rewards points earned
Y
The number of rewards points used to purchase this modifier.
Y
20
9
36 36
Y Y
The Reward Card Number points were added to or subtracted from. The seat number ordering the item. The sort order of the menu items and modifiers entered on the ticket. The ERN of the station where the item was rung. The LRI of the station where the item was rung.
25
Y N
The LRN of the station where the item was rung. The name of the station where the item was rung.
Y N
Payment DTO: Records a payment where a payment is cash, credit card, or coupon. Rewards and Loyalty purchases are recorded against the menu item. Column Data type Max Nullable Description Length Id Unique N Primary Key Identifier Ticket Id Unique N Foreign Key to the Ticket Identifier Annual Z Count Int Y The number of Z's since the beginning of the year. The format is YYYYdddd where YYYY is the year and dddd is the number of Zs processed this year. Business Date Date Time N The business date of the payment. Card Holder Name String 26 Y The card holder’s name for credit card payments Card Type String 20 Y AMEX, DISCOVER, MASTERCARD, DINERS, VISA Change Given Decimal Y
20
Change Kept Coupon Name Coupon ERN
Decimal String String
Coupon LRI
Y
Coupon LRN
Unique 36 Identifier Int
Coupon Percent
Float
Y
20 36
Y Y Y
Y
Coupon Type String CreditCardNumberLast4Digits String Employee Name String
50 4 25
Y Y N
Employee ERN
String
36
Y
Employee LRI
Y
Employee LRN
Unique 36 Identifier Int
Foreign Amount Incentive Card Number
Decimal String
Y Y
Payment Taken On Payment Type Payment Name Payment ERN Payment LRI
N N N Y Y
Payment LRN Station Name
Date Time Int String 50 String 36 Unique 36 Identifier Int String 25
Station ERN
String
36
Y
Station LRI
Y
Station LRN
Unique 36 Identifier Int
Tip Amount
Decimal
Y
Tip House Amount Total Amount
Decimal Decimal
Y Y
9
Y
Y N
Y
Name of the coupon The ERN of the coupon used in this transaction The LRI of the coupon used in this transaction The LRN of the coupon used in this transaction The percent reduction in cost due to the coupon The type of coupon used Last 4 digits of the credit card The employee Id of the employee that rang in this item. The ERN of the employee that rang in this item. The LRI of the employee that rang in this item. The LRN of the employee that rang in this item. The amount paid in foreign currency The card number used to make a loyalty/reward card payment Date and time that the payment was taken Type of payment Name of the payment type The ERN of the payment type The LRI of the payment type The LRN of the payment type The name of the station where the payment was taken. The ERN of the station where the payment was taken. The LRI of the station where the payment was taken. The LRN of the station where the payment was taken. The amount of tip including the amount the house keeps from the tip. Amount the house keeps from the tip. The total amount paid including the tip amount
21
Time Clock Methods Time clock data is not locked after any amount of time. That is, an adjustment to a time clock entry can be made at any time in the future. Therefore, who clocked in when and how long they worked could change at any time. Note that a clock out is required before the data for the individual interaction to be uploaded.
GetAdjustedTimeClockData GetAdjustedTimeClockData returns adjusted time clock entries whose clock out time is after the from date and before the to date at the time of the request. Parameters Name applicationId siteId authCode fromDate toDate
Type Notes Guid Guid Guid DateTime This is filtering on the Clock Out time. DateTime This is filtering on the Clock Out time.
Returns ResultOfArrayOfTimeClockState: Name Status Reason RequestedOn Location Data
Type Enum String DateTime String TimeClockState[]
Notes Success = 0, Failure = 1 The reason for a failure The date and time of the request The Site Id An array of the TimeClockData
TimeClockState: Name
Data Type
Max Length
AutoGratuityTips
Decimal
N
ClockInTime ClockOutTime CreditCardTips
Date Time Date Time Decimal
N N N
CustomerAccountTips Decimal DeclaredCashTips Employee ERN Employee LRI Employee LRN EmployeeFirstName EmployeeLastName Id
Decimal String Unique Identifier Int String String Guid
Nullable Notes
N Y Y
The amount of tips collected via Auto Gratuity The date and time of the clock in The date and time of the clock out The amount of tips from credit card transactions The amount of tips from payments to customer accounts The amount of cash tips declared The ERN of the employee. The LRI of the employee.
Y N N N
The LRN of the employee. The employee’s first name. The employee’s last name. Unique Id for this record
N
36 36
25 25
22
JobType ERN JobType LRI JobType LRN JobTypeName PayRate Sales
String Unique Identifier Int String Decimal Decimal
36 36
25
Y Y
The ERN assigned to the job type. The LRI assigned to the job type.
Y N N N
The LRN assigned to the job type. The name of the job type The payrate for this clock in/out The amount of sales generated for this clock in/out
GetRawTimeClockData GetRawTimeClockData returns the raw data for time clock interactions. The way the DataKey captures time clock data is through a sequence of TimeClockStates. The first state is normally created when the user clocks in. This state is also used to capture the clock out time so long as no adjustments are made. Each new state represents the best data at that moment. What Triggers and Adjustment?
Adjusting any of the following creates an adjustment record.
Clock in time Clock out time Job type Pay Rate Cash Tips Credit card Tips Account tips Auto Gratuity tips Sales total
Creating a clock in entry creates an adjustment record. Deleting a clock entry also creates an adjustment record. How is the Data Related
In every scenario, a TimeClockEntry is created. The TimeClockEntry ties all of the details together. In the majority of cases, you will have a TimeClockEntry and an associated TimeClockState. If adjustments have been performed, they will be related to the TimeClockEntry and point to new TimeClockStates. TimeClockAdjustments are ordered. When processing adjustments, it is important to process them in order.
23
Special Cases
If the user clocks in, then the TimeClockEntry will have a TimeClockState. If the manager clocks in an employee then the TimeClockEntry’s TimeClockState will be null. The manager clock in will be captured as an adjustment. The adjustments state represents the clock in. If the TimeClockEntry is deleted, the last TimeClockAdjustment’s TimeClockState will be null. Parameters Name applicationId siteId authCode fromDate toDate
Type Guid Guid Guid DateTime DateTime
Returns ResultOfRawTimeClockData: Name
Type
Notes
24
Status Reason RequestedOn Location Data
Enum String DateTime String RawTimeClockData
Success = 0, Failure = 1 The reason for a failure The date and time of the request The Site Id An array of the TimeClockData
RawTimeClockData: Name Type Notes Adjustments TimeClockAdjustment[] The array of adjustments Entries TimeClockEntry[] The array of time clock entries TimeClockAdjustment: Name
Data Type
Max Length
Nullable Notes
Adjustment Ordering Adjustment Time Adjustor ERN
Int
N
DateTime String
36
N Y
Adjustor LRI
36
Y
Adjustor LRN
Unique Identifier Int
AdjustorFirstName
String
25
N
AdjustorLastName
String
25
N
Id TimeClockEntryId
Guid Guid
N N
TimeClockState
TimeClockState
Y
Y
An integer indicating the order in which this adjustment occurred The date and time the adjustment occurred The ERN of the employee that made the adjustment The LRI of the employee that made the adjustment The LRN of the employee that made the adjustment The first name of the employee that made the adjustment The last name of the employee that made the Unique Id for this record The id of the time clock entry being adjusted The resulting state from this adjustment. See TimeClockState in GetAdjustedTimeClockData
TimeClockEntry: Name Id TimeClockState TimeClockStateId
Type Guid TimeClockState Guid
Notes The id of the time clock entry The time clock state created on clock in. The id of the time clock state created on clock in.
25
