Voucher API Overview:
It is possible to integrate the TouchOffice Web Voucher system with a 3rd party solution. This enables 3rd party system to:
View voucher details
Create new vouchers
Update existing vouchers
Delete vouchers
Vouchers API:
Method: GET
Description: Returns an array of vouchers with their details
Parameters:
TAK String(30) the terminal access key
site Int(11) the site ID of the till
number Varchar(50) filter by voucher number (optional)
type Int(11) filter by type - e.g return all discount vouchers (optional)
limit Int(11) number of results - used for pagination (optional)
offset Int(11) start from row - used for pagination (optional)
active Int(4) filter by active/inactive - 1 (active) or 0 (inactive) (optional)
Returns: An array of vouchers
Sample request:
https://api.touchoffice.net/vouchers?TAK=XXXXXXXXXX&site=1&type=1
Sample response:
{ "vouchers": [ { "id": 2, "site": 0, "number": "XMSNWVPZRG", "type": 1, "name": "£10 Gift Voucher", "desc": "10 lots of £10 vouchers", "startdate": "2016-12-02 01:00:00", "enddate": "2017-12-02 12:36:00", "value": 1000, "flag": 0, "maxuses": 0, "uses": 3, "used_amount": 1000, "minsalevalue": null, "group": null, "ifgroup": null, "dept": null, "ifdept": null, "plu": null, "ifplu": "0", "active": true }, { "id": 3, "site": 0, "number": "OGWNFHUSFK", "type": 1, "name": "£10 Gift Voucher", "desc": "10 lots of £10 vouchers", "startdate": "2016-12-02 00:00:00", "enddate": "2017-12-02 00:00:00", "value": 1000, "flag": 0, "maxuses": 0, "uses": 3, "used_amount": 3000, "minsalevalue": null, "group": null, "ifgroup": null, "dept": null, "ifdept": null, "plu": null, "ifplu": "0", "active": true } ], "status": 1 }
Sample request:
https://api.touchoffice.net/vouchers/ABCDEF123?TAK=XXXXXXXXXX
Sample response:
{ "vouchers": [ { "id": 146, "site": 0, "number": "ABCDEF123", "type": 1, "name": "Test", "desc": "Test Desc", "startdate": "2016-12-08 00:00:00", "enddate": "2017-12-08 00:00:00", "value": 1000000, "flag": 0, "maxuses": 0, "uses": 40, "used_amount": 106623, "minsalevalue": null, "group": null, "ifgroup": null, "dept": null, "ifdept": null, "plu": null, "ifplu": null, "active": true } ], "status": 1 }
Method: POST
Description: Called to create a new voucher
Parameters:
TAK String(30) the terminal access key
site Int(11) a site ID for the voucher, 0 if can be used at all sites (optional)
number Varchar(50) the voucher number (optional) - Auto generated if not provided
type Int(11) 1 = Gift Card, 2 = Percentage Discount
name Varchar(20) voucher name E.g "Chirstmas Promo" (optional)
desc Varchar(50) voucher description E.g "10% off all food" (optional)
value Decimal(18,2) starting value of voucher (optional)
startdate Datetime a date from which the voucher is valid from (optional)
enddate Datetime an expiry date for the voucher (optional)
active Boolean can the voucher be used?
flag Int(11) a hex value for the flags. Partial Redeem.
maxuses Int(11) maximum number of sales the voucher can be used against (optional)
minsalevalue Decimal(18,2) the minimum sale value that the voucher can be used against (optional)
dept Varchar(50) Comma separated list of department numbers which the voucher can be used with (optional)
ifdept Varchar(50) Comma separated list of department numbers which the sale has to contain (optional)
group Varchar(50) Comma separated list of group numbers which the voucher can be used with (optional)
ifgroup Varchar(50) Comma separated list of group numbers which the sale has to contain (optional)
plu Varchar(50) Comma separated list of plu numbers which the voucher can be used with (optional)
ifplu Varchar(50) Comma separated list of plu numbers which the sale has to contain (optional)
Returns: The full voucher details that has been created
Sample request:
https://api.touchoffice.net/vouchers?TAK=XXXXXXXXXX
Request body:
[ { "site": 0, "number": "ABCDEF123", "type": 1, "name": "£15 off voucher", "desc": "Test Desc", "startdate": "2016-12-08 00:00:00", "enddate": "2017-12-08 00:00:00", "value": 1500, "flag": 0, "maxuses": 0, "minsalevalue": null, "group": null, "ifgroup": null, "dept": null, "ifdept": null, "plu": null, "ifplu": null, "active": true } ]
Sample response:
{ "vouchers": [ { "id": 146, "site": 0, "number": "ABCDEF123", "type": 1, "name": "£15 off voucher", "desc": "Test Desc", "startdate": "2016-12-08 00:00:00", "enddate": "2017-12-08 00:00:00", "value": 1500, "flag": 0, "maxuses": 0, "uses": 0, "used_amount": 0, "minsalevalue": null, "group": null, "ifgroup": null, "dept": null, "ifdept": null, "plu": null, "ifplu": null, "active": true } ], "status": 1 }
Method: PATCH
Description: Called to update an existing voucher's details
Parameters:
TAK String(30) the terminal access key
number Varchar(50) the voucher number to update
Returns: The full voucher details that has been created
Sample request:
https://api.touchoffice.net/vouchers/ABCDEF123?TAK=XXXXXXXXXX
Request body:
{ "name": "£15 off voucher" }
Sample response:
{ "voucher": { "id": 146, "site": 0, "number": "ABCDEF123", "type": 1, "name": "£15 off voucher", "desc": "Test Desc", "startdate": "2016-12-08 00:00:00", "enddate": "2017-12-08 00:00:00", "value": 1500, "flag": 0, "maxuses": 0, "uses": 0, "used_amount": 0, "minsalevalue": null, "group": null, "ifgroup": null, "dept": null, "ifdept": null, "plu": null, "ifplu": null, "active": true }, "status": 1 }
Method: DELETE
Description: Called to delete a voucher
Parameters:
TAK String(30) the terminal access key
number Varchar(50) the voucher number to delete
Returns: The voucher number of the deleted voucher
Sample request:
https://api.touchoffice.net/vouchers/ABCDEF123?TAK=XXXXXXXXXX
Sample response:
{ "voucher_number": "ABCDEF123", "status": 1 }
Method: POST
Description: Logs the use of a voucher with a transaction
Parameters:
TAK String(30) the terminal access key
site Int(11) the site ID of the till
saleID BigInt(30) ID of sale
voucherNumber Varchar(50) the voucher number used
datetime DateTime the datetime of the transaction
amount Int(11) the value of the transaction
Returns:
Sample request:
https://api.touchoffice.net/voucher_transactions?TAK=XXXXXXXXXX
Request body:
{ "site": 1, "saleID": 123456789023413153, "voucherNumber": "ABCDEF123", "datetime": "2018-04-23 12:31:00", "amount": 1000 }
Sample response:
{ "status": 1 }
Voucher Barcode Format:
The barcode consists of 3 sections:
A three Character Prefix: VCF or VCT
VCF is used to identify an amount Gift Card ("type": 1)
VCT is used to identify a discount percentage ("type": 2)
The Voucher Code as generated by TOW
A Suffix Character: *
Please find examples below:
The barcode for a Gift Card with the code ALGWTAVSKI would be:
VCFALGWTAVSKI*
The barcode for Discount Voucher with the code XIFECLAHDJ would be:
VCTXIFECLAHDJ*
Use code 128 format to create the barcodes.
Gift Card Magnetic Card Encoding:
If you want to encode a magnetic stripe card eg Gift Card use:
Track 1 cards.
Start Sentinel: %
End Sentinel: ?
Example: %VCFXXXXXXXXXX*?