# 更新日志与变更公告

> docId：`XD-OP-10` ｜ version：`1.0.0` ｜ status：`PUBLISHED`

## 1. 版本策略（先读这一段）

| 规则 | 说明 |
| --- | --- |
| 路径内带版本 | 接口路径里的 `v1` 是**主版本**；主版本内**只增不改** |
| 字段只增 | 主版本内**不删除、不改名、不改语义**；新字段一律可选 |
| 不兼容变更 | 必须升 `v2` 并**与 `v1` 平行运行至少一个公告周期**（先公告、后下线） |
| 公告先行 | 任何影响商家代码的变更，先发公告，再改行为 |
| 同源发布 | 每次发版在**本文档「更新日志」+「公开发布页」两处**同源发布，公告正文只有一份（见 `releases/`）；**门户公告位当前未启用**（平台侧「不投」口径已结项，启用时另行通知） |

**你要做的**：对 `code` 与字段做**宽松解析**（多字段不报错），对新增枚举值做兼容分支；这样主版本内的变更不会打断你。

## 2. 当前版本

| 项 | 值 |
| --- | --- |
| `skillVersion` | 见 [`MANIFEST.json`](../MANIFEST.json)（本资料与 API 合同同版本；随公开仓提供，**不在门户下载包内**） |
| API 主版本 | `v1` |
| 签名规范 | `XD-Signature-v1` / `XD-Response-v1` / `XD-Webhook-v1` |
| 本版本公告正文 | [`releases/v1.0.0.md`](../releases/v1.0.0.md)（随公开仓提供，**不在门户下载包内**） |

## 3. 更新日志

### v1.0.0

#### 资料（2026-10-17）：官网文档中心入口

公开面（README / `llms.txt`）新增官网文档中心入口：全部 14 篇文档逐篇成页，并提供文档包与 Skill 包的在线下载。接口、字段、签名与文档正文口径不变；官网与公开仓同源（同一 `contentHash`，以 `MANIFEST.json` 为准）。公开仓已于 2026-10-17 重推（单树快照 `176cf22d…`，GitHub 与 Gitee 两侧同值）；下载页通道状态随之恢复 `DELIVERED`。

**迁移动作**：无需迁移。

#### 变更（2026-10-17）：微信 JSAPI 与比例分账口径开放（无接口行为变更）

本轮为**对外口径修正**（接口、字段与路径不变），把已经具备的能力按现役实现写清楚：

- **微信 JSAPI 已开放**：买家在**微信内**打开收银页即可调起微信支付；仅限微信内浏览器——微信外手机浏览器与商家 App 内没有「直接拉起」形态；桌面微信内置浏览器同样按微信内链路处理，若无法完成支付请改用手机微信打开同一链接。其他通道或交易形态的放行仍以对接人确认为准（平台侧无自助查询面）。
- **比例分账已支持**：收款方式为三种——`SINGLE`（单账号全额）、`ROUND_ROBIN`（按顺序轮流）、`RATIO`（比例分账）。比例分账为 **2–4 个参与账号**，配置面每项 `0 < shareBps < 10000`、合计恒为 `10000`bps；`RENORMALIZE` 后单笔**生效腿**可只剩 1 条、达到 `10000`bps。查询接口只读返回配置面的 `ratios` 快照，写面仍在商家后台。
- 历史条目保留原日期与事件；涉及旧状态句的条目已按本条更新，**当前状态以本篇最新条目为准**。

**迁移动作**：无需迁移（只改资料表述，不改接口行为）。

**新增**

- **支付宝官方收款码面向商家下发**：下单响应新增 `qrCode` 字段（仅支付宝渠道、服务端校验官方前缀后下发），商家可在**自有 PC 页面**直接渲染官方收款码，与平台收银页同形。
  - 下发语义：**只有下发响应有效**；查询接口恒为 `null`；需要新码走**重拉起**端点（新尝试=新码）。
  - 覆盖三个端点：创建订单（下发）、重拉起（换新码）、查询（恒空）。
