团队 API
团队 API 认证与签名
团队 API 的 Access Key、Access Secret、请求头和 HMAC-SHA256 签名规则。
团队 API 认证与签名
适用范围
本页仅适用于团队 API。WaaS / 支付引擎 API 使用不同的认证方式和错误码体系，请勿混用。
团队 API 使用 Access Key + Access Secret 完成身份认证，并采用 HMAC-SHA256 算法对请求进行签名。该机制与 WaaS / Payment Engine 的 body 参数签名不同。
请求规范
团队 API 统一采用 HTTPS 协议进行通信，所有接口均使用 POST 请求。每个团队拥有独立的 Base URL，所有请求均需发送至对应 Base URL。
https://{team-domain}/openapi/...Base URL 请前往 Cregis App > 管理 > API管理 > API详情页面查看。调用时无需传递 Team ID，系统会根据访问域名自动识别所属团队。
请求头
所有团队 API 请求均需携带以下请求头：
Access-Key: <access_key>
Access-Timestamp: <unix_millis>
Access-Nonce: <random_nonce>
Access-Signature: <hmac_sha256_signature>| Header | 必须 | 说明 |
|---|---|---|
| Access-Key | 是 | API Key 标识，用于标识调用方身份 |
| Access-Timestamp | 是 | Unix 毫秒时间戳 |
| Access-Nonce | 是 | 随机字符串，用于防止请求重放 |
| Access-Signature | 是 | 使用 Access Secret 计算得到的请求签名 |
鉴权机制
每次请求，服务端将依次校验请求头、Access Key、时间窗口、Nonce、签名以及 API 权限。只有全部校验通过后，请求才会继续处理。
时间戳与 Nonce
- Access-Timestamp 使用 Unix 毫秒时间戳，默认允许客户端与服务端时间误差为 ±300 秒。
- Access-Nonce 建议长度为 16～64 位，每次请求必须生成新的随机字符串。
- 同一个 API Key 在有效时间窗口内不得重复使用相同的 Nonce。
签名算法与签名原文
所有团队 API 均采用 HMAC-SHA256 签名算法，签名结果使用小写十六进制 Hex 字符串。签名原文固定由以下四部分组成，每部分使用换行符（\n）连接：
PATH
TIMESTAMP
NONCE
BODY| 字段 | 来源 | 说明 |
|---|---|---|
| PATH | 请求路径 | 不包含协议、域名及 Query 参数，例如 /openapi/team/info |
| TIMESTAMP | Access-Timestamp | 必须与请求头保持一致 |
| NONCE | Access-Nonce | 必须与请求头保持一致 |
| BODY | 原始请求体 | 无请求体时为空字符串 |
签名示例
请求：POST /openapi/team/profile，请求体如下：
{"name":"Demo Team"}构建签名原文：
/openapi/team/profile
1717380000000
9f7c6a2b47e34f19
{"name":"Demo Team"}以上四个参数按顺序换行拼接后，使用 Access Secret 执行 HMAC-SHA256 运算，并将结果转换为小写 Hex 字符串，作为 Access-Signature 请求头发送。
Body 参与签名规则
- 所有业务参数均放置于 JSON 请求体中，不建议使用 Query String 传递业务参数。
- 请求体为空时，BODY 使用空字符串参与签名。
- 请求体不为空时，应使用原始请求体参与签名。
- 请求体内容必须与签名时保持完全一致，否则签名校验将失败。
- Body 需遵循 RFC 8785 JSON Canonicalization Scheme（JCS）进行规范化，确保对象属性排序、空白字符、数字编码、转义规则和嵌套结构在不同系统中保持一致。