货源对接应覆盖目录、商品、规格、价格、下单字段和数量规则，随后接入付款后的采购、原订单回查及交付。本轮改造正在验收，正式版本号、发布范围及安装状态以发布回执为准；本说明不表示客户已安装或全部真实上游已经验收。
使用流程
- 添加正确渠道类型、HTTPS 地址及该平台采购账号凭据，完成连接测试。
- 点击“一键对接”。任务自动继承上游目录和子目录；易客按用户确认的范围，只使用一级采购目录。
- 选择加价模板和图片保存方式。“对接完成后自动上架”默认勾选；不勾选时保留为草稿。
- 已知商品资料和数量规则准备齐全后，任务创建商品及规格，并执行上架校验。可关闭窗口，随后读取后台持久任务进度。顾客付款后才执行采购。
同一上游父商品的兼容规格保留在一个本地商品中，每个规格有独立价格、库存和上游绑定。不同商品类型、不同数量或下单表单规则不能强行合并；任务明确报告冲突，避免使用另一规格的表单下单。当前单商品最多 500 个规格，超过范围会停止该商品的自动导入，不截断、不拆分后声称全部完成。
“自动上架”仅处理本次任务新建、尚未被商户修改的商品。已经存在的商品保留原分类、名称、价格、上架状态和绑定；自营复制需要配置本地供货，因此继续生成草稿。自动上架失败时保留新建草稿和精确回执，解决原因后重试原任务，避免重复建商品。
下单字段和数量
通用表单已增加密码和多选，数字密码保留前导零。密码在订单页默认隐藏；有权处理该订单的商户或供应商可主动查看。输入和提交保留原字符串，展示按 HTML 转义。
多选按已声明选项提交，遇到上游不同选项编码时由平台适配器转换；不能把显示文字误作上游代码。每个平台的起购量、最大量、递增步长在商品准备及付款前校验，商城最大单规格数量为 9999；上游更小的上限仍然有效。卡券购买数量需要与实际交付卡密数量一致。
本地卡池采用独立交付边界：单张1024字节、单份交付1MiB，单规格安全上限为1023张，商户设置更低上限时保持更低值。该限制在公共下单流程及目录购买规则中生效，不会误限上游自动采购的卡密或直充商品。
对接页面能看到商品不等于已经具备可靠的采购契约。未能确定的控件、校验规则、交付类型或价格字段需要取得平台真实 API 定义后补齐；不能删除校验，让顾客付款后再失败。自动导入应指出具体缺失项，而不是笼统要求反复检查账号或密钥。
持续跟随上游
新建对接商品会记录实际保存后的跟随基线。后台约每五分钟检查启用渠道是否需要启动刷新，遵守上游限速；这不是所有商品五分钟内刷新完毕的承诺。卡速售需要逐个核对已经对接的父商品详情，同账号请求遵守既有间隔，商品较多时完整刷新会更长。同一渠道已有排队或执行中的同步时不会重复创建。失败按有界退避重试，旧快照继续保留。商品更新按分页遍历所有有效绑定，未变化的合同不重复拉取详情。
库存与采购成本来自当前已验证的货源快照。保留商户标题和零售价不会把采购成本永久冻结；更新成本时仍须通过全部本地价格约束，避免亏损销售。旧商品没有历史跟随基线时保留原有营销内容和状态，只更新启用渠道允许的操作快照。一个规格确认下架时当前采用整个父商品暂停销售的保守策略，避免错误采购；未按商户规则自动重开单独关闭的规格。
商品列表的“更多 → 跟随上游”提供九项独立开关：标题、封面及相册、详情及使用说明、注意事项、售价、上下架、最低数量、最高数量、下单字段及规则。渠道级同步开关仍生效。售价开关控制是否重新按加价规则计算销售价格；采购成本按渠道价格同步设置独立核验，关闭售价跟随不能冻结真实采购成本。默认只更新仍跟随上游的字段；检测到商户改动后保留商户值并停止该项跟随。重新开启代表明确同意从下一次成功同步起采用上游内容。缺失或临时为空的资料不能清空原有内容。
新商品按对接时选择的固定加价或百分比加价持续计算价格，保留等级模板与独立定价。旧商品没有可靠历史基线时保持原状；商户显式开启价格跟随后，按当前各规格的售价与成本之间的固定价差计算。出现负价差、来源不一致、价格模板冲突或不兼容的新表单时保留原数据并记录原因，不能先向顾客收款后再尝试猜测接口。
多规格商品只对实际开启的共用字段校验一致性。未开启的数量或下单字段变化不会阻塞其他已开启的跟随。如果新表单无法可靠映射，原有营销内容和表单保留、记录错误；来自当前完整来源证明的成本及库存仍独立通过事务校验更新，避免成本永久停留在旧值。成本超过商户可接受售价或价格模板约束时，该次更新整体回滚并记录价格冲突。
选择保存本地、插件存储或自定义图片的新商品默认关闭图片跟随，防止转存地址被原始上游地址覆盖。上游地址模式可以跟随图片变化；商户可逐项调整。更新保留商品及规格身份、订单、库存预占和已有采购绑定。已付款订单继续使用付款时的表单快照和采购预算，不以新售价扩大旧订单采购额度。同步变更日志记录字段、应用或保留结果和摘要哈希，不记录顾客密码或交付卡密明文。
故障恢复
同步或目录读取失败保留旧快照。仅有部分目录扫描完成时，不把未扫描的目录显示成确定的空目录，也不把一键任务记为完成。
采购请求超时或返回不完整交付时，保留原订单并回查原订单；不能再创建一次采购。卡密在加密交付写入成功后才标记已完成。外部接口无法确认退款时，保留真实状态，不能把本地退款申请写成外部退款已到账。
修改渠道来源地址、平台类型或 AppID 会改变身份。已有商品绑定、订单或任务引用的渠道不能直接换成另一家；新来源应新增渠道。相同账号的密钥轮换沿用原渠道，并继续核对来源和在途订单。删除渠道必须通过既有引用检查，保留订单历史。
订单验证码
卡易速明确要求订单后续验证码的充值商品，在原采购订单确认允许 provideOtp 时，买家订单详情显示“提交验证码”。电脑、手机网页及小程序使用各自登录凭据访问同一业务校验；开放 API 也提供该订单项的后续操作查询及验证码提交接口。只有订单所属买家可以提交，退款、完成、身份不符或上游未允许时拒绝操作。
验证码按原字符串提交，保留前导零，长度为1至32个字符，不能含空值或换行。验证码不写入商品、订单快照、普通日志或本地持久存储。提交后清空输入；同一订单须等待至少30秒，账号限流及上游 Retry-After 可能要求更久。短暂冷却期间仍显示已允许的操作并禁用提交。请求超时不能判定未提交，应先刷新原订单状态；不会自动重复提交验证码或新建采购订单。
自建 HTTP/API 接口
自建接口采用 商城 HTTP v2 自动采购契约，明确声明完整目录、商品类型、字段、数量、预算、订单身份与交付内容。旧版返回 items 的接口仍兼容原操作，但不能据此证明完整清单或任意商品可自动采购。是否已实现 v2 必须向接口提供方核对并实测。
# 商城 HTTP v2 自动采购接口
此协议供自建 HTTP/API 货源实现。已有平台专用接口仍走各自适配器；旧版仅返回 items 的接口不能证明目录完整，也不能自动推断商品类型和下单字段。
连接和认证
使用 HTTPS。路径相对渠道配置的地址，例如配置 https://example.com/api 时，商品路径为 /api/products。沿用渠道认证配置：Bearer 为 Authorization: Bearer <secret>；AppID 模式为 X-App-ID、X-App-Secret；自定义头模式使用配置的头名。密钥不得出现在 URL、商品资料或订单响应中。
完整目录：GET /products
一次返回完整 JSON 快照。所有金额均为 CNY 整数分，禁止浮点数、字符串数字、重复 JSON 属性或未知属性。商品 ID、规格 ID 稳定且唯一，不得复用。父目录需要在同一快照出现；目录不能成环。每个商品至少有一个规格和一个目录归属。
{
"schema": "kasuteng.supplier.catalog.v2",
"complete": true,
"currency": "CNY",
"totalProducts": 1,
"totalVariants": 1,
"categories": [
{"id": "root", "parentId": "", "name": "账号服务", "imageUrl": "", "sortOrder": 0},
{"id": "leaf", "parentId": "root", "name": "游戏充值", "imageUrl": "", "sortOrder": 0}
],
"products": [
{"id": "game", "name": "游戏充值", "categoryIds": ["leaf"], "coverUrl": "", "description": "填写游戏账号", "notice": ""}
],
"variants": [
{
"id": "game-100",
"productId": "game",
"name": "100点",
"type": "direct_recharge",
"costPriceCents": 900,
"stockMode": "advisory",
"stockQuantity": 0,
"status": "active",
"checkoutFields": [
{"key": "account", "label": "游戏账号", "type": "text", "required": true, "maxLength": 80}
],
"purchaseRules": {"minQuantity": 1, "maxQuantity": 100, "quantityStep": 1}
}
]
}type 为 card_key 或 direct_recharge。卡密必须使用 tracked 库存；直充可以使用 tracked 或 advisory。advisory 表示上游不提供可售数量，不能据此虚构无限库存。status 为 active 或 disabled。
checkoutFields 必须是数组；无字段用 []。直充至少有一个字段。此协议支持 text、password、select、multiselect；数字字符串使用 text 配合 validation: "digits"，单选使用 select，不接收 number 或 radio 类型。选项字段使用 options 字符串数组。当前 HTTP 采购目标按单行、最多 512 字节处理，因此此协议不接收 textarea，字段 maxLength 不得超过 512；实际提交值同时受通用采购目标总量限制。多选值为 JSON 字符串数组编码后的字符串，例如 "[\"移动\",\"联通\"]"，选项不得改成另一套编号而不声明。
数量从 minQuantity 起按 quantityStep 增加，最大不得超过 maxQuantity；三者都是正整数，商城单规格最大数量为 9999。服务端同时验证上游规则和商城规则。
响应上限 16 MiB，目录最多 1000，商品最多 10000，商品与规格总数最多 24000。不能截断后仍声明 complete=true。只有全部结构、目录归属和来源证明通过，商城才提交新快照；读取失败保留旧快照。兼容字段与数量规则相同的多规格才能合并为同一个本地商品；不同商品类型或不同表单不能强行合并。
采购：POST /orders
商城携带 Idempotency-Key 头。上游必须按此键和 reference 幂等，重试不能产生第二笔扣款。请求体：
{
"schema": "kasuteng.supplier.order.v2",
"reference": "mall-order-item-reference",
"productId": "game",
"variantId": "game-100",
"quantity": 1,
"maxTotalCostCents": 900,
"target": {"account": "player-001"}
}maxTotalCostCents 为此订单允许支付的采购总额，必须在扣款前检查；超过预算应拒绝，不能先扣款再报错。target 的键必须与 checkoutFields 一致；密码保留原字符串，不转换为数字、不自动去空格。商城在付款前检查字段、价格、数量和采购绑定，付款后才由任务执行采购。
查单和交付
GET /orders/{externalId} 查询已知上游订单；GET /orders/by-reference/{reference} 按商城 reference 查单。两者都是只读操作，不能创建订单或再次扣款。订单不存在时应明确返回未找到，不能返回任意一笔订单。成功响应：
{
"schema": "kasuteng.supplier.order.v2",
"externalId": "upstream-order-1",
"reference": "mall-order-item-reference",
"productId": "game",
"variantId": "game-100",
"quantity": 1,
"status": "succeeded",
"currency": "CNY",
"costCents": 900,
"cards": []
}响应必须回传精确身份、数量、实际采购总价和币种。订单状态沿用商城状态解析规则；推荐明确使用 processing、succeeded、failed、unknown。直充 cards 为 []。卡密成功时 cards 数量必须等于购买数量，每项至少包含可交付内容，例如 {"cardNo":"CARD-001","cardPassword":"SECRET"}；支持 cardNo、cardPassword、url、qrCode、barCode、extra、endsAt、stockType 字符串属性。
HTTP 错误、连接超时或成功但卡密不完整，都不能推断“未扣款”。商城保留原采购状态，仅回查原订单；卡密只有在加密交付提交后才算完成。响应不完整或身份不一致会暂停交付，不能拿其他订单资料代替。
此契约不定义退款接口。退款需要平台提供独立、可验证的撤销/退款契约；商城不能把未确认的外部退款写成成功。本文件定义实现要求，真实外部货源是否已实现该协议须另行实测。