[第二章]添加API接口教程

添加前准备

添加接口前请准备好：

• 已创建的接口分类。
• 接口名称、简介、图标和关键词。
• 请求方式及返回格式。
• 请求参数、返回参数和成功返回示例。
• 计费方式和价格。
• 如果您需要对接第三方接口还需要：第三方接口的上游地址、固定参数及 Token（如有）。

一、填写接口信息

进入“接口管理 > 接口列表”，点击“添加”。

基础信息

• API 图片：上传用于前台展示的接口图标。
• 选择分类：选择已经建立的接口分类。
• 接口类型：选择“官方”或“第三方”。
• API 名称：填写用户看到的接口名称。
• API 关键词：多个关键词用英文逗号分隔，例如 IP,归属地,查询。
• API 简介：说明接口作用、数据来源和适用场景。
• 成功返回示例：填写真实且格式正确的成功响应。
• 接口权重：数值越大，前台排序越靠前。
• 接口实名可用：可设置无需实名、个人实名或企业实名。

二、添加官方接口

官方接口适用于将接口代码部署在本系统的 api 目录中。

1. 准备接口文件

例如接口目录为：

api/ping/

接口入口文件为：

api/ping/api.php

2. 填写接口地址

“接口地址”只填写 api/ 后面的部分：

ping/api.php

“接口目录名”填写：

ping

页面通常会根据接口地址自动获取目录名，保存前仍应检查一次。

3. 设置响应方式

• 返回格式：可选 json、text、img、audio/mp3、video/mp4。
• 请求方式：根据接口代码选择 GET 或 POST。
• 选择文件：需要通过后台上传接口包时使用；已手动上传到服务器的接口不必重复上传。

官方接口代码必须自行完成业务处理，并按文档中定义的格式返回结果。

三、添加第三方接口

第三方接口适用于代理上游 API。系统接收用户请求后，再向填写的上游地址发起请求。

1. 接口地址

填写完整上游地址，例如：

https://upstream.example.com/v1/query

必须带 http:// 或 https://，并确认服务器可以直接访问该地址。

2. 固定附带参数

如果上游要求每次请求都携带固定参数，将“附带参数”设为“附带”，每行填写一个参数，格式为：

key|123456
version|v1
channel|api

左侧是参数名，右侧是参数值，中间使用半角竖线 |。不要使用中文竖线，也不要在行尾添加逗号。

固定参数适合保存上游密钥、渠道编号等不需要用户输入的值。涉及敏感密钥时必须使用 HTTPS。

3. 请求头 Token

上游要求请求头 Token 时，将“请求头token”设为“有”，然后填写 Token。若上游不要求请求头鉴权，保持“无”。

4. 返回结果判断

• 返回格式：选择上游真实返回格式。
• 请求方式：选择上游要求的 GET 或 POST。
• 成功参数：JSON 响应中用于判断成功的字段，例如 code。
• 成功值：成功字段对应的值，例如 200 或 0。

例如上游成功响应为：

{
  "code": 200,
  "message": "success",
  "data": {}
}

则成功参数填写 code，成功值填写 200。非 JSON 接口可根据实际情况留空。

四、填写请求参数说明

切换到“参数内容”标签。系统已经固定包含 apikey 参数，表示用户开通后获得的调用密钥。

为每个业务参数填写：

• 参数名称：例如 url、ip、keyword。
• 是否必填：选择“是”或“否”。
• 参数类型：支持 int、string、Array、float、bool、file、object。
• 参数说明：说明格式、范围、默认值和示例。

示例：

参数名称	是否必填	类型	参数说明
apikey	是	string	用户开通接口后获得的密钥
ip	是	string	需要查询的 IPv4 或 IPv6 地址
lang	否	string	返回语言，默认 zh-CN

文档参数必须与接口代码或第三方上游实际接收的参数完全一致。

五、填写返回参数和状态码

“返回参数说明”用于生成前台接口文档。按真实响应逐项填写字段名称、类型和说明，例如：

参数名称	类型	参数说明
code	int	业务状态码
message	string	状态说明
data	object	返回数据

系统已经预置 100 至 109 等鉴权和计费错误码。可继续添加接口自己的业务状态码，但不要与现有状态码产生歧义。

六、选择计费模式

系统支持三种模式：

按量计费

每成功调用一次从用户余额中扣除接口价格。“接口价格”填写每次调用金额，例如：

0.01

包月计费

每行一个套餐，格式为“月数-金额”：

1-19.9
3-49.9
12-168
0-299

月数为 0 表示永久套餐。

点数包

每行一个套餐，格式为“次数-金额-到期天数”，例如：

1000-10-30
10000-80-365
50000-300-0

到期天数为 0 表示永久有效。套餐格式必须使用半角减号 -。

七、保存后的测试流程

1. 保存接口后，在接口列表确认分类、类型和状态正确。
2. 使用测试用户开通该接口。
3. 使用该用户的 apikey 发起真实请求。
4. 分别测试正常参数、缺少参数、错误参数和余额不足。
5. 检查 JSON、图片或文件响应是否与设置的返回格式一致。
6. 检查计费是否只在符合业务规则时扣除。
7. 检查前台接口文档中的参数和示例是否完整。
8. 全部通过后再正式对用户开放。

八、常见问题

官方接口访问 404

检查接口目录、入口文件和后台填写的接口地址是否一致。填写 ping/api.php 时，服务器上必须存在 api/ping/api.php。

第三方接口一直返回失败

检查上游地址、请求方式、固定参数、Token、成功参数和成功值。还要确认服务器防火墙和 DNS 能访问上游域名。

参数传到上游后为空

确认请求参数名称与上游要求完全一致，并检查 GET、POST 是否选反。固定参数必须使用 参数名|参数值 格式。

接口成功但系统判断失败

检查“成功参数”和“成功值”。上游返回 {"code":0} 时应填写 code 和 0，不要填写 HTTP 状态码 200。

图片或音视频无法正常显示

返回格式必须选择与实际内容对应的 img、audio/mp3 或 video/mp4，同时保证上游响应头和内容有效。

扣费配置不正确

重新确认计费模式和套餐格式。先使用测试账号、小额余额进行验证，禁止未测试就直接上线收费接口。