# 服务端 API


服务端 API 供你的**后端服务**以应用身份调用平台能力，覆盖登录、支付、服务通知、多任务管理等场景。它与前端 JS API 配合，构成完整的智能服务能力闭环。

## 先理解鉴权模型

> 大部分应用级接口需要先获取**应用级鉴权 Token**（access_token）：用 app_id + app_secret、grant_type=client_credential 调用 `/api/token/v1/developer/get_client_token` 换取。Token 有有效期（见 expires_in），应缓存复用、避免高频调用。部分接口（如用 login_code 换 OpenID）直接用 app_id + app_secret 鉴权，无需 access_token。

> app_secret 属敏感信息，务必妥善保管，切勿在客户端代码或公开环境中暴露。

## 接口分类

| 分类 | 主要接口 |
|-|-|
| 登录 | 获取应用级鉴权 Token、获取用户 OpenID、获取用户加密手机号 |
| 支付 | 订单查询、退款创建/查询、协议支付（创建/查询/关闭/解约）、支付与退款结果回调、代扣回调 |
| 服务通知 | 发送服务通知（请求头携带 X-DB-AccessToken） |
| 多任务管理 | 创建云端任务、更新云端任务 |

## 登录换 OpenID 流程示例

1. 智能服务端调用登录组件获取短期一次性 `login_code`，发送至你的服务端。
2. 服务端用 app_id + app_secret 调用「获取用户 OpenID」，将 login_code 换取该用户在本应用下唯一的 `open_id`。
3. 用 open_id 关联或注册到你的自有账号体系。

注意：login_code 有效期极短且一次性，服务端收到后应立即换取；同一用户在不同应用下的 open_id 不同。