- **收银页终端分端能力**：同一收银 URL 按终端分派——PC 渲染二维码；手机浏览器（微信外）支付宝单给**手势主按钮「打开支付宝」**（渲染顺序=二维码 → 主按钮 → 按钮下的兜底说明，三样都在买家手势之前已渲染；**无手势的自动跳转已被真机证伪，不再采用**）；手机微信内支付宝单不自动跳转（只给复制链接引导）。
- **微信支付「免手点」**：手机微信内进入收银页即自动完成授权并调起支付面板，买家无需先点一次按钮。
- **手机微信外推荐路径**：微信支付单在手机微信外给出**可执行**的一键引导（复制链接并打开微信 + 三步说明 + 如实兜底），逐字文案见 [收银页对接 · 第 4 节](./06-cashier-integration.md#4-手机微信外推荐路径逐字引导文案)。

**明确不支持（不要按这些形态设计）**

- 微信**没有**「正扫」形态：微信的 PC 扫码本质是**中转链**（二维码 → 手机微信内 → 页面调起）。
- 手机浏览器（微信外）**没有**「直接拉起微信支付」形态。
- 商家的自有 App **不得**用 WebView 内嵌打开收银页（必须跳系统浏览器）。

**迁移动作**：无需迁移。本次为**只增不改**：新字段 `qrCode` 为可选，旧解析逻辑不受影响；收银页行为变化只作用于买家侧体验，商家的服务端对接无需改动。

#### 变更（2026-10-14）：收款金额限额按主体类型判定（无接口、字段或路径变更）

平台默认限额档从「全类型一档」改为**按本单实际到账账号的主体类型**判定：

- **对公主体（个体工商户 / 企业）**：不设平台业务金额上限，实际以支付服务方额度为准；
- **个人主体**：维持平台默认档；平台为你单独约定过的档位（如有）仍优先于默认档。

**你要不要改代码**：不需要。请求/响应字段、错误码与判定顺序都不变——你原本就该同时处理 `400 OPEN_API_BODY_INVALID`（单笔金额超出本单生效上限，`details.field=amountFen`）与 `422 OPEN_API_LIMIT_EXCEEDED`（触发面在 `details`）。**不要**用试探下单去摸限额边界。**资料侧同步**：[API 参考 §2.8](./03-api-reference.md#28-请求字段约束创建订单--创建退款) 的 `amountFen` 不再写死单一数字，改为按主体类型表述；[费率与限额](./07-fees-and-limits.md) 补主体分档表与各触发面的适用主体；`待支付订单数` / `未关闭支付尝试数` 两类敞口防线与主体无关，照常生效。

**迁移动作**：无需迁移。

#### 变更（2026-10-14）：新增「到账账号与收款分配」只读查询端点（第 14 篇）

商家签名 API 新增一个**只读**端点：`GET /api/open/v1/settlement/accounts`——返回你的**到账账号列表**（主体名称、商户号、银行名、银行卡尾号 4 位）与**当前收款分配**（收款方式、参与账号与顺序）。

- **只读**：收款方式（哪些账号参与收款、顺序、单账号目标、不可用时的策略）的唯一设置入口是**商家后台**的「店铺设置 → 到账账号」页；本端点不接受任何写参数，也没有请求体。
- **一单一结、随单冻结**：分配规则改动**只影响之后新建的订单**；退款按原订单冻结的分配快照发起回退（实际到账路径以支付服务方原交易与分账合同为准）。
- **比例分账已支持**（2026-10-17 起按现役实现表述）：`SINGLE` / `ROUND_ROBIN` / `RATIO` 三种方式；`RATIO` 为 2–4 个参与账号、配置面每项 `0 < shareBps < 10000`、合计 10000bps；`RENORMALIZE` 后生效腿可只剩 1 条。`ratios` 为配置面快照，不是每单实时重算。
- 字段口径与分配边界见 [到账账号与收款分配](./14-settlement-accounts.md) 与 [API 参考](./03-api-reference.md) §2.7。

**你要不要改代码**：不需要。新增端点不触碰既有端点、字段与错误码（主版本内只增不改）；想在自有后台展示「钱进了哪个账户、按什么规则分」的商家可以直接接入。

**迁移动作**：无需迁移。

#### 变更（2026-10-13）：新增「易支付协议兼容接入」面（第 13 篇）

给系统里已装「易支付 / 彩虹支付」类插件的商家新增一条**协议兼容**接入面：在商家后台「易支付接口配置」页开通后，把页面给的**网关地址 / 商家 ID / 商户密钥**填进插件即可，**不用改你系统的代码**；资金仍走持牌支付公司、进你自己在该支付公司开的结算账户（与「免签 / 第四方代收」不是一回事）。

- 支持**支付宝**（买家扫收银页上的码付款）；**微信 JSAPI 已开放**（仅微信内打开收银页可调起；微信外手机浏览器与商家 App 内没有直接拉起形态；2026-10-17 起按本条口径）；**QQ 钱包不支持**。
- **兼容该协议的多种接口**：`submit.php`（表单提交收单）与 `mapi.php`（程序化收单）两个建单入口、`api.php` 查询（`act=order` / `act=query`）——插件原来用哪个入口，就还按哪个入口发。
- 异步通知、同步回跳与主动查询按该协议惯例走；**退款不在这个面上**——走商家后台「成交订单」或[退款与对账](./08-refund-and-reconciliation.md)那条链。
- 参数、签名规则与支持范围见 [易支付协议兼容接入](./13-epay-compat-integration.md)。

**你要不要改代码**：不需要。这是新增的**可选**接入面，不影响 `/api/open/v1` 的任何既有行为。

**迁移动作**：无需迁移。

#### 变更（2026-10-12）：接入资料可用性勘正（第二批，无合同变更）

在第一轮勘正后又做了一轮**可用性复查**（文档 / Skill / 示例 / 演示 / 公开索引全量核对），修正以下引用与口径，不涉及接口、字段或平台行为变化：

- **门户页面名与按钮名对齐**：资料获取指引统一指向「**开发者文档**」页的「**下载文档包**」/「**下载接入包（含示例与 Skill）**」；费用与结算口径指向「**费率说明**」页与「**资金 / 结算**」页；
- `docs/08` 对账与 `UNKNOWN` 收敛骨架里的查询端点补全 `/api/open/v1` 前缀；
- `docs/03` 查单要点与重拉起端点口径对齐：**需要新收款材料只走重拉起**；业务幂等重放只返回当前快照；
- Skill 包内 `demo/` 相关自测命令补注「demo 不在『下载接入包』内」；`examples/README.md` 注明其 `../docs/…` 链接在接入包形态下取不到。

**迁移动作**：无需迁移。

#### 变更（2026-10-12）：接入资料勘正批（无合同变更）

对文档与 Skill 包做了六处**表述与示例修正**，不涉及接口、字段或平台行为变化：

- **Skill 的端点表与最小建单体统一为完整路径**（`<BASE_URL>/api/open/v1/...`）——接入地址是纯 host（不含路径），此前 Skill 片段里的裸路径会拼出错误地址；
- Skill 明确**域名归属验证为可选**（不影响开通与收款），与文档口径对齐；
- Skill 区分**两层幂等重放**：同 `X-XD-Request-Id` 重发返回的是**首次响应原件**（不是当前状态）；业务级重放（响应含 `replayed=true`）返回**当前快照**。拿当前状态一律走查单；
- **事件验签参考实现**（`examples/node/verify_webhook.js`）改为「去重与业务**同一事务**提交」的骨架，修正异步存储下会丢事件、并发投递会重复处理的写法；
- **示例自检/运行命令**改为在包含 `examples/` 的目录执行（公开仓根与解包后的 Skill 包根都直接可用）；
- 文档中标明 `examples/`、`demo/`、`MANIFEST.json` 与公告正文**不在「下载文档包」内**（用「下载接入包」或公开仓取）。

**迁移动作**：无需迁移。若你已按旧版 Skill 生成过代码，建议核对两处：端点路径前缀（`/api/open/v1`）与 webhook 落账的去重写法（去重行与业务同一事务）。

#### 变更（2026-10-12）：webhook 首次投递提速与表述勘正（无合同变更）

平台 webhook 投递调度已**提速至 10 秒级**（此前为每分钟粒度）；[webhook 验签与投递](./05-webhook-verification.md) 与 Skill 中「首次即时」的表述同步勘正为「**首次不等待退避间隔、由平台调度即时发出**〔秒级窗口，当前线上通常 10 秒内〕」——它只表示第 1 次投递**不排队等待退避间隔**，不是「落库即刻推送」。共投递 8 次的总数、1m/5m/15m/1h/6h/24h/48h 退避档位、超时 10 秒与响应体 64KB 上限均不变；商家侧仍是「同一事件至多 8 次投递、以 `eventId` 判重」。

**迁移动作**：无需迁移。若你的对接文档里写过「首次即时＝即时送达」，建议按上面的准确口径改写。

#### 变更（2026-10-04）：应用配置变更改为**提交即生效**（不再人工审核）

产品负责人拍板：**配置变更全部自动审核，平台侧只做记录**。原来是「提交 → 平台人工审核 → 通过后生效」，现在改为：

- 提交时仍需**短信二次验证**（敏感操作保护不变），随后平台**自动校验**（经营范围至少一项、至少一条域名、回调地址为申报域名下的绝对 HTTPS 精确 path）；
- 校验通过**即时生效**（写回你的应用配置）——**没有等待期**，提交成功后立即按新配置产生事件通知；
- 门户「应用配置变更」页可随时发起下一次变更（提交即生效，各自留档）；
- 历史上处于「审核中」的旧记录已不再产生：下次提交会自动取代它（该记录转为「已被取代」状态，不影响新提交）。

**迁移动作**：无需迁移；API 合同零改动（无字段、错误码、请求头变化）。若你的上线检查表里写着「提交后等平台审核」，可以删掉这句——提交成功即已生效。

#### 变更（2026-10-04）：密钥标识（`kid`）格式与获取方式说明补全（文档勘误，无 API 改动）

真实 `kid` 格式一直是 **`mkid_` + 16 位小写十六进制（共 21 字符）**，由平台在你**上传公钥时按公钥指纹派生**并回显——`kid` 从不预先发放。此前资料中的示例值（如 `kid_20260926`）容易让人误以为 `kid` 以 `kid_` 开头、且是一个需要"找"的既有值，已全部勘误。同时新增 **kid 本地派生公式**（`kid = "mkid_" + SHA-256(规范化 SPKI PEM 文本)[前 16 位十六进制]`），集成方可以自行计算、无需向平台索取——详见 [凭证与密钥管理 · 1.1](./12-credential-key-management.md)。另提醒：门户「应用凭证」页同时展示**你的**商户公钥 kid 与**平台的**平台公钥 kid，签名请求头只填前者。

**迁移动作**：无需迁移，API 合同零改动（无新增/删除任何字段、错误码或请求头）。

#### 变更（2026-09-28）：来源 IP 校验可自助开启/关闭

原来只能由平台侧调整的「来源 IP 校验」开关，现在**由你自己在门户掌握**（产品负责人决定）：

- 门户「IP 白名单」页新增**自助开关**：关闭/开启都需**短信二次验证**，平台全程留痕；
- **关闭不动清单**：白名单条目原样保留（不会因为关掉校验而丢），重新开启是一键的事；
- **开启前必须有条目**：空清单上开启等于把所有调用打成 `403`，平台会拒绝这个动作并提示你先加条目——这是「先配置再武装」，不是限制；
- 关闭之后，来源校验那一层的 `403 OPEN_API_SOURCE_IP_REJECTED`（**应用白名单腿**）不会再出现；**平台边缘腿**（对端地址判定）不受本开关影响，恒定生效。

**迁移动作**：无需迁移，API 合同零改动（没有新增/删除任何商家 API 字段与错误码）。若你的接入文档或运维手册里写着「白名单关闭须联系平台审核」，可以删掉这句；如果我们此前给过你「出口 IP 必须固定」的运维约定，现在多了一个自助选项，但**仍然建议保持开启**：密钥一旦外泄，它是签名之外唯一还挡在前面的东西。

#### 变更（2026-09-28）：开通申请判据简化（信用与域名核验不再是判据）

产品负责人拍板「简化开通申请，已经有商户号的卖家基本都能通过」，一键申请的自动审核判据由 5 条降为 **3 条**（判据版本 `openapi-auto-review-v3`）：

| 判据 | 状态 |
| --- | --- |
| 商家状态（在营中） | 保留 |
| 协议与同意书签署 | 保留 |
| 经营范围申报 | 保留 |
| ~~信用与争议记录~~ | **已退役**——新卖家本就没有信用记录，原判据对每一位新卖家都恒为「数据缺失」转人工；商家被停用/冻结等处置态仍由「商家状态」拦下 |
| ~~申报域名归属验证~~ | **已退役**——域名由你自己填写，**平台不做核验**；核验保留为门户里的**可选自助**，建议完成（归属更明确），但不核验也能开通 |

- 三项判据齐备即**自动开通**，不再因为「没有信用记录」「域名没验证」转人工；
- **域名归属从来不是运行时访问控制**：平台不会因为域名未验证而拒绝你的支付或回调；
- 已有的历史申请记录不受影响（历史判据结果原样保留）；历史申请的判据名仍可能显示为已退役的英文标识（如 `SVIP_VALID`），那是**历史事实**的照实呈现。

**迁移动作**：无需迁移。若你的接入文档/代码里写着「必须先完成域名归属验证才能开通」「没有信用记录会被转人工」，请一并删除该前置描述。

#### 变更（2026-09-27）：不再要求 SVIP 资格

开放平台**整条线**不再以会员等级（SVIP）为判据（产品负责人决定）：

- 应用一键申请的自动审核**不再因非 SVIP 转人工**（判据版本 `openapi-auto-review-v2`）；
- 商家 API 的**新增下单与重拉起不再要求 SVIP**——原来的「SVIP 资格」`403` 拒绝码**已从错误码总表移除**（若你的代码里有它的分支，可以删掉；保留也不会再被触发）；
- 已有的历史申请记录不受影响（历史判据结果原样保留）；商家准入仍要求**商家状态 ACTIVE** 且未被风控冻结。

**迁移动作**：无需迁移。若你的接入文档/代码里写着"需要 SVIP"，请一并删除该前置描述。

#### 文档修订（2026-09-27）

本轮为**对齐线上实际行为**的资料修订（无接口行为变更，接口侧唯一一处见下），要点：

- **关单 / 重拉起**：明确这两个端点**无请求体字段，但仍必须带 `Content-Type: application/json`**（接口侧同步修正为「空请求体按无请求体处理」——修复前不带请求体会被 `400` 拒，属缺陷修复，对已按文档接入的商家只会变宽松）。
- **请求头**：补齐六头的长度与字符集约束（`nonce` 16–64 位、`requestId` 8–128 位等）；越界与缺失共用同一句 `400`。
- **响应验签**：补齐 `CONTENT_TYPE` 归一化规则（小写、去 `;` 参数），并写明**哪些响应不带** `X-XD-Response-*`（鉴权链之前的拒绝）——按旧文做强制验签会每个响应都失败。
- **`X-XD-Request-Id` 例外**由两类更正为三类（增加请求体门卫拒绝）。
- **`notifyUrl`**：补齐四项真实前置（绝对 HTTPS、host 必须属于已验证域名、短信二次验证、审核通过才生效），并写明**未配置/未通过 = 不产生事件、事后不可补发**。（本条为 2026-09-27 当时的表述：**两项已被取代**——域名核验已退役为**可选、非生效判据**（见 [接入指南 §2](./02-integration-guide.md)），配置变更已改**提交即生效、无人工审核**（见本文档 2026-10-04 变更）；现行四项约束见 [webhook 验签 · 开头](./05-webhook-verification.md)。）
- **乱序判据**：`stateVersion` 当前恒为 `0`，改为按状态机判新旧。
- **回跳语义**：`returnUrl` 不是自动跳转，需买家点「返回商家」，且仅同一页面会话提供。
- **通道口径**：通道放行由平台整体控制、无自助查询面（原「去门户确认你的应用放行情况」有误）。
- **限额口径**：限额不在门户展示，调整走反馈渠道（原指引入口不存在）。
- **域名验证**：绝大多数失败是**终态**，需重新签发（原「核对后重新验证」会撞 `409`）；补单次申报上限 10 个。
- **指纹自检**：明确 PEM 的规范化规则（统一换行、去首尾空白后再取 SHA-256）。
- **示例与 demo**：示例补 `replayed`/`thresholdFen`、重试条目补「nonce 必须换新」、修正 PHP 覆盖声明与自检命令的工作目录；demo 修正 PC 微信单文案、去掉真实收银页没有的复制入口，并如实标注「通道闸门与四道前置门未模拟」。
- **接入地址（Base URL）下发面**：此前资料只说「开通时提供」、又不许印 host，卖家无处可取；现在**登录门户「应用凭证」页**即可看到并复制「接入地址」，文档同步改写（见 [接入指南 §1](./02-integration-guide.md)）。

#### 文档修订（2026-09-27 · 全量对齐复核批）

本轮为 12 篇文档 + Skill + 示例 + demo 与服务端实现的**逐条对齐复核**后的资料修订（无接口行为变更），修掉的是上一轮修订的漏网残留与表述例外：

- **通道口径残留清理**：简介/FAQ 里「微信要看你这个应用放行了没有」「先在后台确认你的应用放了哪几条通道」为旧口径残留——通道放行由**平台整体控制、不区分应用**，后台没有查询面；**微信 JSAPI 已于 2026-10-17 起开放**（仅微信内），其他通道或交易形态以对接人确认为准（与 [收银页对接 §1](./06-cashier-integration.md) 的修订同源）。
- **限额口径残留清理**：错误码表与 Skill 里「生效限额以门户展示为准」为旧口径残留——限额**不在任何页面展示**，被拒后先关在途订单、需调整走反馈渠道（与 [费率与限额](./07-fees-and-limits.md) 的修订同源）。
- **反馈渠道落点更正**：全部「门户反馈渠道」更正为「**官网反馈渠道**」（门户内暂无反馈提交入口，平台反馈统一走官网反馈链；门户结算页既有指引同此口径）。
- **失败信封例外**：写明来源 IP 拒绝（`403`）的信封另带一个 `details` 字段，内容只有 `reason` 或你的 `appId`，不回显平台观测到的地址。
- **六头重复例外**：同名头重复的 `400` 会在 message 里点名该头（缺失/形态越界仍不点名；每个头只提交一次即可避开）。
- **回源文件验证判据**：写明实际判据是「页面内容包含验证码」；「原样只返回验证码」是最稳妥做法而非硬性要求。
- **事件丢失路径补全**：平台侧内部异常同样可能导致事件未产生——查单补偿路径必须接（与 [上线检查清单 D6](./11-go-live-checklist.md) 互为呼应）。
- **demo 能力如实化**：demo README 补「通道闸门与前置门未模拟」标注（与本日志上一批的表述对齐）；快速开始的能力清单以 demo 冒烟实际覆盖为准（不含轮询步骤）。
- **查询退款的 `replayed`**：写明查询返回中该字段恒为 `true`（既有记录投影），勿当作幂等重放信号。
- **Skill 修订**：`APP_REVOKED` 行补「实际拿到的是 `401`」防枚举口径；`SKILL.md` 铁律 7 的限额口径同步。

#### 文档修订（2026-09-28 · 深度对齐复核批）

本轮对 12 篇文档 + Skill + 示例 + demo 与服务端实现做了**逐条深度复核**（无接口行为变更，只改表述与示例），修的是上一批的漏网与自相矛盾：

- **回跳口径统一**：接入指南与 webhook 篇里「支付完成后自动 `303` 跳回 `returnUrl`」的说法改正为「**买家点「返回商家」才回跳**，且仅同一页面会话、首次观察到支付成功时提供」——与收银页篇、与实现一致（按旧文设计落地页的商家会发现多数流程并不回跳）。
- **`CLOSED` / `FAILED` 不是终点**：补上「支付机构随后确认到账时订单会被**提升为 `SUCCEEDED`** 并推送 `PAYMENT_SUCCEEDED`」这条真实存在的迁移——把这两个状态建成吸收态会**丢掉已到账的事件**。接入指南的状态图与 webhook 篇同批补齐。
- **`stateVersion` 乱序指引清理（第二次）**：webhook 篇的落账骨架与 Skill 的上线清单里仍在教「用 `stateVersion` 判新旧」，同批删除，一律改为**按订单/退款状态机判**；demo 的 mock 平台同步改为恒 `0`（此前反而自增，会让按文档实现错语义的代码在自测里全绿）。
- **`GET` 不带 `Content-Type` 时签名串该行为空行**（新增说明）：`GET` 可以不带这个头，但不带时参与签名的是**空行**而不是 `application/json`——写错只拿到中性 `401`，此前资料里推不出这一支。签名规范篇与 API 参考同批补。
- **请求字段约束成表**（API 参考新增 §2.7）：`outTradeNo`/`outRefundNo` 6–64 位且**不能含点号**、`amountFen` `1`–`2000000`（**该单笔上限自 2026-10-14 起改为按主体类型判定——见本日志最新一条**；个人主体仍为该区间所描述的平台默认档）、`currency` 固定 `CNY`、`subject`/`description`/`attach`/`returnUrl`/`reason` 的长度上限与 https 要求——此前这些硬约束只存在于合同文件，卖家只能靠 `400` 反推。
- **业务摘要成员公开**：明确同号重试「同内容」的判定成员（含 `returnUrl`）——**改 `returnUrl` 再重试是 `409` 冲突而不是被忽略**；`payerClientIp` 不参与，可自由变化。
- **`400` 与 `422` 的分界**：单笔金额超出平台**合同硬上限**返回的是 `400 OPEN_API_BODY_INVALID`；`422 OPEN_API_LIMIT_EXCEEDED` 只用于平台限额。费率篇补出**日累计口径**（当日支付成功金额之和、**退款不释放额度**、北京时间自然日）与**待支付订单数 / 未关闭尝试数**两类此前完全没写的触发面，并说明实际生效的限额层级只有**两级**（结构性存在的「应用档位」当前没有写入面）。
- **事件体两处语义**：`status` 是**事件主体自身**的状态（退款事件里是退款状态，不是订单状态）；事件 nonce 是**事件级**的（重投复用同一 nonce，判重一律用 `eventId`）。「上限 8 次」改写为「**共投递 8 次**（首次即时 + 7 次退避）」，并如实写明**终止态之后平台不会自动感知**（需商家自查单/对账后申请人工补推）。
- **`403` 的两条腿**：区分**平台边缘腿**（带 `details.reason` 七种取值，加白名单无效）与**应用白名单腿**（三字段信封）；删去原先「`details` 含 `appId`」的承诺（该值不会出现在响应里）。安全红线 §8 的简写码名补注「信封里一律是全名」。
- **兜底与边界**：补「收到总表之外的 `code` 按 `503` 语义处置并反馈」、`413`/`500` 的存在说明、以及「路径/方法写错时拿到的不是本文档描述的信封」；`GET` 两个查询端点的失败码补 `409`（重放防护）；创建订单失败码删去不可达的 `404`；`X-XD-Sign` 补 `64–1024 位可见 ASCII`；拒绝次序按实际装配更正（**请求体门卫 → 来源 IP → 六头形态**）。
- **响应验签如实登记**：`XD-Response-v1` 目前**没有参考实现**（`examples/` 覆盖请求签名与事件验签），上线清单 A6 补注需自行按规范串实现；demo 的 mock 平台也**不回**四头。
- **demo 与生产对齐**：关闭/失败事件的 `eventAmountFen` 改为 `0`、`reason` 带上真实关闭原因、退款事件补 `outRefundNo`、`stateVersion` 恒 `0`；README 明示**本 demo 的请求体不是生产请求体形状**（生产以快速开始 §2 六个必填字段为准），并注明 `demo/` **不在门户两个下载包内**。
- **结算视图口径**：明确逐笔清单**只展示最近若干笔**，更早订单以自有记录 + 每单 `feeProjection` 对账。

#### 资料修订（2026-10-02）：对外费率与手续费改为公开写明

产品负责人指令「用户需要知道费率」：公开面——仓库 `README.md` 与 `llms.txt`——现写明**全平台统一**的对外费率与固定手续费；`docs/` 正文不重复列数字，**入账口径不变**（仍以每单 `feeProjection` 为准），限额与时效口径不变（不写死）。姊妹公开仓（`xiaodou-market`）此前已按同口径执行，两仓同源同价。

**迁移动作**：无需迁移。API 合同零改动；若你的对接文档里写过「平台不公开费率」，改为「以公开面与商户后台「费率说明」页为准」即可。

## 4. 已取消/不支持的形态（历史公告残留，防误用）

平台**不提供**下列形态，任何历史资料、截图或口口相传里的这些说法都不成立：

- 微信「原生扫码」直出付款码（见上：不存在）。
- 手机浏览器直接拉起微信支付面板。
- 平台侧托管收款页（收款页形态只有本资料描述的两类：自渲染官方收款码 / 平台收银页）。
- 在本资料里出现过的任何「时效承诺」或旧版「固定费率」——均已作废；费率一律以**公开面（`README.md`）与商户后台「费率说明」页**为准，对账以**每单投影**为准。

## 5. 发布通道状态（机器校验）

<!-- xd-release-channels -->
```json
{
  "skillVersion": "1.0.0",
  "threeWayPublished": false,
  "channels": {
    "portalAnnouncement": {
      "status": "PENDING",
      "path": null,
      "note": "产品负责人 2026-09-28 决定：本批资料修订不做门户公告（无需公告）；本项保持 PENDING，threeWayPublished 因此恒为 false——不得据此宣称「三处同源发布」。追加：2026-10-04 产品负责人明确决定「不做」——公告腿按「不投」口径结项、不再挂待办；门户公告位能力保留不拆，未来如启用另发公告。"
    },
    "changelog": {
      "status": "DELIVERED",
      "path": "docs/10-changelog.md",
      "note": null
    },
    "publicRelease": {
      "status": "DELIVERED",
      "path": "releases/v1.0.0.md",
      "note": "公开仓 github.com/xiaodou-official/xiaodou-open-platform 与 Gitee 镜像 gitee.com/lu-wulei/xiaodou-open-platform（单树快照推送=git commit-tree HEAD:open-platform，同一快照 SHA 两侧逐字一致；tag v1.0.0 指向首发内容树、版本内资料修订随 main 滚动）。2026-09-28 两批：资料修订重推批（响应验签参考实现、开通申请判据简化、域名口径定稿）+ README 增补指向姊妹公开仓 `xiaodou-market` 的链接。2026-09-29 两批：① README 增补指向 `xiaodou-app` 的链接（三仓两两互链）；② `llms.txt` 增补「同一运营主体的其他产品线」段与**新用户福利口径**（四处公开面逐字同源，产品负责人 2026-09-29 拍板）。2026-10-02：费率公开修订（产品负责人指令「用户需要知道费率」）——`README.md` 与 `llms.txt` 增补**全平台统一**的对外费率与固定手续费口径，公开仓重推；同步纪律见 `PUBLISHING.md` 第 5 节。2026-10-04 两批：① kid 勘误批（密钥标识 `kid` 的格式、来源与本地派生公式修正，快照 `2743da9610d9a9c44500d4eeb0bc613488cc1396`）；② README/llms 公开面批（个人可申请与免费接入检索词，含同日「配置变更提交即生效」资料修订，快照 `d9279f4c8da140ba542f3f628a33e5578d3e101c`，两侧同值）。2026-10-04 勘误批：收银「回商家」回跳口径勘误（`docs/02/05/06/09` + Skill 五处同口径「扫码支付不受此限」）与发布记录回补，公开仓重推；快照 `ce248552de75eb4bd2d423035b4de41708131213`（两侧同值）。2026-10-05 两批：① 宣传句收口 + 小豆支付平台三面 UI 美化（快照 `7a8aeb17e05c9501bcda7cb16d1caba6eee2bc6f`，两侧同值）；② 三公开仓 `llms.txt` 增补「运营主体与资质」节（ICP/EDI 许可证与持牌支付机构合作；本仓快照 `f70a5ce5ba134579837bee52a81eccbe35cc373d`，两侧同值）。2026-10-06：README 顶部增补开放平台**全流程演示页**链接（在线可点击演示；产品负责人指令，公开仓域名口径对该演示 URL 完整字面量单点放宽），公开仓重推（快照 `d6ffe0c9509a300316512e90af87eeb387337a17`，两侧同值）。2026-10-10：对外入口域名迁移（产品负责人 2026-10-09 拍板；旧域转 301 保活、同路径与 query 透传），`README.md` 对外入口单点随批更新，公开仓重推（快照 `5bc37c62cc01c70019e66f732d513ec1e63e97f9`，两侧同值；本批回补登记）。2026-10-10（round-04 官网重规划批）：公开面**撤除已退役 App 的福利口径**（新用户注册赠 12 个月 VIP 一句随 App 下架停更整体撤除；活动配置同批关闭），并把「同一运营主体的其他产品线」段的 App 条改述为**卖家移动面＝微信小程序经营台**（看商品 / 订单 / 结算；上货、进件与售后仍在网页端办理；不是买家入口），`README.md` 同批同步。公开仓重推（快照 `05ca0a02700d0b5127b59643eafc580686940cb5`，GitHub 与 Gitee 两侧同值、匿名读回同值）；本条发布记录随本次重推一并对外。2026-10-10（资料收口批，仓库侧）：docs/skill 修订入库——响应验签参考实现口径勘误、`kid` 格式与派生补全、限额 `details` 枚举补全（`PENDING_AMOUNT` / `REFUND_CUMULATIVE`）、应用白名单腿 `details` 收紧（代码侧同批）、桌面微信/回跳凭证/事件体字段等六处补签、Skill 包自足性补强，另含 docs 10 篇与 Skill 门禁补钉。**本批尚未重推**——按 `PUBLISHING.md` §3.6 通道状态退回 `PENDING`；重推后回填快照并恢复 `DELIVERED`。2026-10-10（资料收口批·重推）：docs/skill 收口（响应验签参考实现勘误、`kid` 补全、限额 `details` 枚举、应用白名单腿 `details` 收紧〔RP 代码 `a94ed9a8c1`〕、桌面微信/回跳凭证/事件体字段补签、Skill 包自足性）+ 一致性门禁补钉随批公开；重推快照 `9a3d4fbb6df0d816dd241cae432a2881b2a45cac`（GitHub 与 Gitee 两侧同值；GitHub 腿经本机代理补推、gh api 读回同值；四件抽样匿名 raw 三方逐字节一致）。本条发布记录随本次回填二次推送。2026-10-12（资料勘正批，仓库侧）：webhook 首次投递表述勘正（`docs/05-webhook-verification.md` 与 Skill `references/webhook-verification.md` 同口径『首次不等待退避间隔、由平台调度即时发出〔秒级窗口，当前线上通常 10 秒内〕』；背景＝投递调度提速至 10 秒级，2026-10-12 生产发布 `openapi_webhook_cron10s_r1`）。**本批尚未重推**——按 `PUBLISHING.md` §3.6 通道状态退回 `PENDING`；重推后回填快照并恢复 `DELIVERED`。2026-10-12（资料勘正批·重推）：webhook 首次投递表述勘正（`docs/05-webhook-verification.md` 与 Skill `references/webhook-verification.md` 同口径『首次不等待退避间隔、由平台调度即时发出〔秒级窗口，当前线上通常 10 秒内〕』；背景＝投递调度提速至 10 秒级，2026-10-12 生产发布 `openapi_webhook_cron10s_r1`）。重推快照 `31d59510e98105cd5e20bdb7595d640e051c44f2`（GitHub 与 Gitee 两侧同值、匿名 ls-remote 同值；`docs/05` 三源 raw 逐字节一致）。本条发布记录随本次回填二次推送。2026-10-12（对外资料评审勘正批，仓库侧）：对外资料评审 6 项修正入库——Skill 端点表/伪代码/最小建单体统一为完整路径（接入地址是纯 host，路径自带 `/api/open/v1` 前缀）、Skill 域名归属验证改「可选、非开通判据」口径、Skill 与 docs/03 区分幂等两层重放（请求级=首次响应原件／业务级=当前快照）、`examples/node/verify_webhook.js` 去重改「去重行与业务同一事务」骨架（修 await 缺失与并发重复处理）、`examples/README.md` 自检与运行命令改包根相对路径、docs 十一处包外引用补「不在文档下载包内」注记 + docs/10 新条目。**本批尚未重推**——按 `PUBLISHING.md` §3.6 通道状态退回 `PENDING`；重推后回填快照并恢复 `DELIVERED`。2026-10-12（对外资料评审勘正批·重推）：资料勘正批 6 项公开仓重推；一推快照 `8fc3308e4c81bb9e1b657d3f52cdac3f6b084832`（GitHub 与 Gitee 两侧同值、匿名 ls-remote 同值；GitHub 直连成功）。本条发布记录随本次回填二次推送。2026-10-12（全面复查批，仓库侧）：产品负责人指令「全面修复、确保上架最新可用版」——链接/锚点全量审计＋门户页面名/按钮名逐一对源＋端点路径散文面扫描后，9 类可用性勘正入库（门户页面名与按钮名对齐：开发者文档页·下载文档包/下载接入包·费率说明·资金 / 结算；docs/08 查询端点补全 `/api/open/v1` 前缀；docs/03 查单要点与「新材料只走重拉起」口径对齐；Skill 内 demo 自测命令补包外注记；examples/README 补交付形态说明；docs/06 措辞统一；内部流程文档引用勘正；changelog 新条目）。**本批尚未重推**——按 `PUBLISHING.md` §3 第 6 步通道状态退回 `PENDING`；重推后回填快照并恢复 `DELIVERED`。2026-10-12（全面复查批·重推）：全面复查批 9 类可用性勘正公开仓重推；一推快照 `f840e3ea5b546590dd6f7320ceef8f61abb9dec9`（GitHub 与 Gitee 两侧同值、匿名读回同值；GitHub git 通道不可达时段经 `gh api` 读回同值）。本条发布记录随本次回填二次推送。2026-10-13（易支付兼容面公开批，仓库侧）：公开面第 13 篇《易支付协议兼容接入》＋ README 接入触点；未重推。2026-10-14（资料批，仓库侧）：排障页 appId 逐字符提示＋限额 W12 公开面主体分档收口＋多到账账号 I21 批新篇《到账账号与收款分配》＋ API 参考 §2.7；未重推。2026-10-15（资料口径收口批，仓库侧）：公开面接口清单同步为七个端点（README 接口一览＋`llms.txt`＋Skill 端点表＋`examples/README.md` 自检说明＋第 13 篇互引）、Skill 资产表文档篇数 12→14、更新日志补第 13/14 篇条目；**易支付协议兼容关键词补强**（README 顶部与接口一览＋README 术语表＋`llms.txt` 新增条目＋英文检索词＋第 13 篇「兼容该协议的多种接口」具名 `submit.php`/`mapi.php`/`api.php`＋更新日志同口径；产品负责人 2026-10-15 指令「本次推送务必加入易支付兼容关键词」）。**以上各批（含本批）已于同日重推公开仓**（快照与两侧读回见下条），通道状态随之恢复 `DELIVERED`。2026-10-15（资料口径收口批·重推）：七端点清单同步＋易支付协议兼容关键词补强（README 顶部、接口一览、术语表、英文检索词；`llms.txt` 新增条目；第 13 篇「兼容该协议的多种接口」具名；更新日志同口径）＋Skill 资产表篇数 12→14 公开仓重推；一推快照 `e4833840e65365f812571692b433220be7440cea`（GitHub 与 Gitee 两侧同值；匿名 `git ls-remote` 同值；README / `llms.txt` / 第 13 篇三件匿名 raw 逐字节读回同值；关键词读回在位）。本条发布记录随本次回填二次推送。2026-10-15（易支付 / 彩虹支付关键词批，仓库侧）：产品负责人指令「对外宣称支持兼容易支付接口、彩虹支付接口」——① open-platform 全面关键词（README 顶部/接口一览/术语表/英文检索词/FAQ、llms、第 13 篇、更新日志）；② 第二梯队同步（官网首页与 llms、xdfair 站与 llms、GEO 事实卡、未发稿）＋接口范围 六→七 收口（xdfair 接线图/接口表/筛选段、官网 wall 卡）；③ README 视觉刷新（assets/readme/hero.svg＋导航行）＋GitHub About 优化（描述/站址/主题词）；④ 旧「第三方产品名一律不出现」纪律改判（易支付配置清单 §10、公开仓发布清单 §3/§5、Gitee 自检表同批）。**本批已于同日重推公开仓**（快照与两侧读回见下条），通道状态随之恢复 `DELIVERED`。2026-10-15（易支付 / 彩虹支付关键词批·重推）：关键词全链＋第二梯队＋README hero（`assets/readme/hero.svg`）＋GitHub About 优化公开仓重推；一推快照 `0d54a0509c3b2a5338e874110e2b1619dd48b41f`（GitHub 与 Gitee 两侧同值；匿名 `git ls-remote` 同值；README / `llms.txt` / `assets/readme/hero.svg` 三件匿名 raw 逐字节读回同值；「彩虹支付」读回在位）。本条发布记录随本次回填二次推送。 2026-10-17（口径开放批，仓库侧）：微信 JSAPI 已开放、比例分账已支持、退款按快照发起回退与 docs/03 锚点勘正等资料修订入库。**本批尚未重推公开仓**——按 PUBLISHING.md §3 第 6 步，publicRelease 状态退回 PENDING；重推后回填快照并恢复 DELIVERED。 2026-10-17（官网文档中心入口批·重推）：README 增补官网文档中心 / Skill / 文档下载三个入口、llms.txt 新增「官网文档中心」节；首次快照 `176cf22da8ba52838a180d841c0c1eb8973a0197`（GitHub 与 Gitee 两侧同值；匿名 raw 读回在位）。本条发布记录随本次回填二次推送。"
    }
  }
}
```
<!-- /xd-release-channels -->

> 上表由门禁与 `MANIFEST.json` 交叉校验：**未全部投递前不得宣称「变更公告已全通道发布」**。