YIFTEE REWARDS DEVELOPER GUIDE

Size: px

Start display at page:

Download "YIFTEE REWARDS DEVELOPER GUIDE"

Rachel Sanders
5 years ago
Views:

1 YIFTEE REWARDS DEVELOPER GUIDE INTRODUCTION A reward is a pre- defined amount redeemable at a merchant(s). You can create any number of rewards from the Yiftee Enterprise Portal for your enterprise. A gift is an instances of a reward sent to a specific recipient via or SMS or Twitter or Facebook. Gifts can be created and delivered using the Yiftee Rewards API. You also have the option of just creating the gifts using the API but deliver the gifts yourself. There needs to be enough balance in the account when a gift is created. 1 P age Y iftee, Inc. v0.2

2 CREATE REWARDS 1. Log in to your Yiftee Enterprise Portal and click on Rewards in the menu on the left. 2 P age Y iftee, Inc. v0.2

3 2. Click on Add A Reward (the first time) or Create Reward (near the top left corner) 3 P age Y iftee, Inc. v0.2

4 3. Fill in the details. Click on Add A Gift to select merchant and amount. 4 P age Y iftee, Inc. v0.2

5 4. Review the reward details including the expiration period and the number of reminders to be sent to the gift recipient. Decide if you would like the gift to be exchangeable and donatable. 5 P age Y iftee, Inc. v0.2

6 5. Click on Create Reward to create the reward. 6 P age Y iftee, Inc. v0.2

7 6. If you click on the API JSON button you will see the JSON that should be posted to the Create Gift API (more details later). You will need the api_token, the api_secret and the reward_id from this screen. 7 P age Y iftee, Inc. v0.2

8 YIFTEE REWARDS API In this document, "client" refers to the party initiating the API calls. NOTES FOR TEST ENVIRONMENTS For developer testing purposes, please get the test server host name from Yiftee Developer Support and use it wherever you see <server> or in the following sections. For the test servers, DO NOT USE A REAL CREDIT CARD to deposit funds into the account. Use the following test credit card: card number CVC 111 expiration date 3/2018 street address zip Middlefield Road s will be sent both to gift senders and gift receipients. Therefore, when providing an address, please provide addresses where you can receive these s. CREATE GIFT Up to 50 gifts can be sent in each API call. If the number of gifts exceeds 50, the API call will not be processed. All gifts in a batch must be from the same sponsor. PROTOCOL HTTP Method URL POST <server>/v2/gift/give REQUEST PARAMETERS The POST parameter is a JSON string with the following name- value pairs: api_token required client api token (from the API JSON screen) api_secret required client api secret (from the API JSON screen) sponsor_api_token required sponsor api token (from the API JSON screen) sponsor_api_secret required sponsor api secret (from the API JSON screen) no_deliver required true if CLIENT (not Yiftee) will deliver gift. false if YIFTEE should deliver the gift using /sms in the per- gift info. gifts required array of gift_info (see below) 8 P age Y iftee, Inc. v0.2

9 gift_info reward_id required The reward_id generated by Yiftee to uniquely identify a reward (from the API JSON screen) audit_number required Client- supplied number to track this gift. You should include a unique audit number with each gift. Yiftee server will use this to reject duplicates so that if the same request is posted twice the second one will be ignored. recipient_name name of recipient if known recipient_phone optional phone number of gift recipient if known recipient_ optional address of gift recipient if known recipient_fb_id optional Facebook id of gift recipient if known recipient_twitter optional Twitter id of gift recipient if known RESPONSE The response is a JSON string with the following parameters: total Total cost of the gifts being purchased including Yiftee fees (in USD) account_balance Amount remaining in the sponsor account after purchasing all gifts in the batch invoice_id Yiftee invoice number to refer to this purchase transactions Array of transaction_detail for each gift. The recipient_gift_link can be forwarded to the gift recipient who can follow the hyperlink to retrieve the gift. transaction_detail audit_number recipient_details message price_paid sender_name message_print gift The audit_number sent by the client in the request JSON for each gift. This number can be used to retrieve the status of a gift in the Gift Status API. A hash with the following name- value pairs (depending on what is provided in the request JSON): name phone twitter facebook The message sent to the recipient to announce the gift The amount charged to the client for the gift (includes the Yiftee fees) The sender name as configured in the reward null A gift_info structure gift_info merchant_id merchant_name redeemable_at_copy amount status The Yiftee ID of the merchant where the gift can be redeemed The name of the merchant where the gift can be redeemed A text description of how/where to redeemed the gift The amount that can be redeemed by the recipient (= price_paid minus Yiftee fees) DELIVERED, VIEWED 9 P age Y iftee, Inc. v0.2

