前置条件
账号已完成实名;已开通开放平台权限;已准备服务器出口 IP,用于配置白名单。生产环境请使用独立应用,不要与测试共用密钥。
操作步骤
- 进入开放平台控制台,创建应用,填写应用名称、用途与回调地址。
- 系统生成 AppKey 与 AppSecret。AppSecret 只在创建时完整展示,请立即保存到服务端密钥管理,不要写入前端或代码仓库。
- 配置 IP 白名单,只允许业务服务器出口 IP 调用。
- 按接口文档拼接签名串:通常包含请求方法、路径、时间戳、随机串与请求体,使用 AppSecret 做 HMAC-SHA256,将结果放入签名头。具体拼接顺序以开放平台文档为准。
- 每个请求携带 AppKey、时间戳、随机串与签名;写操作额外携带幂等键,幂等键有效期 24 小时。
- 先调用一个查询类接口(如产品列表或账户信息)验证连通性,再接入下单与查询接口。
结果验证
接口返回 200 与业务数据;错误响应包含错误码与可读消息,不包含成本、毛利或供给源等内部信息。可在开放平台查看调用日志与配额使用情况。
出问题怎么办
- 401:检查 AppKey、签名与时间戳;确认 AppSecret 未填错。
- 403:检查 IP 白名单与接口权限。
- 429:触发限流,按返回的重试建议退避,不要密集重试。
- 409:幂等键重复,确认是否重复提交同一业务请求。
注意:开放平台为独立网关,接口路径、签名串格式与错误码以官方接口文档为准。
常见报错与处理
签名一直不通过 原因:签名串拼接顺序错误、时间戳过期或请求体被二次编码。
处理:严格按文档拼接,使用原始请求体参与签名,校准服务器时间。
AppSecret 泄露 原因:密钥写入前端代码或提交到仓库。
处理:立即在开放平台重置密钥,改为服务端调用。
重复下单 原因:网络重试未携带同一幂等键。
处理:同一业务请求复用同一幂等键,24 小时内有效。