常量字典
下面是 OpenAPI v1.2 所有"不会变"的值。任何破坏性变更都会通过 changelog + 版本号公告，并提前通知集成方。
Base URL
| 环境 | URL |
|---|---|
| 生产 | https://api.coinepay.net |
| 沙箱 | 暂无（v1.2 不提供） |
| 本地开发 | http://localhost:8801 |
API 前缀
/api/v1/openapiHTTP 约定
| 项 | 值 |
|---|---|
| Method | 全部 POST（项目硬性约束） |
| 请求 Content-Type | application/json |
| 响应 Content-Type | application/json; charset=utf-8 |
| 最大请求体 | 4 MB（4194304 字节） |
| 字符集 | UTF-8 |
鉴权
| 项 | 值 |
|---|---|
| 算法 | HMAC-SHA256 |
| 必需 header | X-App-Id / X-Timestamp / X-Nonce / X-Signature |
| AppID 格式 | cp_<28 hex>，固定长度 31 |
| Secret 格式 | 64 hex 字符 |
| Secret 前缀展示 | <前 4 字符>**** |
| Timestamp 单位 | 秒（不是毫秒） |
| 时间戳容差 | ±300 秒 |
| Nonce 长度 | 8~64 字符 |
| Nonce 防重放窗口 | 600 秒 |
| 签名格式 | lowercase hex |
| 签名长度 | 64 字符 |
幂等
| 项 | 值 |
|---|---|
| Header | Idempotency-Key |
| 必填接口 | /api/v1/openapi/card/apply / /api/v1/openapi/card/recharge |
| 最大长度 | 128 字符 |
| 去重窗口 | 24 小时 |
| 冲突状态码 | 409 |
限流
| 项 | 值 |
|---|---|
| 维度 | (AppID, IP) |
| 配额 | 600 / 分钟 |
| 窗口 | 60 秒（滚动） |
| 超出 | HTTP 429 |
Webhook 推送
| 项 | 值 |
|---|---|
| 签名 header | Webhook-Signature |
| 签名格式 | v1,<hex_hmac_sha256> |
| 签名输入 | {timestamp}.{raw_body} |
| 事件 ID header | Webhook-Id |
| 时间戳 header | Webhook-Timestamp |
| 类型 header | Webhook-Type |
| 重试退避（秒） | [60, 300, 900, 3600, 21600, 86400] |
| 总投递次数 | 7（1 次首投 + 6 次重试，之后 dead_letter） |
| 接收方响应头超时 | 5 秒 |
| 接收方整请求总超时 | 10 秒 |
| 必须 HTTPS | ✅（生产；dev 环境 AllowHTTP=true 时方可放行 HTTP） |
| 必须公网 IP | ✅（拒绝私网 / loopback / link-local） |
| 允许端口 | 生产环境仅 443 |
卡类型（v1.2 OpenAPI 范围）
| card_type | 说明 |
|---|---|
virtual_l | 虚拟卡 - L 类 |
virtual_p | 虚拟卡 - P 类 |
virtual_v | 虚拟卡 - V 类 |
virtual_r | 虚拟卡 - R 类 |
virtual_g | 虚拟卡 - G 类 |
virtual_a | 虚拟卡 - A 类（邮箱必填、不收手机号，见申请虚拟卡） |
OpenAPI 不接受非虚拟卡
master_e / visa_h / transfer 等不在范围内，会返回 400 openapi_card_type_not_supported。
apply 接口不传 card_type
/card/apply 不需要传 card_type，由 header_id 自动推导。
业务前缀
| 资源 | 前缀 | 示例 |
|---|---|---|
| 卡 | card_ | card_12345 |
| 套餐 | pkg_ | pkg_67 |
| 卡头 | hdr_ | hdr_5 |
| 充值订单 | txn_ | txn_OO20260429110012abc |
| Webhook 事件 | evt_ | evt_550e8400-e29b-41d4-a716-446655440000 |
常用 SHA-256 常量
| 输入 | sha256 hex |
|---|---|
| 空字符串 | e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 |
{} | 44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a |
国际化
| Header | 行为 |
|---|---|
Accept-Language 不传 | 默认中文 |
Accept-Language: zh-CN | 中文 |
Accept-Language: en-US | 英文 |
message_key 不受 Accept-Language 影响，永远稳定（用作程序判断）。
凭证
| 项 | 值 |
|---|---|
| 凭证有效期 | 不过期（除非 reset / disable） |
| 凭证数量上限 | 每用户 1 条（v1） |
| Reset 后旧 secret | 立即失效 |
| Disable 后 | 401 invalid_credentials；可 enable 恢复 |