52API VOUCHER

In general, 52ViKING operates with two types of vouchers (also referred to as coupons in the API and in 52ViKING):

• Generic vouchers, which can be used several times and distributed in various ways to a large amount of people. Generic vouchers trigger a certain discount, and the vouchers themselves carry no value.

• Unique vouchers, which have a value attached and can only be used once. The value can be either a fixed discount amount or a percentage. For example, a comeback voucher giving 5 euros off the next purchase above a certain amount.

Both voucher types can be printed as barcodes. It's also possible to map the barcodes to a more user-friendly short code for entering the voucher on a webshop.   

In order to use a 52ViKING voucher from a webshop, a connection needs to be established between the web application and the 52ViKING voucher server. This connection runs via the 52ViKING omnichannel controller (OC).

The API methods exposed in this API are general web methods as well as unique voucher methods that are only relevant for unique vouchers because generic vouchers can be used multiple times and don't contain a value.

Voucher API uses these HTTP status codes as return codes:

• 200 OK

  XML tag status that shows if request has gone well or not.

  Can have the values OK or NOK.

• 400 Bad Request

  Returned if request is wrong or if request is missing information.

• 401 Unauthorized

  52ViKING-KEY missing or incorrect.

• 404 Not Found

  Resource not available.

• 500 Internal Server Error

  Unknown error or configuration on the server.    

• UTF-8

When the API itself refers to coupons in the following, it means vouchers.

Vouchers for web use

To make it easy to enter vouchers on web stores, 52ViKING provides a mapping table that shortens the amount of characters to type.

Example: Instead of having to enter the unique voucher number 9891001123400000001794, the customer can enter a short name, like PFMQWZ.

The mapping table is also used for validating if a voucher is correctly entered by the user. Note, however, that even if a voucher has been entered correctly, it may not necessarily trigger a discount if selling conditions aren't met.

Voucher validation

Use to check if a voucher is valid and optionally its value if it’s a unique voucher.

URI	/Coupon/{CouponNumber|CouponName}
Method	GET
Example	/Coupon/9891001123400000001794 /Coupon/JUL2018
Reply body	Tag elements
	Name	Description	Format	Occurrences
	CouponStatus	Root tag		1
	Coupon	Voucher number	10-22 digits	1
	CouponName	Mapping voucher name. Name will only be returned if it exists.	string	0-1
	Value	The value of the voucher (amount/percentage) Only returned for unique coupons.	1-8-digit number with 2 decimals	0-1
	Type	Generic/unique	string	1
	DiscountCouponId	Discount group ID for Basket API	3 digits	1
Returns	200 OK & XML reply

XML reply example:

Copy

1
2
3
4
5
6
7
8
<?xml version='1.0' encoding='UTF-8'?>
<Coupon>
 <Coupon>1001123400000001794</Coupon>
 <CouponName>JUL2018</CouponName>
 <Value>25</Value>
 <Type>unique</Type>
 <DiscountCouponId>123</DiscountCouponId>
</Coupon>

The function may return 400 if CouponName doesn't comply with the allowed format. The format is configurable, defaulting to between 6 and 20 characters containing capital letters and digits.

If the voucher is unique, a value is returned, otherwise it’s a generic voucher. For unique vouchers that are reserved or completed, the value field will be empty.

CouponNumber can be passed with or without the 989 prefix. The returned Coupon element is always without the 989 prefix.

Link between barcode and short name

Use to create a link in the mapping table between a voucher barcode and an easy-to-enter short name.

URI	/Coupon/{CouponNumber}/link/{CouponName}
Method	PUT
Example	/Coupon/9891001123400000001794/link/PMQZXJ
Returns	200 OK

The voucher ID can either be a unique or a generic voucher.

Unique vouchers

Redemption of voucher

Use to check if a voucher is valid, and to check its value.

URI	/CouponValue?
Method	GET
Querystring	Coupon= Voucher number Store= Store ID (optional)
Example	/CouponValue?Coupon= 9891001123400000001794
Returns	200 OK & XML reply

XML reply example:

Copy

1
2
3
4
5
6
<?xml version='1.0' encoding='ISO-8859-1'?>
<CouponValue>
 <status>OK</status>
 <Coupon>1001123400000001794</Coupon>
 <Value>25</Value>
</CouponValue>

Unique vouchers are accepted both for 22 digits and 19 digits. When using 22 digits, the prefix must be 989. The returned voucher ID is only 19 digits.

The voucher isn't reserved, as that will be handled by the following call.

If the voucher isn't valid, the status NOK is returned.

To check if a voucher is valid and create a reservation:

URI	/CouponRedeem?
Method	GET
Querystring	Coupon= Voucher number Store= Store ID
Example	/CouponRedeem?Coupon= 9891001123400000001794
Returns	200 OK & XML reply

XML reply example:

Copy

1
2
3
4
5
6
<?xml version='1.0' encoding='ISO-8859-1'?>
<CouponRedeem>
 <status>OK</status>
 <Coupon>1001123400000001794</Coupon>
 <Value>25</Value>
</CouponRedeem>

CouponRedeem reserves the voucher, so it can't be used again (only valid for unique vouchers). This is relevant when a webshop has added the voucher to the basket, but not completed the transaction yet.

To cancel voucher reservation:

URI	/CouponCancel?
Method	GET
Querystring	Coupon= Voucher number Store= Store ID
Example	/CouponCancel?Coupon= 9891001123400000001794
Returns	200 OK & XML reply

