开放 API 接入文档
ProtoHub 开放 API 允许你在自己的系统中调用协议解析与封包能力。所有接口通过 HMAC-SHA256 签名鉴权，与网页端共享点数账户。请先前往会员中心 → API 密钥创建 Access Key 与 Secret Key。
1. 基本信息
| Base URL | {API_BASE}/openapi/v1 |
| 鉴权方式 | HMAC-SHA256 签名（自定义 Header） |
| 数据格式 | application/json; charset=utf-8 |
| 响应信封 | {"code":0,"message":"ok","data":...} |
| 时间窗 | 签名时间戳与服务器相差不得超过 ±5 分钟 |
2. 签名算法
每次请求需携带三个 Header：X-Api-Key、X-Api-Timestamp（Unix 秒）、X-Api-Sign。签名串由 access_key、时间戳、请求体 MD5 三部分按换行符拼接后，用 secret_key 做 HMAC-SHA256，输出 hex：
sign = hex( HMAC-SHA256(
key = secret_key,
data = access_key + "\n" + timestamp + "\n" + md5_hex(body)
))- GET 请求或无请求体时，body 按空字符串计算 MD5（d41d8cd98f00b204e9800998ecf8427e）
- md5_hex 与 HMAC 输出均为小写 hex 字符串
- body 必须是原始请求字节，不要在序列化后二次修改
3. 调用示例
3.1 curl（bash 计算签名）
AK="你的_access_key"
SK="你的_secret_key"
TS=$(date +%s)
BODY='{"protocol_slug":"modbus-tcp","hex_input":"00010000000601030000000A"}'
BODY_MD5=$(printf '%s' "$BODY" | md5sum | cut -d' ' -f1)
SIGN=$(printf '%s\n%s\n%s' "$AK" "$TS" "$BODY_MD5" | openssl dgst -sha256 -hmac "$SK" | cut -d' ' -f2)
curl -X POST "http://localhost:8080/openapi/v1/parse" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $AK" \
-H "X-Api-Timestamp: $TS" \
-H "X-Api-Sign: $SIGN" \
-d "$BODY"3.2 Python（requests）
import hashlib, hmac, time, json, requests
API = "http://localhost:8080/openapi/v1"
AK, SK = "你的_access_key", "你的_secret_key"
def call(path: str, payload: dict):
body = json.dumps(payload, separators=(",", ":"))
ts = str(int(time.time()))
body_md5 = hashlib.md5(body.encode()).hexdigest()
sign = hmac.new(
SK.encode(), f"{AK}\n{ts}\n{body_md5}".encode(), hashlib.sha256
).hexdigest()
r = requests.post(
API + path,
data=body,
headers={
"Content-Type": "application/json",
"X-Api-Key": AK,
"X-Api-Timestamp": ts,
"X-Api-Sign": sign,
},
timeout=30,
)
return r.json()
# 解析报文
print(call("/parse", {"protocol_slug": "modbus-tcp",
"hex_input": "00010000000601030000000A"}))
# 自然语言封包
print(call("/encode", {"protocol_slug": "modbus-tcp",
"description": "读取保持寄存器，起始0，数量10"}))4. 接口列表
POST /openapi/v1/parse — 报文解析
| 请求体 | {"protocol_slug":"modbus-tcp","hex_input":"0001..."} |
| 响应 data | 解析卡片 JSON（engine / summary / fields / errors / suggestions） |
| 计费 | 公共协议免费；私有协议按点数扣费（默认 2 点/次） |
POST /openapi/v1/encode — 自然语言封包
| 请求体 | {"protocol_slug":"modbus-tcp","description":"读取保持寄存器…"} |
| 响应 data | 封包卡片 JSON（engine / hex / breakdown / notes / errors） |
| 计费 | 同 /parse |
GET /openapi/v1/quota — 配额查询
| 响应 data | {"quota_per_day":1000,"used_today":12,"credit_balance":88} |
| 计费 | 免费 |
5. 计费说明
- 点数与网页端共用同一账户，余额不足时返回 40201，可在会员中心充值
- 公共协议（is_public=true）解析 / 封包免费
- 私有协议按次扣点，单价由系统设置 cost.parse_private / cost.encode_private 决定（默认 2 点/次）
- 每个 API Key 有每日调用配额（quota_per_day），超限返回 40303
6. 错误码表
| 错误码 | 含义 | 处理建议 |
|---|---|---|
| 0 | 成功 | — |
| 40001 | 参数错误（hex 格式非法、缺字段等） | 检查请求体 |
| 40101 | 签名无效或密钥不存在 | 核对签名串与时间戳 |
| 40102 | 时间戳超出 ±5 分钟窗口 | 校准服务器时间 |
| 40201 | 点数余额不足 | 前往会员中心充值 |
| 40301 | 无权限访问该私有协议 | 确认协议归属 |
| 40303 | 超出 API Key 每日配额 | 次日重试或联系管理员 |
| 40401 | 协议不存在 | 检查 protocol_slug |
| 50001 | 服务端内部错误 | 稍后重试并保留订单号/请求 ID |