Altametrics API Library
Introduction
The purpose of this document is to provide detailed description of data field required to fetch and post the data from Hubworks, also contains the type of file format that Hubworks will support to display the data. In Any connector we are trying to fetch the sales, employees, menu-mix, invoices, and ordering etc. data from POS and try to post the data of employees and schedules.
Data Transmission Files
There are basically two types of files:
-
1. Configuration File: It is basically configuration file where different parameters are defined with their unique ids and name. This file will be transmitted when there is any modification or addition of any new parameter. This table acts as a look-up table for transaction file
-
2. Transaction file: This file will transmitted on daily basis that contains the sales data, employee data, menu-mix data etc.
-
3. File naming convention of both the files should be as per the format given below:
<filename>_storeID_<MMDDYYYY>
Configuration File
Configuration files are basically a file containing various look ups for the transaction data to work on to and create appropriate data object for use in Hubworks applications. Look-Up is basically a sort of object index that transaction file will refer to do correct mapping of data values. This file will contain the following look-ups:
Jobs
This look-up contains the details of all the positions that are configured at the POS system. Each position will be uniquely identified using its ID and notation of the same will be done based on the supplied name of the position.
Required Parameters
Parameter | Description | Data Type | Required |
---|---|---|---|
Id | ID of the job. | string | Yes |
name | Name of the job. | string | Yes |
isSalaried | If the position is salaried (non-hourly pay) | boolean | No |
wage | Hourly pay rate of job. | decimal(2) | No |
{
"jobs":
[
{
"id": "701",
"name": "Chef",
"isSalaried": true,
"wage": 0.0
}
]
}
Categories
This look-up contains an array of different categories and each category should have the fields mentioned in the parameter details table below. The details of each category that are uniquely identified using its id.
Required Parameters
Parameter | Description | Data Type | Required |
---|---|---|---|
Id | ID of the item category. | string | Yes |
name | Name of the item category. | string | Yes |
{
"categories":
[
{
"id": "500",
"name": "Burgers"
}
]
}
Items
This lookup contains the details of menu items that are uniquely identified using its id and name.
Required Parameters
Parameter | Description | Data Type | Required |
---|---|---|---|
id | The ID of an item | string | Yes |
name | The name of the item. | string | Yes |
categoryID | The name of the category | string | Yes |
price | Price of an item | decimal(2) | Yes |
{
"items":
[
{
"id": "5001",
"name": "Bacon Avocado Cheeseburger",
"categoryID": "500",
"price": 11.59
}
]
}
Revcenter
This lookup contains the details of sales by type from where the order is being placed. They are uniquely identified using its id and name.
Required Parameters
Parameter | Description | Data Type | Required |
---|---|---|---|
Id | ID of the revCenter. | string | Yes |
name | Name of the revCenter. | string | Yes |
{
"revCenters":
[
{
"id": "1",
"name": "Dining Room"
}
]
}
Voids
This lookup contains the details of the voids due to which the items in a check are being canceled. These voids are defined with a unique id and their name or reason.
Required Parameters
Parameter | Description | Data Type | Required |
---|---|---|---|
Id | ID of the void. | string | Yes |
name | The reason for void. | string | Yes |
{
"voids":
[
{
"id": "V011",
"name": "Unavailable"
}
]
}
Discounts
This lookup contains the details of the voids due to which the items in a check are being canceled. These voids are defined with a unique id and their name or reason.
Required Parameters
Parameter | Description | Data Type | Required |
---|---|---|---|
Id | ID of the discount. | string | Yes |
name | Discount Name. | string | decimal(2) |
{
"discounts":
[
{
"id": "C011",
"name": "OTH 100% Off"
}
]
}
Payment Types
This lookup contains the details of all the payment type that are configured at the POS system. Each payment type will be uniquely identified using its ID and name.
Required Parameters
Parameter | Description | Data Type | Required |
---|---|---|---|
Id | The ID of the payment type | string | Yes |
name | Name of payment type | string | Yes |
Payment group | Name of payment group | string | Yes |
{
"paymentTypes":
[
{
"id": "1",
"name": "Cash",
"paymentGroup": "CASH"
}
]
}
Paid In/Out Payment
This Lookup contains the detail of all the Paid In/Out payments that are configured in the POS system. Each Paid In/Out type will be uniquely identified using its Id and Name.
Required Parameters
Parameter | Description | Data Type | Required |
---|---|---|---|
Id | The Id of the payment (Paid In/Out) reason | string | Yes |
name | The name Of the payment (Paid In/Out) reason | string | Yes |
{
"paidInOut":
[
{
"id": "1",
"name": "Food",
}
]
}
Employees
This lookup contains the details of all the employee that are uniquely identified by their id and first name and and jobs are assigned to employee.
Required Parameters
Parameter | Description | Data Type | Required |
---|---|---|---|
id | The ID of an employee | string | Yes |
First name | First name of an employee | string | Yes |
Last name | Last name of an employee | string | No |
empNum | Employee Number of an employee | integer | No |
roleId | Role Id of an employee | string | No |
empJobs | |||
Id | ID of the job. | string | Yes |
wage | Hourly pay rate of job. | decimal(2) | No |
isprimary | Default job of the Employee | boolean | No |
{
"employees":
[
{
"id": "23",
"firstName": "Drew",
"lastName": "Barrymore",
"empNum": 99998889,
"roleID":"1",
"empJobs":
{
"id": "701",
"wage": 3.45,
"isPrimary": false
}
}
]
}
Transaction file
Transaction file is the file containing daily transactions data of a single store.Transaction data refers to four types of data checks, paidins & paidouts, deposits, and shifts (timekeeping data).
One or more types of transaction data can be sent in the same request.
Check Data
A "check" refers to a single customer bill of sale. Within every "check" there are several data types. Check Info, Check Discounts, Check Items (includes voids, discounts, and modifiers), and Check Payments.
{
"checks": [
{
"checkNum": "10001",
"orderNum": 1007,
"employeeID": "104",
"openedAt": "2018-04-10T09:09:00",
"closedAt": "2018-04-10T10:42:00",
"revCenterID": "1",
"lastModifiedAt": "2018-04-10T10:42:00",
"guestCount": 1,
"tableNum": "1",
"inclusiveTax": 0.0,
"exclusiveTax": 0.0,
"total": 1.84,
"busiDate": "2018-04-10",
"busiTime": "09:09:00",
"items": [{
"itemID": "355",
"quantity": 1.0,
"price": 3.69,
"inclusiveTax": 0.0,
"amount": 1.84,
}, {
"itemID": "1079",
"quantity": 1.0,
"price": 0.0,
"inclusiveTax": 0.0,
"amount": 0.0
}, {
"itemID": "304",
"quantity":1.0,
"price": 0.0,
"inclusiveTax": 0.0,
"amount": 2.89
}
],
"payment": {
"total": 1.85,
"paymentTypeID": "2",
"received": 0.0,
"change": 0.0,
"tip": 0.0,
"appliedAt": "2007-03-29T18:10:00"
},
"discounts": [
{
"id": "C012",
"name": "Comp",
"amount": 40.45,
"itemID": "5011"
}
],
"voids": [
{
"id": "V012",
"qty": 3.0,
"amount": 15.15,
"itemID": "5011"
}
]
}]
}
Check Info
The general check information. Here are the fields for a check:
FIELD | TYPE | REQUIRED | DESCRIPTION |
---|---|---|---|
checkNum | string | Yes | Unique ID for a check for a given POS in a location. |
orderNum | string | Order number which is sometimes associated with a check in some POS systems | |
businessDate | date | Yes | Date used for reporting the sales |
businessTime | time | Yes | Time used for reporting the sales. This is a local time (not UTC) and is used so that we can easily report on sales from 3-4pm at multiple locations across different time zones. |
openedAt | datetime | Yes | Date & time the check was opened |
closedAt | datetime | Date & time the check was closed, if this is NULL, we will report the check as being “open” | |
lastModifiedAt | datetime | Yes | Last time the check was updated |
employeeId | string | ID for Employee assigned to the check. From the configuration data. | |
revCenterId | string | The revenue center ID. From the configuration data. | |
guestCount | integer | Total number of guests. If QSR, just default to 1. | |
tableNum | string | Table number | |
inclusiveTax | decimal(2) | Total amount of inclusive tax | |
exclusiveTax | decimal(2) | Total amount of exclusive tax | |
autoGratuity | decimal(2) | Total amount of auto gratuity applied to the check | |
total | decimal(2) | Yes | The check total |
Check Items
A check can have multiple items applied to it. Here are the fields for an item:
FIELD | TYPE | REQUIRED | DESCRIPTION |
---|---|---|---|
itemid | string | Yes | Sales item ID. From the configuration data. |
quantity | decimal(2) | Yes | Total quantity sold |
amount | decimal(2) | Yes | Total sales amount for this item (this amount SHOULD INCLUDE discount/comp but SHOULD NOT INCLUDE taxes) |
inclusive_tax | decimal(2) | Inclusive tax amount | |
exclusive_tax | decimal(2) | Exclusive tax amount | |
price | decimal(2) | Yes | The price of item |
Check Payments
A check can have multiple payments applied to it. Here are the fields for a payment:
Required Parameters
FIELD | TYPE | REQUIRED | DESCRIPTION |
---|---|---|---|
paymentTypeId | string | Yes | ID for the payment type |
total | decimal(2) | Yes | Total amount of the payment applied towards the check total |
received | decimal(2) | Yes | Total amount received from the customer |
change | decimal(2) | Yes | Total amount of change given to the customer |
tip | decimal(2) | Credit card tip amount | |
appliedAt | datetime | Date & time this payment was applied |
Check Discount
A check can have multiple discounts applied to it. Here are the fields for a discount:
FIELD | TYPE | REQUIRED | DESCRIPTION |
---|---|---|---|
id | string | Yes | The id of item. |
From the configuration data. | |||
quantity | decimal(2) | No | The quantity of the item on which discount is applied. |
amount | decimal(2) | No | The total amount applied as discount. |
itemID | string | yes | The id of the item on which discount is applied. |
Check Voids
A check can have multiple items applied to it. Here are the fields for an item:
FIELD | TYPE | REQUIRED | DESCRIPTION |
---|---|---|---|
id | string | Yes | The Id of the Void. |
quantity | decimal(2) | No | The quantity of the Voided item. |
amount | decimal(2) | No | Total amount of the void. |
itemID | string | No | The id of the voided item. |
Shift Data
A "shift" refers to a single employee’s shift or timeslip that was generated from an employee clocking in and out.
FIELD | TYPE | REQUIRED | DESCRIPTION |
---|---|---|---|
id | string | Yes | Unique ID for a shift in a location. If the POS System does not provide a unique ID, you can try combining the given shift ID with the shift start time. |
employeeId | string | Yes | employee ID for the shift |
jobId | string | Yes | job ID for the shift |
businessDate | date | Yes | date used for reporting the labor |
startTime | time | Yes | time used for reporting the labor |
endTime | time | business time the shift ends | |
startedAt | datetime | Yes | date & time the shift was started |
endedAt | datetime | date & time the shift ended | |
shiftUpdatedAt | datetime | Yes | last time the shift was updated |
totalTime | decimal(2) | Yes | total number of minutes for the shift (including overtime) |
totalPay | decimal(2) | Yes | total cost for the shift (including overtime) |
payRate | decimal(2) | pay rate | |
otPayRate | decimal(2) | pay rate for overtime | |
ccTips | decimal(2) | total credit card tips for the employee shift | |
cashTips | decimal(2) | total cash tips declared by the employee at clock out | |
paidBreakMinutes | decimal(2) | total number of paid break minutes | |
unpaidBreakMinutes | decimal(2) | total number of unpaid break minutes |
{
"shifts": [
{
"id": "10090",
"employeeID": "1009",
"jobID": "3",
"startedAt": "2007-03-28T00:00:00",
"busiDate": "2007-03-27",
"startTime": "00:00:00",
"endTime": "00:00:00",
"endedAt": "2007-03-28T00:00:00",
"shiftUpdatedAt": "2007-03-28T00:00:00",
"totalTime": 300.0,
"totalPay": 47.5,
"payRate": 9.5,
"cashTips": 0.0,
"ccTips": 0.0,
"otPayRate": 0.0,
"paidBreakMinutes": 0.0,
"unpaidBreakMinutes": 0.0
}
]
}
Shift Break Detail
The shift info above has fields for break totals, but break details can also optionally be added (multiple breaks are allowed). Here are the fields for break detail:
FIELD | TYPE | REQUIRED | DESCRIPTION |
---|---|---|---|
startedAt | datetime | Yes | date & time for the start of the break |
endedAt | datetime | Yes | date & time for the end of the break |
Paid In/Out Payment Data
A "paid in/out payment" refers to an incoming or outgoing payment using the paid in/out types from the configuration data.Negative amounts indicate paid out
Here are the fields for a paid in/out payment:
FIELD | TYPE | REQUIRED | DESCRIPTION |
---|---|---|---|
id | string | Yes | The Id of the payment |
amount | decimal(2) | No | The total amount of the payment |
paidAt | datetime | No | The date and time of the payment |
paymentTypeId | string | Yes | The id of the payment type |
busiDate | date | No | The business date on which the payment was made |
lastModifiedAt | datetime | No | Last time the payment was updated |
paidInOutID | string | Yes | The Id of the payment (Paid In/Out) reason |
employeeID | string | Yes | The Id of the employee doing the payment |
custAccountID | string | No | The Id of the existing House account of a customer. |
tip | decimal(2) | The amount of tip given by the customer |
{
"paidInOut": [
{
"id": "P100",
"amount": 100.0,
"paidAt": "2017-03-28T00:00:00",
"paymentTypeID": "1",
"busiDate": "2017-03-27",
"lastModifiedAt": "2017-03-28T00:00:00",
"paidInOutID": "1",
"employeeID": "23",
"custAccountID": "13",
"tip": 2.0
}
]
}
Cash Deposit
Cash Deposit refers to the amount of cash present in the cash drawer at the end of the day.
Here are the fields for cash deposit:
FIELD | TYPE | REQUIRED | DESCRIPTION |
---|---|---|---|
id | string | Yes | unique identifier of the cash deposit |
amount | decimal(2) | Yes | Total amount deposited in the cash deposit/drawer |
busidate | date | Date used for submitting deposit | |
lastModifiedAt | datetime | Yes | Last time the cash drawer amount was updated |
depositedAt | datetime | Yes | Amount submitted into drawer |
employeeID | string | Yes | employee ID for cash deposit |
{
"version": "1.0",
"deposits": [
{
"id": "73309",
"amount": 1196.0,
"busiDate": "2018-04-10",
"lastModifiedAt": "2007-03-28T00:00:00",
"depositedAt": "2007-03-28T00:00:00",
"employeeID": "4018"
},
{
"id": "73312",
"amount": 166.0,
"busiDate": "2018-04-10",
"lastModifiedAt": "2007-03-28T00:00:00",
"depositedAt": "2007-03-28T00:00:00",
"employeeID": "4018"
}
]
}