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. Integer No
Sample Request

  {
    "jobs": 
    [
      {
        "id": 701,
        "name": "Chef",
        "isSalaried": true,
        "wage": 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
Sample Request

    {
      "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 integer Yes
Sample Request

{
  "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
Sample Request
      
{
  "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
Sample Request

{
  "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 Yes
Sample Request

{
  "discounts": 
  [
    {
      "id": "C011",
      "name": "OTH 100% Off"
    "amount": 0.0
    }
  ]
}
          
          

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
Sample Request

{
  "paymentTypes": 
  [
    {
      "id": 1,
      "name": "Cash",
      "paymentGroup": "CASH"
    }
  ]
}
        
        

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. Integer No
isprimary Default job of the Employee boolean No
Sample Request

{
  "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.

Sample Request

{
    "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,
        "inclusiveTax": 0.0,
    "exclusiveTax": 0.0,
        "total": 1.84,
        "busiDate": "2018-04-10",
        "busiTime": "09:09:00",
        "items": [{
        "itemID": 355,
        "quantity": 1,
        "price": 3.69,
        "inclusiveTax": 0.0,
        "amount": 1.84,
        "type": 1 
        }, {
        "itemID": 1079,
        "quantity": 1,
        "price": 0.0,
        "inclusiveTax": 0.0,
        "amount": 0.0
        }, {
        "itemID": 304,
        "quantity": 1,
        "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,
        "amount": 15.15,
        "itemID": "5011" 
    }
    ]
    }]
}
        
        
        

Check Info

The general check information. Here are the fields for a check:

FIELD TYPE REQUIRED DESCRIPTION
checkId string Yes Unique ID for a check for a given POS in a location. If the POS System does not provide a unique ID, you can try combining the check number with the check open datetime.
checkNum string Yes Check number, if no check number exists, you can use the check_id. This does not need to be unique.
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
voids decimal(2)   Amount of voids
discounts decimal(2)   Amount of discounts
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 integer 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
discount xml element See Check Discounts (can only have one)
void xml element See Check XML below for an example. Requires void_id, and optionally approver_id, and applied_at (can only have one)

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
discounts string Yes Discount ID.
From the configuration data.
quantity integer Yes Total number of items affected by this discount
amount decimal(2) Yes Total discount amount for this discount
approver_id string   Employee ID for the manager that approved this discount. From the configuration data.
appliedAt datetime   Date & time this discount was 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 Discount ID.
name integer Yes Type of discount applied.
amount decimal(2) Yes Total discount amount for this discount
itemID string ItemID from configuration file

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

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 unique identifier of the paid in/out payment
amount integer Yes Total amount for this paidIn/out
paidAt datetime Yes date & time at which amount is submitted in the drawer
paymentTypeId string Yes ID for the payment type
busiDate date Yes date used for submitting paidIn/out
lastModifiedAt datetime Yes Last time the check was updated
paidInOutID integer Yes Amount submitted into drawer
employeeID string Yes employee ID for paidIn/Out
tip decimal(2)   total tip submitted by the employee

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 integer Yes Total amount deposited in the cash deposit/drawer
busidate datetime Date used for submitting deposit
lastModifiedAt datetime Yes Last time the cash drawer amount was updated
depositedAt integer Yes Amount submitted into drawer
employeeID string Yes employee ID for cash deposit
Sample Request
      
{
"version": "1.0",
"deposits": [
{
  "id": 73309,
  "amount": 1196,
  "busiDate": "2018-04-10",
  "lastModifiedAt": "2007-03-28T00:00:00",
  "depositedAt": "2007-03-28T00:00:00",
  "employeeID": 4018
},
{
  "id": 73312,
  "amount": 166,
  "busiDate": "2018-04-10",
  "lastModifiedAt": "2007-03-28T00:00:00",
  "depositedAt": "2007-03-28T00:00:00",
  "employeeID": 4018
}
]
}
        
        

Business management has never been easier. Try any business app free.