Methods:

  • /api/v1/gifts/offer/
  • /api/v1/gifts/offer/available/
  • /api/v1/ecommerce/gifts/commit-transaction - confirmation of awarding the gift
  • /api/v2/gifts/coupons/status/ - coupon status
  • /api/v2/gifts/coupons/delete/ - coupon deletion
  • /api/v2/gifts/manage/categories/ - gift categories list
  • /api/v2/gifts/manage/create/ - gift creation
  • /api/v2/gifts/manage/edit/ - gift editing
  • /api/v2/gifts/list/ - gifts list
  • /api/v2/gifts/offer/ -
  • /api/v2/gifts/purchases/delete/ - canceling a gift
  • /api/v2/gifts/purchases/edit/ - editing of the gift that has been given away
  • /api/v2/gifts/purchases/new/ - awarding the gift
  • /api/v2/gifts/samples/ - the list of standard SailPlay's gifts

Confirmation of Awarding the Gift

Request Example

http://sailplay.net/api/v1/ecommerce/gifts/commit-transaction/?token=7ce324861c4a5de5bfe931c04d96073f9b72bfec&store_department_id=122&gift_public_key=09kdhh472idgh785920kfa

 Response Format

{
"status": "ok",
"purchase_gift": {
"id": 166,                   //transaction id
"already_completed": false,  //has the transaction been processed
"gift": 20,                  //gift id in SailPlay.ru's system
"gift_sku": "123",           //gift id in the partner's system
"purchase_date": "2013-03-26T10:18:41",       
"complete_date": "2013-03-26T10:19:04.118",
"points_delta": 800,
"is_completed": true,
"user": "79000000000"
}
}

/api/v2/gifts/coupons/status/ - coupon status

Method's Use

To receive information on the coupon status use the method

/api/v2/gifts/coupons/status.

Request Example

sailplay.net/api/v2/gifts/coupons/status/?store_department_id=15&token=a81f9aaa212fa92a4ea2d8f05f350995002f761d08b0&coupon_number=adsf332hkak

Response Example

{
"coupon":
{
"receipt_date": null,
"is_confirmed": false,
"number": "adsf332hkak",
"points": 400,
"confirm_date": null,
"is_purchased": false
"id" : 9293212929

},
"status": "ok",
"user":
{
"phone": null,
"origin_user_id": null,
"id": null
}
}

 

The following variables are used in the response:

receipt_date - date and time when a coupon has been received by the user
is_confirmed - it is used to confirm that your system accounts for the coupon. Methods for this parameter are described below.

 

To work with the field is_confirmed use the same request, adding the following parameter

action=<confirm | confirm_cancel>

/api/v2/gifts/coupons/delete - Delete the coupon

Method is used to delete particular coupon numbers. It is possible to delete only not redeemed certificates.

Request parameters

Is the parameter mandatory? Parameter Parameter description Data type Example
yes token see here
see the request example
token=qx6s4gsdvsdhsdsd
yes store_department_id see here
integer
store_department_id=345 
yes coupon_id Internal coupon identifier integer
1223331

Request example

sailplay.net/api/v2/gifts/coupons/delete/?store_department_id=345&token=qx6s4gsdvsdhsdsd&coupon_id=180841

Server response

Parameter Parameter description Data type Example
status

Request status:

ok - if the request is successful, error - if there is an error

JSON String
"status":"ok"

Server respose example

