O2O

Create Vouchers Flow (Synchronous)

Create Vouchers Flow

Get Voucher Serial Numbers (Partner提供)

Get voucher serial numbers by order information - Yahoo call partner

URI

[POST]  /v1/vouchers/serialNumbers?...
{
      "storeId":"top1",
      "transactionId":"6021970",
      "orderId":"YM1505120000043",
      "productId":"p12345679",
      "specId":"1",
      "customizedProductId":"p12345679",
      "quantity":3,
      "orderItems":[
          {
            "orderItemId":"YS1505120000043",
            "price":70,
            "originalPrice":100
          },
          {
            "orderItemId":"YS1505120000044",
            "price":70,
            "originalPrice":100
          },
          {
            "orderItemId":"YS1505120000045",
            "price":70,
            "originalPrice":100
          }
        ]
}

Response - Success

// HTTP/1.1 200 Ok
{
          "vouchers":[
            {
              "orderItemId":"YS1505120000043",
              "serialNumber":"00000000001"
            },
            {
              "orderItemId":"YS1505120000044",
              "serialNumber":"00000000002"
            },
            {
              "orderItemId":"YS1505120000045",
              "serialNumber":"00000000003"

            }
          ]
}

Cancel Voucher Serial Numbers (Partner提供)

cancel voucher serial numbers by order information - Yahoo call partner

URI

[POST]  /v1/vouchers/serialNumbers?...
{
      "storeId":"top1",
      "transactionId":"6021970",
      "orderId":"YM1505120000043",
      "productId":"p12345679",
      "specId":"1",
      "customizedProductId":"p12345679",
      "quantity":3,
      "orderItems":[
          {
            "orderItemId":"YS1505120000043",
            "price":100
          },
          {
            "orderItemId":"YS1505120000044",
            "price":100
          },
          {
            "orderItemId":"YS1505120000045",
            "price":100
          }
        ]
}

Response - Success

// HTTP/1.1 200 Ok
{
          "vouchers":[
            {
              "orderItemId":"YS1505120000043",
              "serialNumber":"00000000001"
            },
            {
              "orderItemId":"YS1505120000044",
              "serialNumber":"00000000002"
            },
            {
              "orderItemId":"YS1505120000045",
              "serialNumber":"00000000003"

            }
          ]
}

Redeem Voucher (Yahoo提供)

redeem a voucher - Partner call Yahoo

URI

[POST]  https://tw.ews.mall.yahooapis.com/stauth2/v1/vouchers/redeem?...
{
  "vouchers":[
    {
      "orderId":"YM123239423",
      "orderItemId":"YS1505130000028",   //not required
      "serialNumber":"1234567890",
      "redeemAt":"user input"
    }]
}

Response - Success

// HTTP/1.1 200 Ok
{
  "vouchers": [
   {
     "orderId": "YM1505130000018",
     "orderItemId": "YS1505130000028",
     "status": "USED",
     "storeId": "tw_auc_user1",
     "statusAppliedTime": 1433315752
   }]
}

Response - Error

// HTTP/1.1 400 Bad Request
{
  "error": {
    "code": 12001,
    "message": "Redeem Failed."
  }
}