10 expiration_date The date when the gift will expire in %A %b %d format (e.g. "Tuesday Dec 06") expiration_date_utc The date when the gift will expire in UTC (e.g. " ") recipient_gift_link A URL where the recipient can retrieve the gift short_code A short code which is the unique part of the recipient_gift_link. This short_code can be used to query information about the gift in the future (see the Gift Info API). sender_gift_link A URL where the recipient can see the sender image_url A URL to an image of the gift EXAMPLES The following examples use the curl command to illustrate the effects of making API calls. You can launch the API calls from the programming environment of your choice. EXAMPLE 1 In this example two gifts are sent: one to Fred and one to Sam. The audit_number is something the client generates to uniquely identify each gift for tracking and debugging purposes. We want Yiftee to send the gifts so we set no_deliver to false (the JSON response is the same when no_deliver is true). Note that the curl command in the following example is a single command line. #!/bin/bash api_token=83595d6ce4896fea0a097f785e28f4d3224 api_secret=16685d1a7c48ecd0d21afbaa sponsor_api_token=83595d6ce4896fea0a097f785e28f4d3224 sponsor_api_secret=16685d1a7c48ecd0d21afbaa cd curl -X POST -H "Content-Type: application/json" -d '"api_token":"'$api_token'","api_secret":"'$api_secret'","sponsor_api_token":"'$spons or_api_token'","sponsor_api_secret":"'$sponsor_api_secret'","no_deliver":false,"gifts" :["reward_id":11,"audit_number":"1001","recipient_name":"sam","recipient_ ":"sam@ cohowinery.com""reward_id":1,"audit_number":"1002","recipient_name":"fred","recipie nt_twitter":"@fred"]' Response: "total": 44.0, "account_balance": 208.0, "invoice_id": 39430, "transactions": [ "audit_number": "1001", "recipient_details": "name": "Sam", " ": "sam@cohowinery.com", "phone": "", "twitter": "" "message": "Welcome to the Preferred Circle!", "price_paid": "22.0", "sender_name": "Steve Chan", "message_print": null, "gift": "merchant_id": , 10 P age Y iftee, Inc. v0.2

11 ] "merchant_name": "Fav Cafe", "redeemable_at_copy": "565 Middlefield Road, Menlo Park, California 94025", "amount": "20.00", "status": "DELIVERED", "expiration_date": "Tuesday Dec 06", "expiration_date_utc": " ", "recipient_gift_link": " "short_code": "8Kg903T", "sender_gift_link": " "image_url": " "bounce_sms": null, "bounce_ ": null, "bounce_facebook": null, "bounce_twitter": null "audit_number": "1002", "recipient_details": "name": "Fred", " ": "", "phone": "", "twitter": "message": "Welcome to the Preferred Circle!", "price_paid": "22.0", "sender_name": "Steve Chan", "message_print": null, "gift": "merchant_id": , "merchant_name": "Fav Cafe", "redeemable_at_copy": "565 Middlefield Road, Menlo Park, California 94025", "amount": "20.00", "status": "DELIVERED", "expiration_date": "Tuesday Dec 06", "expiration_date_utc": " ", "recipient_gift_link": " "short_code": "HMytFfV", "sender_gift_link": " "image_url": " "bounce_sms": null, "bounce_ ": null, "bounce_facebook": null, "bounce_twitter": null EXAMPLE 2 If you just want to send a single gift you can omit the 'gifts' array in the JSON. The server will treat a single entry just like an array of one element. curl -X POST -H "Content-Type: application/json" -d '"api_token":"'$api_token'","api_secret":"'$api_secret'","sponsor_api_token":"'$spons or_api_token'","sponsor_api_secret":"'$sponsor_api_secret'","no_deliver":false,"reward _id":"11","audit_number":"1005","recipient_name":"sam","recipient_ ":"sam@cohowine ry.com"' 11 P age Y iftee, Inc. v0.2

