AiPool 點數系統 API 驗證方式開發手冊

來源文件：點數系統(Aipool)_API 驗證方式_公版.docx。本文已將示例密鑰、手機號、長 ID 等公開發布不需要的值改為占位符。

變更紀錄

API 驗證方式

概述

點數系統提供API的方式，允許外部系統透過呼叫API方式進行系統整合，本章節主要是說明API呼叫的方式與驗證簽名方式。

呼叫API是需要申請點數平台的租戶，目前僅限由管理員協助創建租戶帳號，取得帳號後，登入點數平台管理後台，選擇自己擁有的企業，到我的應用，建立新的應用。

應用分成四大類：

• • 企業應用：單一企業下可以調用的API，包含點數(賺)操作、帳號匯入、點數總覽、點數明細等
• • 授權應用：可授權自己的企業API，給予其他平台呼叫
• • WebHook 應用：可設定那些指定操作，由系統主動發出WebHook訊息
• • 策略合作應用：策略夥伴用的API，比如點點全球，一般企業不會使用到

API 驗證標準原則

連結方式：HTTPS

Method： POST

資料格式：JSON字串

字元編碼：UTF-8

簽名格式：AILE(空一格)AppId:Signature

AILE：固定

AppId：透過點數後台建立的應用APP ID

Signature：加密字串

Base64(HMAC-SHA256(appid+nonce+MD5(requestBody), SecretKey))

nonce：隨機字串，可以使用timestamp

requestBody：請求參數，Array轉成JSON字串，範例：

Array ([userIdType] => 2, [id] => USER_ID_PLACEHOLDER) => JSON 字串

{"userIdType":2,"id":"USER_ID_PLACEHOLDER"}

企業應用資訊(請找業務申請)：

應用Id：

秘鑰：

企業ID：

企業編號：

可發行企業點數：點

可發行UUPON點數：點

JavaScript 範例

var hmacPrefix = "AILE";                              // 簽名起始字串
var AppId = "APP_ID_PLACEHOLDER";                   // appid (點數管理後台取得)
var APIKey = "<APP_KEY>";      // app SecretKey (點數管理後台取得)
var nonce = new Date().getTime();                      // 創建隨機值
var requestContentBase64String = "";
var bodyObj = JSON.parse(pm.request.body.toString());
var bodyString = JSON.stringify(bodyObj);   //產生要發送的request body字串，並經過了JSON格式化去空格
if (bodyString) {
var md5 = CryptoJS.MD5(bodyString);     // 對request body的內容進行MD5加密
requestContentBase64String = md5.toString();
}
var signatureRawData  = AppId  +  nonce + requestContentBase64String; // 將簽名的內容組合
var signature = CryptoJS.enc.Utf8.parse(signatureRawData);              //轉換UTF-8格式
var signatureBytes = CryptoJS.HmacSHA256(signature,APIKey);            // HmacSHA256加密
var requestSignatureBase64String = CryptoJS.enc.Base64.stringify(signatureBytes); //Base64加密
var hmacKey = hmacPrefix + " " + AppId + ":" + requestSignatureBase64String; // 最終Authorization
// 設置header
pm.request.headers.add({
key: "nonce",
value: nonce
});
pm.request.headers.add({
key: "Authorization",
value: hmacKey
});
// 因body為json，MD5加密的時候已經去除空格，所以確保發送的內容和簽名的body內容一致，需重新設置了body的資料
pm.request.body.raw = bodyString

PHP 範例實例

$hmacPrefix = 'AILE';              //固定頭
$AppId = APP_ID_PLACEHOLDER;   //應用APPID
$APIKey = <APP_KEY>; //應用APP 密鑰
$body = '{"userIdType":1,"id":"PHONE_E164_PLACEHOLDER"}';  //request Body
$nonce = time();
$md5_body = md5($body);          //md5加密 body
$sha256 = hash_hmac('sha256',$AppId.$nonce.$md5_body,$APIKey,true);  //sha256加密
$sha256_str = base64_encode($sha256);                             //base64加密
$str = $hmacPrefix.' '.$AppId.':'.$sha256_str;                          //組成Authorization

$api_url = 'https://lab.uupon.com/api/tenant/v1/user/getOpenId';                  //API位置

$rs = httpRequest($api_url, $body, $nonce, $str);  //呼叫API
print_r($rs);  //將回應值顯示出來

function httpRequest($api, $body, $nonce, $str) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'nonce: '.$nonce,
'Authorization:'.$str)
);
$result = curl_exec($ch);
curl_close($ch);
return json_decode($result, true);
}

建立會員(匯入使用者並初始化點數)

說明： 用於第一次建立帳號用，檢查手機是否存在，不存在則建立帳號，檢查企業是否存在帳號，不存在則進行創建使用者，並匯入點數，存在則拒絕不可再次匯入

API路徑： https://lab.uupon.com/api/tenant/v1/user/import

Method： POST

請求參數名稱

