所有 API 请求（包括出站调用和入站 Webhook）均使用以下三个必填请求头。
必填请求头
| 请求头 | 说明 |
|---|---|
| X-PARTNER-ID | 入驻时提供的客户端密钥 |
| X-TIMESTAMP | 当前时间戳，采用 ISO8601 格式（例如：2024-12-19T17:07:05+07:00） |
| X-SIGNATURE | 根据请求参数生成的 RSA 签名（参阅签名生成） |
签名方式
API 使用非对称加密（Asymmetric Without Get Token）方法，遵循印度尼西亚央行制定的安全标准。您无需发起额外的 Token 请求，签名通过 X-SIGNATURE 请求头随每次请求一并发送。
完整算法和代码示例请参阅签名生成。
时间戳规则
当 X-TIMESTAMP 不符合以下规则时，API 将以错误码 40001001 拒绝请求：
| 规则 | 错误信息 |
|---|---|
必须为带有明确时区偏移的 ISO 8601 格式：+07:00、+0700 或 Z。允许包含小数秒（例如：2024-12-19T10:07:05.123Z）。 |
Invalid X-TIMESTAMP format |
| 必须与服务器时间相差在 ±5 分钟以内。请保持服务器时钟同步（NTP）。 | X-TIMESTAMP outside allowed window |
每次请求都应生成新的时间戳，请勿复用之前请求的时间戳或签名。
错误响应
当必填请求头缺失或无效时，API 返回 HTTP 400（而不是 401）及错误码 40001001：
{
"error": {
"code": 40001001,
"message": "Invalid X-SIGNATURE value"
}
}
| 错误信息 | 原因 |
|---|---|
Invalid X-TIMESTAMP |
缺少 X-TIMESTAMP 请求头 |
Invalid X-PARTNER-ID |
缺少 X-PARTNER-ID 请求头 |
Invalid X-PARTNER-ID NOT LISTED |
X-PARTNER-ID 与已登记的客户端密钥不匹配 |
Invalid X-SIGNATURE |
缺少 X-SIGNATURE 请求头 |
Invalid X-TIMESTAMP format |
参阅时间戳规则 |
X-TIMESTAMP outside allowed window |
参阅时间戳规则 |
Invalid X-SIGNATURE value |
签名与请求不匹配。参阅签名生成 |
请根据 HTTP 状态码和 error.code 进行判断。message 的措辞可能会变更。
在生产环境中，IP 白名单校验先于上述校验执行，因此部分请求会更早被拒绝，并返回不同结构的响应体。参阅 IP 白名单。