# 代理商、團隊同 API

代理商點樣以每位客戶嘅名義喺 Agilis 刊登廣告、團隊角色、餘額同發票點樣運作，以及點樣使用 Agilis REST API。

**簡而言之：**代理商只需以自己嘅法定名稱註冊一次，之後喺**對外顯示名稱**填寫每位客戶嘅名稱，就可以為客戶刊登廣告。費用由代理商支付，餘額由代理商持有，發票亦會發畀代理商。開發人員可以用廣告平台提供嘅 API 金鑰，透過 **Agilis REST API**（https://ads.agilis.dating）建立同管理優惠及活動；測試金鑰免費，而且永遠唔會向會員顯示。

## 代理商適用

1. **註冊代理商**，請使用代理商自己嘅法定名稱。→ [點樣註冊](https://www.agilis.dating/yue/business/guide/register)
2. 建立優惠或活動時，請喺**對外顯示名稱**填寫**對外顯示名稱**。會員會見到客戶嘅名稱，而唔係您嘅名稱。
3. 您必須獲得每位客戶授權，先可以為佢哋刊登廣告。根據廣告條款及細則，代理商須為此負責。

**邊個付款，發票發畀邊個**

- 費用由代理商帳戶支付，並以代理商嘅結算貨幣計算。
- 代理商入面每位成員都有自己嘅餘額，並由自己嘅餘額付款。機構餘額係所有餘額嘅總和。→ [餘額點樣運作](https://www.agilis.dating/yue/business/guide/pricing)
- 發票同成效數據都以代理商名義顯示，每次付款一張發票，方便您向每位客戶再收費。
- 如要分開記錄每位客戶嘅支出，請為每位客戶使用獨立嘅優惠或活動，並根據相關發票向客戶再收費。

## 團隊角色

機構管理員同廣告專員喺廣告平台工作；開發人員就透過 API 工作。開發人員唔可以喺廣告平台建立優惠或活動，但可以用自己嘅 API 金鑰透過 API 建立、發佈及支付優惠同活動，而貴機構須為其金鑰嘅使用方式負責。完整列表請參閱[團隊角色及權限](https://www.agilis.dating/yue/business/guide/getting-started)。

## Agilis REST API

- **基本網址：**https://ads.agilis.dating
- **參考文件：**www.agilis.dating/api-doc，附有 cURL、Python、Node.js 同 PHP 範例，仲有 API 助手
- **機器可讀格式：**OpenAPI 3.1 喺 www.agilis.dating/openapi.json，Markdown 喺 www.agilis.dating/api-doc.md，供 AI 工具使用嘅完整文本喺 www.agilis.dating/llms-full.txt
- **優惠：**列出您嘅類別同興趣；建立優惠前先估算價錢；建立、列出、暫停、恢復同刪除優惠；查閱每個優惠嘅成效
- **活動：**預覽、發佈、列出、編輯、改期、取消同刪除活動；查閱每個活動嘅成效

### 取得 API 金鑰

1. 以機構管理員或開發人員身分登入廣告平台。
2. 用頁面頂部嘅切換掣揀選**測試模式**或正式模式。
3. 前往 **API 金鑰** → **建立新金鑰**，為金鑰命名，亦可以按需要設定到期日。
4. **請即刻複製金鑰。**之後您將無法再查看。

測試金鑰以 `pk_test_` 開頭；正式金鑰以 `pk_live_` 開頭。每人喺每個模式最多可以有 10 條金鑰。**更換金鑰**會即時取代舊金鑰，所以請先更新您嘅系統。請喺 `x-api-key` 請求標頭傳送金鑰：`x-api-key: pk_test_…`。

### 安全開發

- 請用 `pk_test_` 金鑰開發同測試：測試優惠同活動免費，而且永遠唔會向會員顯示。
- 建立優惠前，請先用 price-estimate 估價端點計算價錢。
- 唔好將金鑰放入程式碼儲存庫或瀏覽器；請由您嘅伺服器呼叫 API。

## 常見問題

### 代理商可唔可以用一個帳戶管理多個客戶？

可以。代理商只需註冊一次，然後喺每個優惠或活動填寫客戶名稱。

### 每位客戶可唔可以有獨立發票？

發票會發畀您嘅代理商，每次付款一張。請根據發票向客戶再收費。

### 有冇沙盒測試環境？

有。使用 `pk_test_` 金鑰嘅測試模式就係完整嘅沙盒環境。唔會收取任何費用，亦唔會向會員顯示任何內容。

### 可唔可以連接 AI 編程工具？

可以。將您嘅工具指向 www.agilis.dating/api-doc.md 或 www.agilis.dating/openapi.json 就得。

Source: https://www.agilis.dating/yue/business/guide/agencies-and-api