虚拟商品发货总出错，从校验源头查起

虚拟商品发货错误，最常见的情况是订单已支付，但发出的卡密或直充结果不对，排查时又难以定位到具体环节。判断发货错误，不能只看订单是否标记成功，要先把商品、规格与发货链路作为校验重点，确认三者匹配再推进交付。

发货前必须核对的关联项

发货错误的根源，常是商品与实际交付配置不一致。做任何调整前，先把商品关联关系梳理清楚，避免在错误配置上反复操作。

先确认商品本身可正常采购。调用 GET /goods/catalog 查询可采购商品，确认目标商品当前订阅状态正常、未到到期时间，且商品详情里标注了适用的发货方式。例如原本配置为卡密发货的商品，实际却关联了直充货源，订单生成后自然会发错。

再核对规格匹配。单规格商品只需确认 productRef 与本地商品一致，多规格商品要同时确认 productRef 与 variantRef 与买家下单的规格完全一致。规格不匹配时，即便订单能创建，后续货源匹配也会错位。

最后核对发货规则。直充商品需在关联渠道明确绑定本站货源，卡密商品需指定卡密仓库并配置对应发货规则，自动采购还需单独具备 API 权限。只要其中一项缺失，就可能在发货环节出现错误。

调整发货配置的可执行步骤

确认关联问题后，按顺序调整配置，每步完成后做一次本地记录，便于后续核对。

第一步，重新拉取商品模板。调用 GET /goods/tpl 获取商品下单模板，确认模板里的规格选项、发货方式与本地销售配置一致。若模板与本地配置有差异，以最新模板为准更新本地表单。

第二步，调整货源关联。在闲管家或货源管理中，重新把商品绑定到对应的货源。直充商品确认关联的是本站直充货源，卡密商品确认选择的是对应卡密仓库，绑定完成后保存并查看返回的关联状态。

第三步，设置发货规则。为卡密商品明确发卡规则，包括卡密来源、发放顺序，为直充商品确认充值账号取值来源。规则生效后，用一笔测试订单走一遍完整下单与发货流程，验证发出的卡密或充值结果与商品标注一致。

发货错误出现后的排查顺序

已经出现错发时，不要先重发，按以下顺序排查，避免重复错发。

先核对订单详情。调用 GET /orders/{clientOrderRef} 查询订单详情，确认订单中商品、规格、支付状态是否与买家实际下单一致，若订单本身信息就错了，先修正商品与规格关联，再处理订单。

再核对既有交付结果。把渠道订单与本站订单对应起来，先查看渠道侧返回的交付结果，确认是明确失败、错发还是未交付，明确失败且未交付时，再通过补发或退款处理，不直接重复发卡。

最后核对 Webhook 内容。收到卡密、订单等 Webhook 时，先检查事件格式和必填字段，保存 eventId，确认卡密内容与订单商品匹配后再进入发货流程。若发现 eventId 重复或卡密内容不符，不要再次发卡，先回查订单与货源状态。

完成调整后的验收标准

调整完成后，用明确的可观察结果确认发货错误是否减少。

一是测试订单准确交付。完成调整后，选取卡密、直充两类商品分别下一单，确认收到的卡密有效、直充结果与商品标注一致，且订单状态、交付内容、买家收到的内容三者完全对应。

二是订单与货源状态同步。后续订单创建后，货源侧显示的交付状态与本站订单状态一致，未出现订单已支付但货源未匹配的情况，说明关联配置已生效。

三是重复与错发情况消失。连续抽取若干笔近期订单，核对卡密内容、充值结果，未再出现规格不符、卡密错发的问题，即说明发货配置调整到位，后续可按此标准维持。

参考资料：接入指南（2026-09-20）；店铺与电商接入疑问（2026-10-18）；电商店铺与选品（2026-10-18）。具体操作与适用范围以对应文档为准。