{ "id": "SuperPoint202307271",
"countryCode": "+886",
"phone": "PHONE_PLACEHOLDER",
"pointType": 0,
"point": 0,
"reason": "註冊會員",
"reasonCode": "0099",
"fromSystem": "1",
"fromDevice": "1",
"fromInfo": "1",
"name": "PHONE_PLACEHOLDER"
}

回應參數值

查詢OpenID

說明： 透過匯入使用者時的手機或者原平台的uid，查詢在點鑽點數平台的OpenId

通常應用在登入時，確認手機或uid是否存在某個企業下，若不存在則呼叫匯入使用者並初始化點數API來建立帳號。

API路徑： https://lab.uupon.com/api/tenant/v1/user/getOpenId

Method： POST

請求參數名稱

{"userIdType":1,"id":"PHONE_E164_PLACEHOLDER"}

回應參數值

{
"data": "60ff72******76cd8",
"code": 1000,
"message": "成功",
"subCode": "AP.SUCCESS"
}

累點 API

說明： 當需要進行點數發送時，呼叫使用，需要先取得該用戶的OpenId才可以進行操作，

發送點數時，會需要檢查企業下的點數池是否存在足夠的點數，另外可設定生效時間，只有未生效跟未使用的點數才可以取消累點；當發送UUPON點，企業下需要額外購買系統服務費，已取得贈送的UUPON點數，UUPON點數發送後，在UUPON點數未生效前，才可以取消累UUPON點，已經生效的UUPON點數，是無法取消累點，點數在生效時，準備金流轉到點鑽企業，同時UUPON點數歸屬權已經轉移至點鑽企業，負責替會員履約

API路徑： https://lab.uupon.com/api/tenant/v1/user/point/increase

Method： POST

請求參數名稱

{"id":"OBJECT_ID_PLACEHOLDER",
"startTime":'.$starttime.',
"expireTime":1735574400000,
"pointType":1,
"point":10,
"reason":"API 測試",
"reasonCode":"0010",
"fromSystem":"PHP_API",
"fromDevice":"API_TEST",
"fromInfo":"IF010",
"timeType":0}

回應參數值

範例：

{
"data": {
"id": "64070c5****3b6c61ec4",      //這個是bizId 若要取消則需要這個值
"couponId": "64070c8****b6c61ec3",
"tenantId": "1073****1008",
"tenantCode": "91003646-01",
"openId": "20230****00001",
"name": "api_test",
"aiCoin": 0,
"aiPool": 100,
"point": 0,
"enableAiCoin": 0,
"enableAiPool": 0,
"enablePoint":  0,
"coupon": 0,
"enableCoupon": 0
},
"code": 1000,
"message": "成功",
"subCode": "AP.SUCCESS"
}

兌點 API(本企業的企業點)

說明： 目前僅開放企業兌點自身企業的點數，若要跨企業或者核銷UUPON點數，要使用點數核銷 API

API路徑： https://lab.uupon.com/api/tenant/v1/user/point/decrease

Method： POST

請求參數名稱

回應參數值

點數核銷 API(使用openId) -扣除UUPON點數

說明： 核銷點數為一次交易過程，會自動先從 企業點/集團點->商圈點->UUPON點，等過程

扣點，進行核銷，企業點不足扣商圈點，商圈點不足最後扣UUPON點

API路徑： https://lab.uupon.com/api/transaction/v1/tenant/exchange\_by\_id

Method： POST

請求參數名稱

回應參數值

{
["data"]=>
array(3) {
["result"]=>
int(1)
["point"]=>
int(3)
["tradeId"]=>
string(24) "OBJECT_ID_PLACEHOLDER"
}
["code"]=>
int(1000)
["message"]=>
string(6) "成功"
["subCode"]=>
string(10) "AP.SUCCESS"
}

取消點數核銷 API(使用openId方式)

說明： 根據核銷的交易紀錄進行反向返點，若交易大於七日則不允許取消

取消核銷會引發企業點數返還給會員，因此有可能導致企業可使用點數為負，

負值超過一定數值則不能再發送點數API路徑：

https://lab.uupon.com/api/transaction/v1/tenant/exchange/cancel

Method： POST

請求參數名稱

範例：

{
"id": "OBJECT_ID_PLACEHOLDER",
"bizId": "LONG_ID_PLACEHOLDER",
"reason": "取消核銷",
"fromSystem": "API",
"fromDevice": "API",
"fromInfo": "API"
}

回應參數值

範例：

{
"data": {
"result": 1,
"point": 6,
"tradeId": "LONG_ID_PLACEHOLDER"
},
"code": 1000,
"message": "成功",
"subCode": "AP.SUCCESS"
}

查詢使用者在所有企業下的點數總覽

API路徑： https://lab.uupon.com/api/tenant/v2/user/info

Method： POST

請求參數名稱

回應參數值

