# 代理商、團隊與 API

代理商如何以各客戶的名稱在 Agilis 上刊登廣告、團隊角色、餘額與帳單如何運作，以及如何使用 Agilis REST API。

**簡而言之：**代理商只需以自身的法定名稱註冊一次，並在**顯示名稱**中填入各客戶的名稱，即可為客戶刊登廣告。由代理商付款、持有餘額並收取帳單。開發人員可使用廣告平台中的 API 金鑰，透過 **Agilis REST API**（https://ads.agilis.dating）建立及管理優惠與活動；測試金鑰免費，且絕不會向會員顯示。

## 代理商適用

1. 以代理商自身的法定名稱**註冊代理商**。→ [如何註冊](https://www.agilis.dating/zh-hant/business/guide/register)
2. 建立優惠或活動時，請在**顯示名稱**中填入您**顯示名稱**。會員看到的是客戶的名稱，而非您的名稱。
3. 您必須獲得每位客戶的授權，才能為其刊登廣告。依據廣告條款，代理商須對此負責。

**由誰付款、帳單開給誰**

- 由您代理商的帳戶付款，並以代理商的計費幣別計價。
- 代理商中的每位成員都有自己的餘額，並從中付款。組織餘額為所有成員餘額的總和。→ [餘額如何運作](https://www.agilis.dating/zh-hant/business/guide/pricing)
- 帳單與成效均以您代理商的名義呈現，每筆付款開立一張帳單，方便您向各客戶轉開請款。
- 若要將各客戶的支出分開，請為每位客戶分別使用各自的優惠或活動，並依其帳單向客戶請款。

## 團隊角色

組織管理員與廣告主在廣告平台中作業；開發人員則透過 API 作業。開發人員無法在廣告平台中建立優惠或活動，但可使用其 API 金鑰透過 API 建立、發布優惠與活動並支付費用；貴公司須對其金鑰的使用方式負責。完整對照表請見[團隊角色與權限](https://www.agilis.dating/zh-hant/business/guide/getting-started)。

## Agilis REST API

- **基礎 URL：**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/zh-hant/business/guide/agencies-and-api