Преглед на файлове

docs(汇安融开放文档): 逐单 notify_url 进 10.1/10.4/11,对接指南 docx 同步

har-openapi.md:
- 10.1 请求表加 notify_url 行 + 注解框(本单专属、快照语义、不传回落);
- 10.4 地址段改三级优先级:快照、Key return_url(注明该级是推送时现读、
  不是快照)、租户默认;POST 行「你的 return_url」改「你的回调地址」;
- 11 清单加一条(单笔指定用 notify_url,全局兜底配 Key)。

docx 对接指南(生成器 logs/_har-docx-gen.py 为 scratch,不入库):
- 04 章「两个位置」表改三级:单笔订单上 / 单把 Key 上 / 租户默认,警示框
  「两个都没配」改「三个都没配」;
- 5.3 请求表加 notify_url 行 + 注解框;5.6 首句补三级优先级;FAQ
  「收不到回调」补一句;06 清单加一条;文档版本 2026-10-14。

验证(logs/_har-docx-verify-notifyurl.py):负读数 5 词旧>0 新=0(含
"2026-10-09" 与两句被替换文案)、恒零护栏 6 词、正对照 20 词;顺序化逐行
diff(zipfile/XML 量具)与 python-docx 普查互为异种量具,diff 仅六处预期
变更、无漂移。dist 词普查:新三词命中 js/index.CEuo7SzW.js,被替旧句 0
命中;正控 5 个旧 dist vintage 同句均 =1(探针量得出正数)。

交付指纹(2026-10-14):
docx sha256 ba92075936ceb4bd5014300a5c774f9ca6bb2778c4f152258c73e105c23350fb,50,213 B(旧 49,549 B)
dist.zip sha256 708e48cc244809f6e4790f7e8fd118688d02c7ee003bf562d88687bbcacc0a42,9,374,452 B,281 条目
alphaH преди 21 часа
родител
ревизия
c36aadcf64
променени са 2 файла, в които са добавени 12 реда и са изтрити 2 реда
  1. BIN
      docs/支付宝收单开放接口对接指南.docx
  2. 12 2
      frontend/src/views/module_payment/apikey/docs/har-openapi.md

BIN
docs/支付宝收单开放接口对接指南.docx


+ 12 - 2
frontend/src/views/module_payment/apikey/docs/har-openapi.md

@@ -31,6 +31,9 @@ POST /payment/openapi/alipay/order/create
 | `out_biz_no` | string | 否  | 你自己的订单号,≤64 字符,原样存下供你查询 |
 | `ip` | string | 是  | 顾客用户端ip |
 | `pay_timeout` | int | 否  | 支付过期时间,取值 2–60(单位由上游定义,平台原样透传) |
+| `notify_url` | string | 否  | **本单专属回调地址**,≤512 字符。传了 ⇒ 这笔订单**整个生命周期**的回调全推它;不传 ⇒ 按 10.4 的默认地址 |
+
+> ℹ️ **`notify_url` 是「本单专属」的回调地址(2026-10-14 新增)。** 传了它,这笔订单**每一次回调都只推这个地址**(支付成功、退款各态、超时关闭……一切状态变化),不再看你 API Key 上配的 `return_url`。地址在下单时记到订单上,**下单之后再改 Key / 租户配置都不影响这一单**;不传(或传空白)则完全沿用旧口径(见 10.4 的三级优先级)。
 
 **响应**(B 型,`data` 内)
 
@@ -147,10 +150,16 @@ POST /payment/openapi/alipay/refund
 
 订单状态变化时,平台会向你推送一条回调。
 
-**回调地址取自你这把 API Key 上配置的 `return_url`**(未配置时退回该租户的默认回调地址)。**没配时平台不会丢下这笔** —— 记一次推送失败并继续重试(见下),你补配地址后未达上限的订单仍会收到;但尽快补配,超过上限就不会再推了,届时只能靠主动查询(10.2)拿结果。
+**回调地址按下单时的快照取,三级优先级(2026-10-14 起)**:
+
+1. **下单时传了 `notify_url`(10.1)⇒ 这笔订单整个生命周期只推它。** 地址在下单时冻结在这笔订单上,之后你改 Key 配置、改租户配置都不影响这一单;
+2. 没传 ⇒ 你这把 API Key(下单用的那把)上配置的 `return_url` —— 这级是**推送时现读**的,不是下单时快照:推的时候 Key 上配的是什么就推什么;
+3. Key 上也没配 ⇒ 该租户的默认回调地址。
+
+**三级全空时平台不会丢下这笔** —— 记一次推送失败并继续重试(见下),你补配地址后未达上限的订单仍会收到;但尽快补配,超过上限就不会再推了,届时只能靠主动查询(10.2)拿结果。
 
 ```
-POST <你的 return_url>
+POST <你的回调地址>
 Content-Type: application/x-www-form-urlencoded
 ```
 
@@ -242,6 +251,7 @@ Content-Type: application/x-www-form-urlencoded
 - [ ] 拿到了 `pay_url` 并能渲染成二维码
 - [ ] 按 `trade_status` 的**数字字符串**分支处理(`"1"` 才是钱到账)
 - [ ] `trade_status = "16"`(超时关闭)按未收款终态处理:这一单不会再有支付,不用等、不用主动查
+- [ ] 回调地址按需选:单笔指定用下单的 `notify_url`,全局兜底配 API Key 的 `return_url`(三级优先级见 10.4)
 - [ ] 回调接口能处理表单编码,并把 `content` **再解析一次** JSON
 - [ ] 回调按 `out_biz_no` 做幂等
 - [ ] 对长期停在 `"0"` 的订单有主动查询兜底