# 代理商、团队与 API

代理商如何以各客户的名称在 Agilis 上为客户投放广告，团队角色、余额和发票如何运作，以及如何使用 Agilis REST API。

**简而言之：**代理商只需以自身的法定名称注册一次，然后在**展示名称**中填写各客户的名称，即可为客户投放广告。由代理商付款、持有余额并接收发票。开发者可使用广告平台中的 API 密钥，通过 **Agilis REST API**（https://ads.agilis.dating）创建和管理优惠与活动；测试密钥免费，相关内容也绝不会向用户展示。

## 面向代理商

1. 以代理商自身的法定名称**注册代理商**。→ [如何注册](https://www.agilis.dating/zh-hans/business/guide/register)
2. 创建优惠或活动时，请在**展示名称**中填写**展示名称**。用户看到的是客户的名称，而不是您的名称。
3. 您必须获得每位客户的授权，才能为其投放广告。根据广告条款，代理商须对此负责。

**由谁付款，向谁开具发票**

- 由您代理商的账户付款，以代理商的结算货币计价。
- 代理商中的每个人都有自己的余额，并从中付款。机构余额为所有人余额的总和。→ [余额如何运作](https://www.agilis.dating/zh-hans/business/guide/pricing)
- 发票和效果数据均以您代理商的名义出具，每笔付款对应一张发票，方便您向各客户转收费用。
- 为分开核算每位客户的支出，请为每位客户使用单独的优惠或活动，并依据相应发票向客户转收费用。

## 团队角色

机构管理员和广告主在广告平台中操作；开发者通过 API 操作。开发者无法在广告平台中创建优惠或活动，但可使用其 API 密钥通过 API 创建、发布优惠和活动并为其付款；贵企业须对其密钥的使用方式负责。完整表格请见[团队角色与权限](https://www.agilis.dating/zh-hans/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_` 密钥进行开发和测试：测试优惠和活动免费，且绝不会向用户展示。
- 创建优惠前，请先使用价格估算端点估算价格。
- 请勿将密钥放入代码仓库或浏览器中；请从您的服务器调用 API。

## 常见问题

### 代理商能否通过一个账户管理多个客户？

可以。只需注册一次代理商，并在每个优惠或活动中填写客户名称。

### 能否为每位客户单独开具发票？

发票开具给您的代理商，每笔付款一张。您可依据这些发票向客户转收费用。

### 有沙盒环境吗？

有。使用 `pk_test_` 密钥的测试模式就是一个完整的沙盒环境。不会产生任何费用，也不会向用户展示任何内容。

### 可以接入 AI 编程工具吗？

可以。将您的工具指向 www.agilis.dating/api-doc.md 或 www.agilis.dating/openapi.json 即可。

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