DEVELOPER ACCESS / V1

开放接入

为授权销售渠道提供商品目录、订单发卡与状态查询接口。卡密由权益发行方签发并判定兑换资格，销售平台负责收款和交付。

查看接口提交接入申请

天火 / All-PAY 星桥工作台

虚构示例 · 不可兑换

星桥工作台、示例订单和卡密均为演示数据，不代表已接入商家，也无法用于购买或兑换。实际发行方需完成审核与生产配置。

01 / ONBOARDING

接入流程

01
提交申请
填写经营主体、商品授权与技术联系人。
02
审核与开通
运营核验售卖范围，由发行方发放独立渠道凭证。
03
联调验收
校验目录、支付发卡、幂等重试、查询和错误边界。
04
生产切换
先部署发行方接口，再配置天火服务端密钥并开启新订单发卡。

申请批准不等于自动开通生产发卡。渠道凭证由发行方运营人员单独创建，审核记录只保存渠道 ID，不保存密钥。

02 / AUTHENTICATION

服务端凭证

每家渠道有独立的 merchantId 和密钥。所有请求使用 HTTPS，并在请求头发送 x-merchant-id、x-merchant-key。凭证只放在服务端环境变量，不放进网页、客户端或 URL。

密钥轮换后旧密钥立即失效；停用渠道只阻止新发卡，已售订单仍可查询。

虚构示例 · 环境变量

CARD_ISSUER_URL=https://issuer.example.com
CARD_MERCHANT_ID=mch_<审核后发放>
CARD_MERCHANT_KEY=cmk_<仅显示一次>

03 / API REFERENCE

卡密接口

以下使用虚构的星桥工作台说明接口字段。https://issuer.example.com 是不可调用的示例域名；实际地址与凭证在审核通过后提供。

方法	路径	用途
GET	`/api/integrations/cards/catalog`	读取允许售卖的首充和日常规格
POST	`/api/integrations/cards/issue`	支付确认后，按渠道订单号生成卡密
POST	`/api/integrations/cards/status`	按渠道订单号查询卡密及使用状态
POST	`/api/integrations/cards/statuses`	批量查询 1–50 笔渠道订单
POST	`/api/integrations/cards/void`	作废未兑换的卡密

按订单幂等

同一渠道和订单号只会生成一张卡。同订单改类型或售价返回 409，不会重复发卡。

发行方判定资格

首充或日常等兑换条件由权益发行方判定，销售平台不得只根据购买邮箱推断资格。

查询为准

卡状态为 UNUSED、USED、VOID 或 EXPIRED。网络超时后用原订单号重试或查询。

虚构示例 · 发卡请求

curl -X POST "$CARD_ISSUER_URL/api/integrations/cards/issue" \
  -H "Content-Type: application/json" \
  -H "x-merchant-id: $CARD_MERCHANT_ID" \
  -H "x-merchant-key: $CARD_MERCHANT_KEY" \
  -d '{"orderNo":"STAR-DEMO-0001","type":"daily","priceCents":3000}'

虚构示例 · 发卡响应

{
  "ok": true,
  "data": {
    "orderNo": "STAR-DEMO-0001",
    "code": "XQ-DEMO-7Q2M-9K4P",
    "type": "daily",
    "priceCents": 3000,
    "credits": 300,
    "expiresAt": 1948752000000,
    "status": "UNUSED",
    "redeemedAt": null
  }
}

虚构示例 · 查询请求

curl -X POST "$CARD_ISSUER_URL/api/integrations/cards/status" \
  -H "Content-Type: application/json" \
  -H "x-merchant-id: $CARD_MERCHANT_ID" \
  -H "x-merchant-key: $CARD_MERCHANT_KEY" \
  -d '{"orderNo":"STAR-DEMO-0001"}'

查询边界

查询使用渠道订单号，不提供任意卡密搜索。渠道只能查询自己的订单；未知订单返回 404。批量查询结果按 orderNo 关联，不保证与请求顺序一致。

orderNo 长度 1–120，只允许字母、数字、点、下划线、冒号和连字符。发卡请求只传 type 与 priceCents，到账权益由发行方目录决定。

04 / FAILURE CONTRACT

错误与重试

成功统一返回 { ok: true, data }；错误包含可读消息、稳定错误码、是否可重试和请求编号。请依据 code 分支，不解析中文消息。

HTTP	code	处理
400 / 413	INVALID_*、SKU_NOT_ALLOWED、BODY_TOO_LARGE	修正请求，禁止原样重试
401	AUTH_INVALID	核对渠道开通、停用及密钥轮换
404	ORDER_NOT_FOUND、ENDPOINT_NOT_FOUND	核对订单归属和接口路径
409	ORDER_CONFLICT、ALREADY_REDEEMED	停止自动发卡，转人工核对
429 / 503 / 500	RATE_LIMITED、ISSUE_UNAVAILABLE、INTERNAL_ERROR	保留订单号，退避重试

错误响应 · 409

{
  "ok": false,
  "error": "渠道订单号已用于其它充值规格",
  "code": "ORDER_CONFLICT",
  "retryable": false,
  "requestId": "a1b2c3d4"
}

没有收到响应不等于发卡失败。用相同订单号重试 /issue 或查询 /status；不能换订单号再次发卡。收款后的非重试错误进入人工处理。

05 / PILOT

指挥官试点

真实联调试点，与上方“星桥工作台”虚构示例无关。

天火在创建指挥官商品订单前核对指挥官目录，锁定订单类型、售价和到账点数。收款回调验签后向指挥官领卡，买家用订单号与查询密码领取。卡的真实使用状态由指挥官返回。

已售 ZP- 旧卡继续沿原链路兑付；新卡只在指挥官签发模式开启后产生。退款或已兑换卡的补偿需要人工账务核对，不能删除订单或直接修改卡状态。

天火商城商品 / 收款 / 交付

指挥官签发 / 兑换 / 账本

06 / APPLY

申请接入

提交经营主体、商品授权与技术联系人。运营审核后再安排试点联调与渠道凭证发放。

查看商家入驻说明

开放接入

接入流程

提交申请

审核与开通

联调验收

生产切换