自动发卡失败怎么区分接口与配置原因

自动发卡失败不能一律归为“货源没货”，接口状态、回调地址、库存绑定都会影响最终结果。先区分“交易成功但卡密没到用户”与“订单根本没有创建”，再进入具体环节，避免把重新下单或重复补发作为排查手段。

先确认失败出现在哪个环节

先看支付端和商户后台的结果是否一致。若支付已完成，但后台没有订单，优先核对下单时使用的商城订单号、登录身份、查单手机号，并使用原订单编号查询，不要用支付渠道流水号代替。换设备或清除浏览器数据后本机记录为空，不代表订单已删除，必须回到原账户和原订单号。

若后台存在订单，但orderState没有进入发卡成功，接下来要区分是“明确失败”还是“结果不确定”。明确失败通常伴随明确的接口返回，例如PURCHASE_SCHEMA_CHANGED，表示下单模板已更新，此时应重新查询商品下单模板，并使用原来的clientOrderRef再次提交。结果不确定时不能直接补卡，先查原订单日志及渠道结果，避免重复发卡或重复到账。

接口校验应排在配置调整之前

接入自动发卡前，本地表单与平台模板必须一致。创建本地商品时，先调用 GET /goods/{productRef} 获取详情和规格；需要销售的规格再调用一次 GET /goods/tpl，保存返回的下单模板并生成本地下单表单。单规格商品只传 productRef，多规格商品必须同时传 variantRef，且 units 必须等于实际数量。

网络超时或未收到明确结果时，只能复用原 clientOrderRef 和原下单内容重试。平台会返回第一次创建的原订单，不会再次扣款或重复下单；改成其他商品、规格、数量或充值资料会返回 IDEMPOTENCY_CONFLICT。不能通过更换 orderCallbackUrl 来修正已建订单，重试传入不同地址也不会修改原订单，仍以第一次保存的地址为准。

库存类失败要区分货源类型与绑定状态。卡密、卡号加卡密、固定卡密与充值货源用途不同，导入卡密不等于已经完成商品绑定。需核对导入格式、有效可售数量、货源启用状态，并确认货源已绑定到正确商品或规格。多货源策略也要按后台实际配置理解，不能用货源列表排序推断每一单必走某个渠道。

回传中断要按地址与响应逐层排查

订单已成功创建时，卡密未到用户通常与回传链路有关。orderCallbackUrl 填写后，订单、卡密、退款及关联售后消息优先发送到该地址；未填写时，每条消息生成时读取当时的默认回调地址。同一条消息只选择一个地址并固定下来，之后修改默认地址不会改变已经生成的消息；两个地址都没有时不发送该条 Webhook，订单仍正常创建，第三方只能通过查询接口获取结果。

回调地址必须使用公网 HTTPS，不能包含用户名、密码、# 片段或 IP 地址，也不能返回 HTTP 跳转。接收方收到消息后要检查 JSON 格式和必填字段，保存 eventId；同一个 eventId 再次收到时不得重复发卡、记录退款或追加售后消息。卡密必须先安全保存，再交给后续发货流程。

Webhook 响应有严格判定：只有 HTTP 状态为 200，且响应正文去除首尾空白后忽略大小写等于 OK，才算成功。其他状态、空正文、JSON、其他文本、超时或连接失败均视为失败。例如，接收方返回了 200 但正文是 JSON，系统仍会重试，卡密也可能因此延迟到达。

排查顺序与验证标准

• 第一步：核对订单：用商城订单号、原会员账户或查单手机号查询，确认订单是否创建、扣款是否完成、orderState 当前状态。
• 第二步：核对模板与参数：出现 PURCHASE_SCHEMA_CHANGED 时，重新查询 /goods/tpl，更新本地表单后复用原 clientOrderRef。
• 第三步：核对库存与绑定：检查可售数量、货源类型、启用状态及商品或规格绑定，不只看总库存。
• 第四步：核对回传：确认订单地址或默认地址存在且为 HTTPS，检查接收端是否返回标准 OK，并用 eventId 防止重复处理。
• 第五步：只读验证：处理后通过订单详情或商品查询接口确认状态与卡密结果，不要直接重发同一批卡密。

该判断不适用于仅凭支付渠道显示“已支付”就认定发卡完成的场景；支付成功不等于订单创建，也不代表卡密已生成。若订单确实未创建，应回到下单参数、模板版本与余额校验，不要尝试关闭安全校验或绕开幂等规则，否则会破坏订单与资金的对应关系。

参考资料：接入指南（2026-09-20）；订单查不到怎么办（2026-10-18）；创建订单（2026-08-31）；库存与发货异常（2026-10-18）。具体操作与适用范围以对应文档为准。