12 Response "total": 22.0, "account_balance": 142.0, "invoice_id": 39432, "transactions": [ "audit_number": "1005", "recipient_details": "name": "Sam", " ": "sam@cohowinery.com", "phone": "", "twitter": "" "message": "Welcome to the Preferred Circle!", "price_paid": "22.0", "sender_name": "Steve Chan", "message_print": null, "gift": "merchant_id": , "merchant_name": "Fav Cafe", "redeemable_at_copy": "565 Middlefield Road, Menlo Park, California 94025", "amount": "20.00", "status": "DELIVERED", "expiration_date": "Tuesday Dec 06", "expiration_date_utc": " ", "recipient_gift_link": " "short_code": "d2lwcqy", "sender_gift_link": " "image_url": " "bounce_sms": null, "bounce_ ": null, "bounce_facebook": null, "bounce_twitter": null ] NOTES The audit_number, if provided, must be unique among all gifts sent. If not provided, the Yiftee server will generate a unique audit_number for you, but it will be a Yiftee internal number, not your own. If you try to create a gift with a duplicate audit_number, it will be ignored and no gift will be sent. If you provide a Twitter hashtag in recipient_twitter, the response will contain a property recipient_gift_link_public. This link will take the recipient to a public gift page that forces the user to log in with their Twitter username before redeeming the gift. In order to create and send gifts, it is necessary to fund the sender's account. This may be done by logging in to the sender's account and depositing funds in the normal way. GIFT STATUS Pass in an audit_number to retrieve the current status of a gift. 12 P age Y iftee, Inc. v0.2

13 PROTOCOL HTTP method URL GET <server>/v2/gift/status REQUEST PARAMETERS The following parameters are passed in the URL. api_token required client api token api_secret required client api secret audit_number required An audit_number previously used to create a gift RESPONSE receipt A transaction_detail structure (see the Create Gift API response section) EXAMPLE api_token=1d65d4dfbd7933c2e746f805877cf api_secret=a4c01cb4d9646fda206495e05f8cfc4c24189 curl -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET " t_number=3001" Response "receipt": "audit_number": "3021", "recipient_details": "name": "Sam", " ": " sam@cohowinery.com ", "phone": "", "twitter": "" "message": "Welcome to the Preferred Circle!", "price_paid": "22.0", "sender_name": "Steve Chan", "message_print": null, "gift": "merchant_id": , "merchant_name": "Fav Cafe", "redeemable_at_copy": "565 Middlefield Road, Menlo Park, California 94025", "amount": "20.00", "status": "DELIVERED", "expiration_date": "Tuesday Dec 06", "expiration_date_utc": " ", "recipient_gift_link": " "short_code": "d2lwcqy", "sender_gift_link": " "image_url": " "bounce_sms": null, "bounce_ ": null, "bounce_facebook": null, 13 P age Y iftee, Inc. v0.2

14 "bounce_twitter": null LIST REWARDS Retrieve a list of all rewards defined. PROTOCOL HTTP method URL GET <server>/v2/gift/enumerate_rewards REQUEST PARAMETERS The following parameters are passed in the URL. api_token required client api token api_secret required client api secret RESPONSE The response is a JSON string with the following parameters reward_list s Array of reward_info reward_info id name microgift_id image_url merchant sender_name message exchangeable donatable s reward_id (generated by Yiftee for each reward) reward name Yiftee internal ID A URL of the gift image merchant name reward sender name reward message to be send to the gift recipient if the gift can be exchanged for gifts at other merchants if the gift can be donated EXAMPLE api_token=1d65d4dfbd7933c2e746f805877cf api_secret=a4c01cb4d9646fda206495e05f8cfc4c24189 curl -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET " secret" 14 P age Y iftee, Inc. v0.2

15 Response "rewards": [ "id": 11, "name": "Preferred Circle Welcom Gift", "microgift_id": 42472, "image_url": " "price": "20.0", "merchant": "Fav Cafe", "sender_name": "Steve Chan", "message": "Welcome to the Preferred Circle!", "exchangeable": false, "donatable": false, "expiration_days": 365, "gift_reminders": 12 "id": 12, "name": "Golden Circle Welcom Gift", "microgift_id": 42473, "image_url": " "price": "100.0", "merchant": "Fav Hotel", "sender_name": "Steve Chan", "message": "Welcome to the Golden Circle!", "exchangeable": false, "donatable": false, "expiration_days": 365, "gift_reminders": 12 ] GIFT INFO Retrieve latest information of a gift including the balance using the short code returned in the Create Gift API. PROTOCOL HTTP method URL GET <server>/v2/gifts/<short_code> REQUEST PARAMETERS The following parameters are passed in the URL. Note that the gift short code is part of the URL (see example). api_token required client api token api_secret required client api secret RESPONSE The response is a JSON string with the following parameters 15 P age Y iftee, Inc. v0.2

16 meta response s code:200 if successful Contains the gift element with details of the gift. gift.balance contains the current balance remaining on the gift. See example for details. EXAMPLE api_token=1d65d4dfbd7933c2e746f805877cf api_secret=a4c01cb4d9646fda206495e05f8cfc4c24189 short_code=d2lwcqy curl -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET $server"/v2/gifts/$short_code?api_token=$api_token&api_secret=$api_secret" > $prefix.log 2> $prefix.err Response "meta": "code": 200 "response": "gift": "id": 47097, "message": "message": " Welcome to the Preferred Circle!", "timestamp": " T19:07:13Z", "recipient_ ": "sam@cohowinery.com", "giftee_sms": "", "share_on_facebook": false, "recipient_twitter": "" "microgift": "id": 42472, "image_url": " "price": "20.00", "merchant": "id": , "name": "Fav Cafe", "address": "565 Middlefield Road, Menlo Park, California 94025", "address1": "565 Middlefield Road", "address2": "", "city": "Menlo Park", "state": "California", "zipcode": "94025", "phone": "(650) " "total_price": "22.00" "cannot_donate": "true", "cannot_exchange": "true", "balance": "20.00", "expiration_date": "Wednesday Dec 07, 2016", "created_at": "December 8, :07 PM", "giftee_name": "Sam", "short_code": "d2lwcqy ", "bounce_ ": null, "bounce_sms": null, "bounce_facebook": null, "bounce_twitter": null 16 P age Y iftee, Inc. v0.2

17 17 P age Y iftee, Inc. v0.2

API Documentation. Release Version 1 Beta

API Documentation. Release Version 1 Beta API Documentation Release Version 1 Beta Document Version Control Version Date Updated Comment 0.1 April 1, 2016 Initialize document 1 Release version PROMOTEXTER V3 BETA - API Documentation 1 Table of