Query List of Vouchers (Yahoo提供）

retrieve a list of vouchers - Partner call Yahoo

URI

[GET]       https://tw.ews.mall.yahooapis.com/stauth2/v1/vouchers?...

PARAMETERS

Parameter	Type	Format	Description
voucherId	integer	int	voucher id
serialNumber	string	utf8_length(20)	serial number of the purchased voucher
orderId	string	utf8_length(24)	orderId (YM)
orderItemId	string	utf8_length(24)	orderItemId (YS)
productId	string	utf8_length(24)	product id
specId	string	utf8_length(24)	spec id
createdTimeStart	date	yyyy/mm/dd h:m:s	search on created date
createdTimeEnd	date	yyyy/mm/dd h:m:s	search on created date
expiredTimeStart	date	yyyy/mm/dd h:m:s	search on expiry date
expiredTimeEnd	date	yyyy/mm/dd h:m:s	search on expiry date
sort	string	createdTime	expiredTime record’s ordering, add “-” in front for descending order default: -createDate
status	string	utf8_length(30)	ex: status=UNUSED,USED

RETURN

Collection of Voucher Object that match the given filter criteria upon success. Otherwise, an Error Object is returned.

Sample Request

GET  /stauth2/v1/vouchers?orderId=YM1505130000018

Response - Success

// HTTP/1.1 200 Ok
{
  "total": 1,
  "vouchers": [
    {
      "voucherId": 18446744073709551615,
      "productId": "p093568055654",
      "specId": "1",
      "price": 200,
      "serialNumber": "615089255",
      "orderId": "YM2015050500005",
      "orderItemId": "YS2015050500005",
      "title": "I’m title",
      "redemptionDesc": "I’m description",
      "buyerDetails":{
          "name":"\u694a\u4e8e\u6167",
          "phone":"0912063990"
      },
      "executedBy":"system:VoucherOrderConsumerApp",
      "status":"UNUSED",
     "refundType":"NOEXPIRES",
     "redemptionType":"EXPIRES",
      "statusAppliedTime": "2015-01-05T07:20:00Z",
      "deliveredTime": "2015-01-05T07:20:00Z",
      "expireTime": "2015-01-05T07:20:00Z",
      "startTime": "2015-01-05T07:20:00Z"
    }]
}

Response - Error

// HTTP/1.1 404 Not Found
{
  "error": {
    "code": 11001,
    "message": "No Vouchers are found."
  }
}

Voucher Status Changed Notification （Partner 提供)

notify status changed vouchers - Yahoo call partner

URI

[POST]  /v1/vouchers/notification?...
{
  "vouchers":[
    {
     "storeId":"top1",
     "voucherId":"123239423",
     "orderId": "YM1505130000018",
     "orderItemId": "YS1505130000028",
     "status":"USED",
     "statusAppliedTime":"2015-01-05T07:20:00Z",
     "executedBy":"system:VoucherOrderConsumerApp"
    },
    {
     "storeId":"top1",
     "voucherId":"123239424",
     "orderId": "YM1505130000018",
     "orderItemId": "YS1505130000029",
     "status":"USED",
     "statusAppliedTime":"2015-01-05T07:20:00Z",
     "executedBy":"system:VoucherOrderConsumerApp"
    }
  ]
}

Voucher Status Definition

Name	Description
UNUSED	The voucher is now available for redemption. However, it is possible that the redemption might fail if the voucher has expired.
USED	The voucher has been redeemed.
REFUNDPENDING	The voucher owner has initiated a refund of the voucher. This state is necessary because some sellers take a few days to enter vouchers that have been redeemed. We wait a few days to avoid refunding a voucher that has already been redeemed.
REFUNDED	The voucher has been refunded.
CANCELLED	The voucher has not been redeemed and can no longer be redeemed.

Call Yahoo api 認證方式

TimeStamp, ApiKey 請直接帶在URI後面

作signature所需data的規則是

URI＋JSON Request body

Example

signature的data content為

/stauth2/v1/vouchers/redeem?TimeStamp=1433924096&ApiKey=247c4a4244eaf481d39ed035xxxxxx{"vouchers":[{"orderId":"YM123239423","orderItemId":"YS1505130000028","serialNumber":"1234567890","redeemAt":"user input"}]}

uri之後就直接接json

做出來的signature請帶在HEADER

欄位名稱為X-STOREAUTH-SIG

X-STOREAUTH-SIG:xxxxxxxxx

Test Information

API Host	https://tw.ews.mall.yahooapis.com/
API Key	247c4a4244eaf481d39ed035xxxxxx (請帶提供之api key)
Shared Secret	OGEzMDc3NDg1OTZmMjMyMxxxxxxxx (sample only)
orderId	YM1505070079148
SN	YTWPS00001ABCDE