---
doc_id: aipool-api-authentication-guide
title: AiPool 點數系統 API 驗證方式開發手冊
description: AiPool 點數系統 API 驗證方式開發手冊，說明應用申請、簽名驗證、會員匯入、查詢、累點、兌點、取消與點數明細查詢。
slug: /developers/aipool-api-authentication-guide
product: AiPool
category: developer-guide
audience:
  - developer
  - qa
visibility: public
status: published
version: 1.0.0
owner: aile-platform
updated_at: 2026-06-24
tags:
  - AiPool
  - UUPON
  - API
  - Authentication
  - 點數系統
  - 開發手冊
rendered_html: /rendered/developers/aipool-api-authentication-guide/
download: true
sidebar_position: 9
---

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

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

## 變更紀錄

| 版本號 | 作者 | 修訂內容 | 發布日期 |
| --- | --- | --- | --- |
| 1.0 | 朱春雷 | 初稿，提供點數相關API初步定義 | 2023-02-19 |
| 1.1 | 朱春雷 | 調整請求參數定義 | 2023-02-21 |
| 1.2 | 朱春雷 | 加入webhook定義 | 2023-02-26 |
| 1.3 | 朱春雷 | 加入api呼叫限制說明 | 2023-02-27 |
| 1.4 | 朱春雷 | 調整點數概念，調整API | 2023-03-07 |
| 1.5 | 朱春雷 | 補上回應參數名稱的屬性說明 | 2023-03-14 |
| 1.6 | 朱春雷 | 調整並加入預計支援的API | 2023-03-16 |
| 1.7 | 朱春雷 | 調整ID規則<br />單一企業：OpenID<br />點鑽：AccountID | 2023-03-18 |
| 1.8 | 朱春雷 | 新增變更使用者身份、發送優惠券，查詢帳號、使用者點數總覽，使用者企業列表等API | 2023-03-20 |
| 1.9 | 朱春雷 | 調整範圍查詢店家API，支持圓形查詢與矩形查詢 | 2023-03-30 |
| 1.10 | 朱春雷 | 調整API定義，舊URL規則能可沿用(2023年底失效)<br />新增激勵賺相關API<br />新增查詢客戶身分的店家列表API<br />新增查詢點鑽企業下消費明細API<br />核對請求參數與返回參數定義<br />調整範圍查詢僅返回商家列表<br />新增點數核銷 API<br />新增點數類型概述說明 | 2023-04-18 |
| 1.11 | 朱春雷 | 新增點數核銷 API<br />新增兌換激勵賺API | 2023-04-19 |
| 1.12 | 朱春雷 | 調整企業API<br />策略廠商API使用範圍定義 | 2023-04-26 |
| 1.13 | 朱春雷 | 根據商圈以及集團相關，調整API說明 | 2023-05-18 |
| 1.14 | 朱春雷 | 新增企業用API<br />查詢用戶關聯商圈列表<br />用戶點數總覽<br />企業生成累點連結(URL)<br />核銷點數<br />核銷賺+點<br />指定核銷<br />查詢交易紀錄<br />新增策略整合API<br />新增UUPON專用API<br />會員基本訊息API<br />查詢UUPON消費明細<br />創建特約店<br />查詢企業剩餘可用點數 | 2023-05-23 |
| 1.15 | 洪惟信 | 新增企業API<br />帳號唯一碼查詢 | 2024-04-15 |
| 1.16 | 洪惟信 | 調整帳號唯一碼查詢 | 2024-04-23 |
| 1.16.1 | 洪惟信 | 調整錯誤訊息 | 2024-05-06 |
| 1.16.2 | 許意研 | 新增查詢未生效UUPON點數明細 | 2025-01-15 |

## 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字串，範例：

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

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

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

應用Id：

秘鑰：

企業ID：

企業編號：

可發行企業點數：點

可發行UUPON點數：點

### JavaScript 範例

```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 範例實例

```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
```

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

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

```php
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 | String | 是 | 會員ID |
| countryCode | String | 是 | 手機國碼必須+開頭 |
| phone | String | 是 | 手機號碼 |
| name | String | 是 | 使用者名稱 |
| pointType | Integer | 是 | 點數類別<br />預設：0<br />(不可流通) |
| point | Integer | 是 | 初始化點數，若無則帶入0 |
| reason | String | 否 | 原因 |
| reasonCode | String | 否 | 原因代碼 |
| fromSystem | String | 否 | 來源系統 |
| fromDevice | String | 否 | 來源裝置 |
| fromInfo | String | 否 | 來源資訊 |

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

