常量字典
下面是 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 恢復 |