XML reply example:

Copy

1
2
3
4
5
<?xml version='1.0' encoding='ISO-8859-1'?>
<CouponCancel>
 <status>OK</status>
 <Coupon>1001123400000001794</Coupon>
</CouponCancel>

CouponCancel will remove the reservation of a voucher so it can be used again.

To capture a voucher for use (can be reserved):

URI	/CouponComplete?
Method	GET
Querystring	Coupon= Voucher number Store= Store ID Amount = The amount the voucher gives in discount
Example	/CouponComplete?Coupon= 9891001123400000001794
Returns	200 OK & XML reply

XML reply example:

Copy

1
2
3
4
5
<?xml version='1.0' encoding='ISO-8859-1'?>
<CouponComplete>
 <status>OK</status>
 <Coupon>1001123400000001794</Coupon>
</CouponComplete>

CouponComplete should be used then the voucher is marked as used, that is when the order is shipped of completed.

Create vouchers

Use to create a number of vouchers and a link in the mapping table.

URI	/CouponsCreate
Method	POST
Example	/CouponsCreate
Request body	Name	Description	Format	Occurrences
	Tag-elements
	CreateCoupons	Roottag		1
	CouponId	CouponId as created in 52ViKING	3 digits	1
	NamePrefix	The prefix of the mapping name. A mapping will only be created if NamePrefix is provided.	string	0-1
	Value	The value of the voucher (amount/percentage)	1-8-digit number with 2 decimals	1
	Start	Start date of the voucher	YYYY-MM-DDThh:mm:ssTZD	1
	End	End date of the voucher	YYYY-MM-DDThh:mm:ssTZD	1
	Quantity	Number of vouchers to be created	1..5000	1
Returns	200 OK & XML reply
Reply body	Name	Description	Format	Occurrences
	Tag-elements
	Coupons	Root tag		1
	Coupon	Element for Coupons
	Barcode	The full barcode of the voucher	22 digits	1
	Name	The mapping name of the voucher NamePrefix+6-digit random number Only present if NamePrefix was provided in the request	string	0-1

 

Issue of unique discount vouchers

Use to generate unique vouchers that may, for example, be used in conjunction with e-mail campaigns.

URI	/IssueCoupons?
Method	GET
Querystring	Type= Discount voucher n type (3 digits) used to link with discount group Qty= Number of vouchers to be issued Value= Amount or percentage depending on discount group Start= Valid from YYMMDD End= Valid until (including) YYMMDD. Must be larger or equal to Start.
Accept	text/xml application/json text/csv
Example	/IssueCoupons?Type=1&Qty=2&Value=10&Start=161001&End=161031
Returns	200 OK & XML reply

XML reply example:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?xml version='1.0' encoding='ISO-8859-1'?>
<IssueCoupons>
 <Coupon>
 <CouponId value='627'/>
 <Start value='161005'/>
 <Slut value='161010'/>
 <Value value='15'/>
 <CV2 value='921'/>
 <Barcode value='9891001000100000627921'/>
 </Coupon>
 <Coupon>
 <CouponId value='628'/>
 <Start value='161005'/>
 <Slut value='161010'/>
 <Value value='15'/>
 <CV2 value='525'/>
 <Barcode value='9891001000100000628525'/>
 </Coupon>
</IssuedCoupons>

Up to 5000 discount vouchers can be issued per request. Upon a completed successful request, the vouchers are created in the database and are ready for use (subject to start and end dates).

All fields are mandatory, otherwise HTTP status 400 is returned. 400 is also returned for invalid parameters.

Example of JSON output:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
 "IssuedCoupons": {
 "Coupon": [
 {
 "CouponId": 629,
 "Start": 161005,
 "Slut": 161010,
 "Value": 15,
 "CV2": 408,
 "Barcode": "9891001000100000629408"
 },
 {
 "CouponId": 630,
 "Start": 161005,
 "Slut": 161010,
 "Value": 15,
 "CV2": 528,
 "Barcode": "9891001000100000630528"
 }
 ]
 }
}

Example of CSV output:

Copy

1
2
Coupon,611,161005,161010,15,448,"9891001000100000611448"
Coupon,612,161005,161010,15,231,"9891001000100000612231"

 

Error codes

The Voucher API functions listed in the previous, except CreateCoupons, can return:

• OK – when successful

• NOK – when not successful, with the following supplementary error code text:

  • Unknown number

  • Already used

  • Coupon not active

  • Coupon expired

  • Unknown coupon

52ViKING uses two types of vouchers.

Type 0 - Generic voucher: These are typically used in advertising materials or handed out as part of marketing campaigns.

Type 1 - Unique voucher: These are typically created as comeback vouchers, and each one has a unique voucher number and a value.

Generic voucher barcode structure

• 2-digit flag code (=98: voucher)

• 1-digit marking for discount voucher (=9: 52ViKING discount voucher)

• 1-digit discount voucher type (0=generic)

• 5-digit (always 0)

• 3-digit discount voucher ID

• 1 check digit

In total 13 digits.

Unique voucher barcode structure

• 2-digit flag code (=98: voucher)

• 1-digit marking for discount voucher (=9: 52ViKING discount voucher)

• 1-digit discount voucher type (1=unique)

• 3-digit discount voucher ID

• 4-digit shop ID

• 8-digit discount voucher number

• 3-digit security code

In total 22 digits.