{
    "status": "ok"

Possible errors

This pair of store_deprtment_id and token are incorrect or missing in the system.

{
    "status": "error",
    "message": "Permission denied. Provide auth token and store_department_id"
}

Coupon not found

{
    "status": "error",
    "message": "Coupon not found"
}

Coupon is already redeemed by a customer and can't be deleted

{
    "status": "error",
    "message": "Coupon is already redeemed"
}

 

/api/v2/gifts/manage/categories/ - gift categories list

Method's Use

Each gift should be assigned to a particular category. The gift category is set when the gift is created in your account on the website SailPlay.ru or via API. 

This method returns the list of all categories.

 

Request Parameters

ПIs the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here

 Server Response

Parameter Name Parameter Description
status  

array

categories

 Array of objects with two fields: id, name


Request Example

http://sailplay.net/api/v2/gifts/manage/categories/?token=45d1a2c8777532f140dfbd42706a5382540c8cdb&store_department_id=131

 

Server Responses Examples

{
status: "ok",
categories:
[
{
id: 1,
name: "Clothing and shoes"
},
{
id: 2,
name: "Sports accessories and goods"
}
]

/api/v2/gifts/manage/create/ - gift creation

Method's Use

Use this method for automated creation of gifts using SailPlay API. 

NOTE: All parameters must be submitted in the body of the request, excpept for the token and store_department_id

Parameters

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
yes name  Gift name. It will be displayed in the popup on the main page and on the page of the specific gift. 
yes description   Gift description text It will be displayed in the popup on the page of the specific gift.
yes enabled  Checkbox "Is the gift active?". If it is equal to "1" then the gift will be available after its creation, any other value would specify the gift as unavailable.
yes points  Gift cost in points.
yes pic  Gift's cost in points. This image will be used in the popup and in your account. It has to be square. It will be automatically scaled to 250x250
yes pic_full  Gift image. This image will not be processed automatically and will be returned in the unmodified state. There are no requirements for aspect ratio.
no quantity  The number of gifts (if this parameter is not submitted, the number of gifts is unlimited, if the parameter is submitted, then there will be a specified number of gifts available).
no category  Gift category
no type  Gift type (if it is submitted it should have the value “coupon”).
no Coupons  Coupons numbers separated by commas. 
no sku  Gift ID in your system (see more here)
no partner_url  Gift page URL on your website (if there is any). It will be used when generating links to share by users. If the value for this parameter is empty, your website URL will be used, if it is also empty, the gift page on the SailPlay website will be used.
no help_text  The text that will be displayed to the user in the popup after s(he) receives the gift (see more  here).
no share_msg  The text that will be provided when users share information in social networks. You can find information about variables that can be used in your account on SailPlay or by contacting support.
no sms_msg  The text message that will be sent to the user after s(he) receives the gift. You can find information about variables that can be used in your account on SailPlay or by contacting support.

 

Server Response

All submitted parameters will be returned in a form of a JSON-array.

Important!

Parameters are validated against the type when the gift is created. Additionally, the following aspects are checked:

  1. the gift's image has to be square
  2. text length limits (if it is allowed to use variables in the text and they have been used, the length will be counted from the end message)

 

/api/v2/gifts/manage/edit/ - gift editing

Method's Use

This method is used for editing of a particular gift, i.e. changing the gift's status to inactive (equivalent to deleting the gift) and adding new numbers for coupons.

Method's Description

To edit gifts the following method is used

/api/v2/gifts/manage/edit

In terms of the request/response structure and submitted parameters it is like the method for creation of the gift but it has the following differences:

  1. when editing the gift you should be sure to submit the parameter gift_id - Gift ID in the query string

  2. you should only submit the parameters that you change (or all parameters but then all of them will be updated)

  3. you can't change the gift type (non-coupon to coupon)

  4. if the gift type is a coupon, and coupons parameters are submitted, all new unique coupons will be added to the list of previous coupons

/api/v2/gifts/list/ - receiving gifts list

Method's Use

The method allows receiving the list of all active gifts.

Request Parameters

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here

 Server Response

Parameter Name Parameter Description
status  

array

gifts

 Array of objects with gifts description.


Request Example

http://sailplay.net/api/v1/gifts/list/?token=c5c7c184b656d1166a2d512d19a945ae2a263858&store_department_id=441

Server Responses Examples

{
"gifts": [
{
"sku": "even1",
"update_date": "2014-02-21T10:41:11",
"name": "gifts",
"pic": "gifts/gift/b7fbeb7581fe4bafb408362b9d0c53d4.jpg",
"pic_full":"https://d3vr33qml1umu3.cloudfront.net/media/gifts/gift/b3a1a4faf2ebbaff7094a10e.jpg",
"points": 100,
"id": 583,
"description": "A great gift for your loyalty!"
}
],
"status": "ok",
"media_url": "//d3257v5wstjx8h.cloudfront.net/media/"
}

Where:

sku - gift ID in the partner's system
update_date - last update date
name - gift name
pic - gift image URL
pic_full - link to the alternative image of the gift in the original size
points - gift cost in points
id - gift ID in SailPlay's system
description - gift description
media_url - prefix of the link to the gift image

 

/api/v2/gifts/purchases/new/ - awarding the gift

Method's Use

You can use this method for automated awarding of the gifts.

Parameters

[mandatory parameter] token
[mandatory parameter] store_department_id
[mandatory parameter] user_phone or origin_user_id
[mandatory parameter] gift_id or sku_id
[not a mandatory parameter] order_num - number of the order with the gift. If the gift has been awarded for this order, the error will be returned.

 

Server Response

sku  - SKU of the awarded gift
status - transaction status
gift_id - gift ID in the SailPlay's system
user
phone
origin_user_id
order_num
points_delta - written-off points



Request Example

http://sailplay.net/api/v2/gifts/purchases/new/?store_department_id=37&token=0a5f9516698a3c9c2d34394fa8da9474307193c8&user_phone=19236054672&sku=U12312

Server Responses Examples


{
"sku": "U12312",
"status": "ok",
"gift_id": 11,
"user": {
"phone": "79000000000",
"origin_user_id": "asdf23heiuhi2lhiuehiu23eh23ihi2e23e23"
},
"order_num": null,
"points_delta": 100
}