Webinars
Events
Integrations
Learn
Contact Us
Sign Up

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

  {
    "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
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 decimal(2) 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 decimal(2)
Sample Request

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

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

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

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

    {
      "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
Sample Request
      
{
"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"
}
]
}
Attend Webinar
Schedule a Demo
Contact Us
SCHEDULE A DEMO