快速开始

最短路径完成第一次成功调用

快速开始

模组工坊 Open API 让你能以编程方式访问平台上的资源、用户内容、Webhook 通知等能力。本章介绍最短路径到第一次成功调用。

1. 申请应用

进入我的应用页面，点击「申请新应用」并填写：

应用名称（2-100 字符）
应用描述（可选）
应用主页（可选）

提交后等待管理员审核。审核通过后会颁发 API Key + Secret Key。

2. 准备调用要素

每次请求必须携带以下 4 个请求头：

Header	说明
`X-API-Key`	你的 API Key
`X-Timestamp`	当前毫秒级 Unix 时间戳
`X-Signature`	Base64( HMAC-SHA256( secret, StringToSign ) )
`X-Proxy-User-Id`	（可选）代理用户 ID

StringToSign 格式：

METHOD\nPATH\nTIMESTAMP

例如调用 GET /openapi/v2/section/list?pageNum=1，TIMESTAMP=1735000000000：

GET
/openapi/v2/section/list
1735000000000

签名算法详见签名章节。

3. 你的第一个请求

TS=$(date +%s%3N)
SIG=$(printf "GET\n/openapi/v2/section/list\n${TS}" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)

curl "https://api.example.com/openapi/v2/section/list" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

成功响应统一用 ResponseDTO 包裹：

{
  "code": 0,
  "ok": true,
  "msg": "操作成功",
  "data": [ { "sectionCode": "minecraft", "sectionName": "我的世界" }, ... ]
}

4. 推荐下一步

认证与 API Key — 详细说明 Key/Secret 的分发与轮换
签名详解 — HMAC-SHA256 各语言代码示例
限流策略 — 100 次/分 + 10000 次/天的默认配额
错误处理 — 错误码 200001-200999 速查
Webhook 集成 — 让平台主动推送事件给你

也可以直接打开在线沙箱选一个接口立即试调用。

5. 调通前的自查清单

第一次接入时，按下表逐项确认，可以避开多数常见问题：

请求头三件套齐全：X-API-Key / X-Timestamp / X-Signature
X-Timestamp 是毫秒级 Unix 时间戳（13 位），不是秒级（10 位）
StringToSign 用单个换行符 \n（0x0A）拼接，顺序为 METHOD\nPATH\nTIMESTAMP
PATH 只含纯路径，不含 host、不含 query 串
用 Secret Key（不是 API Key）作为 HMAC 密钥，结果做 Base64（不是 hex）
本机时钟与标准时间相差在 5 分钟以内
应用状态为「已通过」

HTTP 请求头名大小写不敏感，X-API-Key 与 x-api-key 等价；但签名串里的 METHOD 必须大写。

调不通时优先在在线沙箱用同一接口跑一遍——沙箱由浏览器替你完成签名，能快速区分是「签名实现问题」还是「参数问题」。

下一章 →认证与 API Key