#### 回應參數值

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| id | String | 對應的累點紀錄Id |
| tenantId | String | 企業ID |
| tenantCode | String | 企業編碼 |
| openId | String | 使用者openId |
| name | String | 使用者名稱 |
| aiCoin | Integer | 使用者擁有的uupon點數<br />(非點鑽企業，一般為0) |
| aiPool | Integer | 使用者擁有的企業點 |
| point | Integer | 使用者擁有的賺總和 |
| enableAiCoin | Integer | 使用者可用的UUPON點 |
| enableAiPool | Integer | 使用者可用的企業點 |
| enablePoint | Integer | 使用者可用的賺 |
| coupon | Integer | 使用者擁有的優惠卷總合 |
| enableCoupon | Integer | 使用者可用的優惠卷總合 |

### 查詢OpenID

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

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

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

**Method：** POST

#### 請求參數名稱

| 欄位名稱 | 資料類型 | 是否必填 | 欄位說明 |
| --- | --- | --- | --- |
| userIdType | String | 是 | Id的類型<br />手機<br />匯入時的Id |
| id | String | 是 | 若userIdType為手機，則id需要國碼+手機號碼。舉例 PHONE_E164_PLACEHOLDER |

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

#### 回應參數值

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| data | String | 對應的OpenId |

```json
{
"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 | String | 是 | openID |
| startTime | Long | 是 | 生效時間<br />(時間戳-毫秒) |
| expireTime | Long | 是 | 失效時間，若為0則依據系統設定，即開始時間+點數有效期<br />(時間戳-毫秒) |
| pointType | String | 是 | 點數類型，預設0，不可流通的點；1 = UUPON點 |
| point | Integer | 是 | 累積點數，需大於0 |
| reason | String | 否 | 原因 |
| reasonCode | Integer | 否 | 原因代碼 |
| fromSystem | String | 否 | 來源系統 |
| fromDevice | String | 否 | 來源裝置 |
| fromInfo | String | 否 | 來源資訊 |
| timeType | String | 否 | 默認:0 長期點數，expireTime的23:59:59<br />1：短期點數，expireTime必須於當前24小時內的時間戳，精準到分鐘失效 |
| activityName | String | 否 | 活動標記<br />若pointType=0且ActivityName不為空，則對應的使用者只能通過activityName活動參與一次累企業點，若pointType=0 則此參數無效 |

```php
{"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}
```

#### 回應參數值

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| id | String | 對應的累點紀錄Id (bizID) |
| tenantId | String | 企業ID |
| tenantCode | String | 企業編碼 |
| openId | String | 使用者openId |
| name | String | 使用者名稱 |
| aiCoin | Integer | 使用者擁有的uupon點數<br />(非點鑽企業，一般為0) |
| aiPool | Integer | 使用者擁有的企業點 |
| point | Integer | 使用者擁有的賺總和 |
| enableAiCoin | Integer | 使用者可用的UUPON點 |
| enableAiPool | Integer | 使用者可用的企業點 |
| enablePoint | Integer | 使用者可用的賺 |
| coupon | Integer | 使用者擁有的優惠卷總合 |
| enableCoupon | Integer | 使用者可用的優惠卷總合 |

**範例：**

```json
{
"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

#### 請求參數名稱

| 欄位名稱 | 資料類型 |  | 是否必填 | 欄位說明 |
| --- | --- | --- | --- | --- |
| id | String |  | 是 | openID(使用者的openId) |
| point | String |  | 是 | 點數 |
| reason | String |  | 否 | 原因 |
| reasonCode | String |  | 否 | 原因代碼 |
| fromSystem | String |  | 否 | 來源系統 |
| fromDevice | String |  | 否 | 來源設備 |
| fromInfo | String |  | 否 | 來源資訊 |

#### 回應參數值

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| id | String | 對應的紀錄Id |
| tenantId | String | 企業ID |
| tenantCode | String | 企業編碼 |
| openId | String | 使用者openId |
| name | String | 使用者名稱 |
| aiCoin | Integer | 使用者擁有的uupon點數總合<br />(非點鑽企業，一般為0) |
| aiPool | Integer | 使用者擁有的企業點 |
| point | Integer | 使用者擁有的賺總和 |
| enableAiCoin | Integer | 使用者可用的UUPON點 |
| enableAiPool | Integer | 使用者可用的企業點 |
| enablePoint | Integer | 使用者可用的賺 |
| coupon | Integer | 使用者擁有的優惠卷總合 |
| enableCoupon | Integer | 使用者可用的優惠卷總合 |

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

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

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

**API路徑：** https://lab.uupon.com/api/transaction/v1/tenant/exchange_by_id

**Method：** POST

#### 請求參數名稱

| 欄位名稱 | 資料類型 | 是否必填 | 欄位說明 |
| --- | --- | --- | --- |
| orderType | String | 否 | 交易訂單類型 |
| description | String | 否 | 交易描述訊息 |
| outTradeNo | String | 否 | 外部交易ID(由外部交易平臺產生，不得重複) |
| id | String | 是 | 企業下的openId |
| attach | String | 否 | 附加資訊 |
| point | String | 是 | 欲核銷的點數數量 |
| districtId | String | 否 | 商圈ID |

#### 回應參數值

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| result | String | 1代表成功<br />-1 代表失敗代表失敗 |
| point | String | 成功核銷點數數量 |

```php
{
["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 | String | 是 | 企業下的OpenId |
| tradeId | String | 是 | 欲取消的交易ID(透過累點成功後系統回傳的Id參數) |
| reason | String | 是 | 取消的原因 |
| fromSystem | String | 否 | 來源系統 |
| fromDevice | String | 否 | 來源裝置 |
| fromInfo | String | 否 | 附帶資訊 |

**範例：**

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

#### 回應參數值

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| result | String | 1代表成功<br />-1 代表失敗代表失敗 |
| point | String | 成功核銷點數數量 |
| trade | String | 交易Id |

**範例：**

```json
{
"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

#### 請求參數名稱

| 欄位名稱 | 資料類型 | 是否必填 | 欄位說明 |
| --- | --- | --- | --- |
| id | String | 是 | openID(使用者的openId) |

#### 回應參數值

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| name | String | 使用者名稱 |
| openId | String | 本企業下的openId |
| tenantPoint | object | 使用者擁有的企業點數總覽 |
| districtPoints | object[] | 使用者擁有的商圈下點數總覽 |
| uuponPoints | object | 使用者可用的UUPON點數總覽 |

```php
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

#### 請求參數名稱

| 欄位名稱 | 資料類型 | 是否必填 | 欄位說明 |
| --- | --- | --- | --- |
| id | String | 是 | openID(使用者的openId) |

#### 回應參數值

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| tenantId | String | 企業ID |
| tenantCode | String | 企業編碼 |
| tenantName | String | 企業名稱 |
| location | object[] | 企業座標(可顯示在地圖上) |
| aiCoin | int | 企業可用的UUPON點數總和 |
| aiPool | int | 企業可用的企業點數總和 |

### 查詢使用者企業點數明細

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

**Method：** POST

#### 請求參數名稱

| 欄位名稱 | 資料類型 | 必填 | 欄位說明 |
| --- | --- | --- | --- |
| id | String | 是 | openID(使用者的openId) |
| pageIndex | Integer | 是 | 當前索引，從0開始 |
| pageSize | Integer | 否 | 返回資料列大小，最小值1，最大值20，默認為20 |
| pointType | Integer | 是 | 查詢的點數類別<br />0：賺<br />1：點<br />2：激勵賺 |

#### 回應參數值

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| pageIndex | Integer | 當前索引，從0開始 |
| pageSize | Integer | 返回資料列大小 |
| totalPage | Integer | 總頁數 |
| total | Long | 總資料量 |
| list | `T` | 當前資料列表 |
| hasNextPage | Boolean | 是否存在下一頁 |

#### `T` 內欄位

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| point | int | 紀錄的點數 |
| startTime | long | 生效時間 (時間戳-毫秒) |
| expireTime | long | 失效時間 (時間戳-毫秒) |
| reason | String | 紀錄的原因 |
| reasonCode | String | 紀錄的原因代碼(若空，不顯示) |
| fromSystem | String | 來源系統(若空，不顯示) |
| fromDevice | String | 來源裝置(若空，不顯示) |
| fromInfo | String | 來源資訊(若空，不顯示) |
| limitInfo | LimitInfo[] | 限制範圍，若為空則無限制 |
| couponId | String | 優惠券碼(查詢[賺]返回) |
| couponName | String | 優惠券名稱(查詢[賺]返回) |
| flagName | String | 激勵賺名稱(查詢[激勵賺]返回) |
| flagCode | String | 激勵卡編號(查詢[激勵賺]返回) |

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

**測試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點數，無法被取消

#### 請求參數名稱

| 欄位名稱 | 資料類型 | 必填 | 欄位說明 |
| --- | --- | --- | --- |
| id | String | 是 | openID(使用者的openId) |
| bizId | String | 是 | 累點成功時，系統返回Id |
| reason | String | 否 | 原因 |
| reasonCode | String | 否 | 原因代碼 |
| fromSystem | String | 否 | 來源系統 |
| fromDevice | String | 否 | 來源設備 |
| fromInfo | String | 否 | 來源原因 |

#### 回應參數值

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| id | String | 對應的交易紀錄Id |
| tenantId | String | 企業租戶ID |
| tenantCode | String | 企業編碼 |
| openId | String | 用戶的openId |
| name | String | 用戶名稱 |
| aiCoin | Integer | 用戶的UUPON點，若非點鑽應用，該欄位為0 |
| aiPool | Integer | 用戶的企業點數總和 |
| point | Integer | 用戶的賺數總和 |
| coupon | Integer | 用戶的卷張數總和 |
| enableAiCoin | Integer | 可用的UUPON點數總和 |
| enableAiPool | Integer | 可用的企業點數總合 |
| enablePoint | Integer | 可用的賺數總和 |
| enableCoupon | Integer | 可用的卷數總和 |

### 取消兌點 (取消兌點)

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

**Method：** POST

**說明：** 取消一次兌點

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

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

#### 請求參數名稱

| 欄位名稱 | 資料類型 | 必填 | 欄位說明 |
| --- | --- | --- | --- |
| id | String | 是 | openID(使用者的openId) |
| bizId | String | 是 | 兌點成功時，系統返回Id |
| reason | String | 否 | 原因 |
| reasonCode | String | 否 | 原因代碼 |
| fromSystem | String | 否 | 來源系統 |
| fromDevice | String | 否 | 來源設備 |
| fromInfo | String | 否 | 來源原因 |

#### 回應參數值

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| id | String | 對應的交易紀錄Id |
| tenantId | String | 企業租戶ID |
| tenantCode | String | 企業編碼 |
| openId | String | 用戶的openId |
| name | String | 用戶名稱 |
| aiCoin | Integer | 用戶的UUPON點，若非點鑽應用，該欄位為0 |
| aiPool | Integer | 用戶的企業點數總和 |
| point | Integer | 用戶的賺數總和 |
| coupon | Integer | 用戶的卷張數總和 |
| enableAiCoin | Integer | 可用的UUPON點數總和 |
| enableAiPool | Integer | 可用的企業點數總合 |
| enablePoint | Integer | 可用的賺數總和 |
| enableCoupon | Integer | 可用的卷數總和 |

### 帳號唯一碼查詢

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

**Method：** POST

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

企業外部ID。

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

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

#### 請求參數名稱

| 欄位名稱 | 資料類型 | 必填 | 欄位說明 |
| --- | --- | --- | --- |
| phone | String | 是 (四擇一) | 手機09XXXXX(不須帶+886) |
| accountId | String | 是 (四擇一) | 生態帳號ID |
| openId | String | 是 (四擇一) | 企業OpenId |
| uid | String | 是 (四擇一) | 企業外部ID |

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

#### 回應參數值

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| phone | String | 手機號碼 |
| accountId | String | 生態帳號ID，非Aile管理企業或點鑽企業均為flase |
| openId | String | 企業openId |
| uid | String | (外部) 企業匯入UID |

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

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

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

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

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

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

**response 4：未提供任何參數**

```json
{
"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點數，未生效時的列表

#### 請求參數名稱

| 欄位名稱 | 資料類型 | 必填 | 欄位說明 |
| --- | --- | --- | --- |
| id | String | 是 | OpenId |

**Request：**

```json
{ "id": "OBJECT_ID_PLACEHOLDER" }
```

#### 回應參數值

| 欄位名稱 | 資料類型 | 欄位說明 |
| --- | --- | --- |
| data | Array(Object{}) | 數據結構 |
| id | string | BizId(交易編號) |
| point | integer | 點數 |
| startTime | integer | 點數生效日期(時間戳到毫秒) |
| reason | string | 贈點理由 |
| createTime | integer | 贈送點數日期(時間戳到毫秒) |
| code | integer | API回應值: 1000代表執行成功 |
| message | string | API回應訊息 |
| subCode | string | API回應subCode |

**Reponse：**

```json
{
"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"
}
```

| 錯誤碼 | 說明 |
| --- | --- |
| 1000 | 執行成功 |
| 2000 | 服務不可用(系統異常) |
| 2002 | 傳入參數錯誤 |
| 6001 | userType範圍錯誤 |
| 6002 | 手機號碼已被綁定 |
| 6003 | ID已經存在 |
| 6004 | ID類型不正確(帶入的ID非字串格式) |
| 6005 | 沒有找到對應的企業用戶 |
| 6006 | 帳號不存在 |
| 7001 | APP狀態不正確 |
| 7002 | APP未達到啟用時間 |
| 7003 | 拒絕存取，IP未授權 |
| 7004 | APP權限不足，不允許此API |
| 7005 | APP類型不正確 |
| 7006 |  |
| 20000 | NO_ACCOUNT，找不到對應帳號 |
| 20007 | 未輸入參數 |
| 20031 | 用戶不存在 |