开发前必读

欢迎使用本项目的对外接口与接入文档。本页面为主页（Home），简要说明文档的用途与结构，帮助开发者快速定位所需内容。

接口域名

UAT环境: https://uat.bkj.com/openapi/v1/

生产环境: 请联系工作人员获取

本文档集合用于对外说明并指导合作方如何安全、规范地接入本系统的 API，包含以下主要内容：

请求头（Request Headers）规范：移动端与 Web 端需携带的头部字段及含义。

接口签名（Signature）机制：HMAC-SHA256 签名流程、规范化请求体、必需头与示例代码。

错误码（Error Codes）列表：API 返回的所有错误码及含义、处理建议与重试策略。

语言与区域（Accept-Language / Locale）：支持的语言代码（BCP 47）及使用说明。

时区（Timezone）说明：使用 IANA 时区（如 Asia/Shanghai），以及时区在展示时间上的用法与实现建议。

按“接口签名”文档实现请求签名（非 GET 请求需签名），并在请求头中附带 X-Signature、X-Timestamp、X-Nonce、X-Api-Key。

使用“错误码”文档映射并处理后端返回的 code，按建议进行重试或展示友好提示。

第三方集成工程师（mobile / web / backend）

产品与 QA（用于校验接入规范）

客服与运维（定位问题时参考错误码和日志字段）

签名：使用 HMAC-SHA256，签名字符串为：Method + Path + CanonicalizedBody + Timestamp + Nonce。每个合作方拥有独立 API key。

请求体规范化：忽略 null 与数组字段，对键排序并把数字规范为字符串。

时区格式：采用 IANA 时区（Region/City，如 Asia/Shanghai），系统内部以 UTC 存储并按用户时区展示时间（展示时附带 UTC±offset）。

语言格式：采用 BCP 47（如 en-US, zh-CN），通过 Accept-Language 头指定首选语言。

错误处理：参见错误码文档，401/Token 相关需引导用户重新登录；频率限制类错误建议展示重试倒计时。

如在接入过程中遇到问题，请准备好：请求示例（含全部 headers）、时间戳、nonce、签名字符串与返回的错误码，并联系项目技术支持团队以便快速定位问题。