Skip to main content

Voucher API - 3rd Party Integration

Jonathan Hutchings avatar
Written by Jonathan Hutchings
Updated over 3 weeks ago

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:

  1. A three Character Prefix: VCF or VCT

    1. VCF is used to identify an amount Gift Card ("type": 1)

    2. VCT is used to identify a discount percentage ("type": 2)

  2. The Voucher Code as generated by TOW

  3. 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*?

Did this answer your question?