array(4) {
["data"]=>
array(4) {
["name"]=>
string(6) "api_test"
["openId"]=>
string(24) "OBJECT_ID_PLACEHOLDER"
["tenantPoint"]=>
array(11) {
["tenantId"]=>
string(19) "LONG_ID_PLACEHOLDER"
["tenantCode"]=>
string(8) "83119052"
["tenantName"]=>
string(14) "SP超級點數"
["name"]=>
string(6) "api_test"
["aiCoin"]=>
int(0)
["aiPool"]=>
int(0)
["point"]=>
int(0)
["enableAiCoin"]=>
int(0)
["enableAiPool"]=>
int(0)
["enablePoint"]=>
int(0)
["enableCoupon"]=>
int(0)
}
["uuponPoint"]=>
array(6) {
["tenantId"]=>
string(19) "LONG_ID_PLACEHOLDER"
["tenantCode"]=>
string(14) "000-000-000002"
["tenantName"]=>
string(12) "點鑽企業"
["name"]=>
string(6) "api_test"
["aiCoin"]=>
int(10)
["enableAiCoin"]=>
int(10)
}
}
["code"]=>
int(1000)
["message"]=>
string(6) "成功"
["subCode"]=>
string(10) "AP.SUCCESS"
}

查詢企業下的可用點數

API路徑： https://lab.uupon.com/api/tenant/v1/tenant/info

Method： POST

請求參數名稱

回應參數值

查詢使用者企業點數明細

API路徑： https://lab.uupon.com/api/tenant/v1/user/detial

Method： POST

請求參數名稱

回應參數值

T 內欄位

取消累點 (取消企業專用點數累點)

測試API路徑： https://lab.uupon.com/api/tenant/v1/user/point/increase/cancel

正式API路徑：https://prod.uupon.com/api/tenant/v1/user/point/increase/cancel

Method： POST

說明： 取消一次累點

限制： 1.對應的累點點數沒有被使用或者點數未達生效時間

2.已經發送的UUPON點數，無法被取消

請求參數名稱

回應參數值

取消兌點 (取消兌點)

API路徑： https://lab.uupon.com/api/tenant/v1/user/point/decrease/cancel

Method： POST

說明： 取消一次兌點

1.取消兌點時，若企業點數的有效期已經過期，將默認延長當前時間1小時的有效期

2.兌點紀錄的時間若已超過7天，則不允許取消

請求參數名稱

回應參數值

帳號唯一碼查詢

API路徑： https://lab.uupon.com/api/tenant/v1/only/code

Method： POST

說明： 透過手機、企業外部ID、帳號ID、企業openId查詢，帳號ID、企業openId、

企業外部ID。

主要是應用在外部整合應用中，對於多租戶與點鑽生態帳號之間的關聯，在贈送會員UUPON

點數時，提供查詢功能給予企業針對自己應用流程進行判斷是否要幫用戶建立帳號

請求參數名稱

{
"phone": "PHONE_PLACEHOLDER",
"accountId": "",
"openId": "",
"uid": ""
}

回應參數值

response 1：UUPON帳號存在、企業帳號存在

{
"data": {
"phone": "PHONE_PLACEHOLDER",
"accountId": true,
"openId": "OBJECT_ID_PLACEHOLDER",
"uid": "UID_PLACEHOLDER"
},
"code": 1000,
"message": "成功",
"subCode": "AP.SUCCESS"
}

response 2：UUPON帳號不存在、企業帳號不存在

{
"data": null,
"code": 20000,
"message": "找不到對應帳號",
"subCode": "NO_ACCOUNT"
}

response 3：UUPON帳號存在、企業帳號不存在

{
"data": {
"phone": "PHONE_PLACEHOLDER",
"accountId": true,
"openId": "",
"uid": ""
},
"code": 1000,
"message": "成功",
"subCode": "AP.SUCCESS"}

response 4：未提供任何參數

{
"data": null,
"code": 20007,
"message": " 至少需要提供一個參數",
"subCode": "AT_LEAST_ONE_PARAMETER_REQUIRED"
}

(非點鑽企業)獲取發送之UUPON點數未生效列表

API 路徑： https://lab.uupon.com/admin/api/tenant/v1/user/inactive/points

Method： POST

說明： 透過企業下的用戶openId查詢，查詢企業發UUPON點未生效之點數列表

主要是應用在外部整合應用中，對於多租戶與點鑽生態帳號之間的關聯，在贈送會員UUPON

點數時，提供查詢功能給予企業針對自己發送出UUPON點數，未生效時的列表

請求參數名稱

Request：

{ "id": "OBJECT_ID_PLACEHOLDER" }

回應參數值

Reponse：

{
"data": [
{
"id": "OBJECT_ID_PLACEHOLDER",
"point": 50,
"startTime": 1737302400637,
"reason": "API 測試",
"createTime": 1736911489058
},
{
"id": "OBJECT_ID_PLACEHOLDER",
"point": 50,
"startTime": 1737302400637,
"reason": "API 測試",
"createTime": 1736911494987
},
{
"id": "OBJECT_ID_PLACEHOLDER",
"point": 50,
"startTime": 1737302400637,
"reason": "API 測試",
"createTime": 1736911496254
},
{
"id": "OBJECT_ID_PLACEHOLDER",
"point": 50,
"startTime": 1737302400637,
"reason": "API 測試",
"createTime": 1736911497251
}
],
"code": 1000,
"message": "成功",
"subCode": "AP.SUCCESS"
}