1. 接入准备
环境地址、应用密钥与请求签名
环境地址
请求头
Authorization: Bearer <accessToken> X-AF-App-Id: af_android X-AF-Timestamp: 1785267600 # 秒级，偏差需 < 300 秒 X-AF-Nonce: f3a9c1e07b2d4 # 随机串，5 分钟内不可重复 X-AF-Sign: <签名值> X-AF-Client-Ver: 4.2.1 # 用于兼容性过滤，务必带上 X-AF-Device-Id: <设备唯一标识>
签名算法
raw = METHOD + "\n" + PATH + "\n" + SORTED_QUERY + "\n" + BODY_MD5 + "\n" + TIMESTAMP + "\n" + NONCE sign = HMAC_SHA256(raw, APP_SECRET) // hex lowercase
SORTED_QUERY：query 按 key 升序拼k=v&k=v，无参数为空串BODY_MD5：请求体 MD5（hex lowercase），GET 或空体为空串- 签名错误
40101，时间戳超窗40102，nonce 重放40103
2. 通用约定
响应结构、分页、限流、幂等与单位
统一响应
RESPONSE
{
"code": 0,
"message": "ok",
"data": {},
"requestId": "req_9f2c7b1e4a8d",
"serverTime": 1785267600
}
requestId 请在客户端日志保留，排查问题时提供。
分页响应
PAGINATION
{
"list": [],
"page": 1,
"pageSize": 20,
"total": 12840,
"hasMore": true,
"cursor": "eyJpZCI6InAyMDAxIn0"
}
列表页用 page，社区信息流用 cursor（避免新内容插入导致翻页重复）。
限流
| 维度 | 限制 | 超限返回 |
|---|
时间
统一秒级 Unix 时间戳（int），客户端自行转本地时区
金额
统一为分（int），16800 表示 ¥168.00；积分为整数
幂等
下单、支付、提现带
Idempotency-Key，重复提交返回首次结果Webhook 回调
平台向你配置的地址推送事件，带签名与重试
请求格式
POST <你的回调地址>
X-AF-Event: order.status_changed X-AF-Event-Id: evt_9f2c7b1e X-AF-Timestamp: 1785267600 X-AF-Signature: <hmac_sha256(body, secret)> { "eventId": "evt_9f2c7b1e", "event": "order.status_changed", "createdAt": 1785267600, "data": { "orderId": "AF20260729001", "fromStatus": "working", "toStatus": "review", "operator": "creator" } }
验签与重试
VERIFY
expected = HMAC_SHA256(raw_body, secret) // hex lowercase，比对 X-AF-Signature // 不一致直接丢弃
事件列表
状态机
订单、审核与提现的状态流转规则
订单状态流转
各状态允许的操作
| 状态 | 含义 | 买家可做 | 剪辑师可做 |
|---|
自动流转
审核状态机
AUDIT
draft ──提交──> pending ──通过──> passed
│ │
│ 下架
│ ▼
│ offline
│ │
驳回 恢复上架
▼ │
rejected <─────────────┘
│
修改重提 └──> pending
提现状态机
WITHDRAW
pending ──风控通过 + 打款──> paid
│
└──驳回──> rejected
// 金额退回余额
枚举字典
客户端对未知枚举做兜底展示，优先用服务端下发的 xxxName 字段
客户端集成
版本兼容、深链、导入流程、缓存与埋点
版本兼容性是投诉最高的一类问题
用户下载到无法导入的预设时会直接给差评。请务必在列表请求传
maxVersion，
并用响应里的 compatible 决定按钮态。
兼容性处理顺序
深链 Deep Link
客户端需注册 autfeng:// scheme，建议同时配置 Universal Link / App Links 作为降级。
导入流程
缓存策略
| 数据 | 建议缓存 | 失效策略 |
|---|
CONDITIONAL GET
GET /resources?category=transition If-None-Match: "W/9f2c7b1e" // 未变更返回 304，不消耗流量
WebView 内嵌
Hub 页面会被客户端 WebView 内嵌，需注意：
埋点事件
POST /analytics/events
{
"events": [
{ "event": "resource_view",
"props": { "resourceId": "p_2001", "from": "category" },
"ts": 1785267600 },
{ "event": "import_result",
"props": { "resourceId": "p_2001", "success": true },
"ts": 1785267640 }
]
}
错误码
HTTP 状态码看传输层，业务 code 看业务层
| code | 含义 | 建议处理 |
|---|
变更日志与兼容承诺
v1.0.0 · 2026-07-29 首个正式版本
兼容性承诺