本文要点
- eBay 于 2026 年 8 月 19 日在 Finances API 1.19.1 中新增 ReferenceTypeEnum.PSNAD_ID。
- 该值用于标识 Partial Significantly Not as Described 索赔，可出现在 getTransactions 返回的 Reference 中。
- 这次变化不是新退款接口，也不表示每笔 PSNAD 都是完整退款；业务动作仍要以交易类型、金额、状态和关联引用共同判断。
- 最先检查的是枚举反序列化、SDK 版本、数据库约束、数据仓库映射和未知值告警，避免单个新枚举阻断整批同步。
- 上线应采用兼容解析、原值保留、样本回放和财务复核，不能把未知枚举静默映射成普通退款。
PSNAD_ID 改变的是引用类型，不是交易主状态
PSNAD 是 Partial Significantly Not as Described 的缩写，可理解为部分商品或部分金额涉及“与描述严重不符”的索赔。官方本次只确认 ReferenceTypeEnum 增加 PSNAD_ID，并说明它用于标识这类 claim。
Reference 是帮助关联外部业务对象的字段。不要只看到 PSNAD_ID 就自动退款、关闭订单或改写争议状态；应同时读取当前 transaction 的类型、状态、金额、币种和其他 reference，再由既有业务规则决定动作。
最难发现的故障：接口返回 200，账却少了一截
这种问题让人最容易走错方向：请求成功、定时任务也显示完成，团队便继续查网络、重跑任务，直到财务在日结时才发现交易数和金额对不上。风险最高的是把官方枚举生成为严格 enum，并在遇到未知值时直接抛异常的客户端；一个 PSNAD_ID 就可能让整页 getTransactions 在响应到达后反序列化失败。
如果失败发生在写入游标之前，同一页可能被不断重拉；如果异常被吞掉，下一页又继续推进，账面就会留下更难察觉的缺口。数据库 CHECK 约束、BI 维表、消息 schema 和 switch 分支也要一起查，只升级 SDK 不能自动修复下游仓库或报表中的封闭列表。
兼容更新的五步检查
第一，搜索 ReferenceTypeEnum 的所有解析和分支。第二，确认未知值能以原始字符串保存，并进入 UNKNOWN_OR_NEW 分类。第三，在数据库和数据仓库加入 PSNAD_ID 映射。第四，用包含该值的脱敏 payload 回放分页、重试和幂等逻辑。第五，让财务确认报表展示名称与处理边界。
兼容解析不等于忽略新值。建议同时记录 API 版本、transaction id、reference id、首次出现时间和原始枚举，并对新值触发低噪声告警；确认业务含义后再稳定归类。
对账与自动化动作要分开
报表可以把 PSNAD_ID 显示为“部分与描述不符索引”，用于检索相关交易；资金确认仍以 Finances API 返回的金额和交易语义为准。不要根据英文缩写推算退款比例，也不要把它与完整 SNAD、退货或一般 adjustment 合并。
任何自动退款、发消息或更新 ERP 状态的规则，都应设置显式条件和幂等键。新枚举首次上线时先只读观察，抽样与 Seller Hub 记录核对，再逐步开放自动动作。
发布前与发布后的验证清单
发布前验证旧 payload、新 payload、未知虚构枚举、空 references、多 references 和分页重放；确认单条解析失败不会丢掉整批数据。发布后比较 API 拉取数、落库数、未知枚举数和财务报表总额，保留可回放的 request id 与时间窗口。
如果 SDK 尚未公开支持该值，可临时使用字符串兼容层，但不要修改官方响应或丢弃原值。出现差额时先冻结自动动作，保存原始响应和游标，再分别检查解析、映射与财务规则。
网络错误与 schema 错误不要混查
超时、DNS、TLS 或代理认证发生在请求到达 API 之前；PSNAD_ID 解析失败发生在已收到成功响应之后。先记录 HTTP 状态、响应体是否完整和解析异常位置，才能决定重试还是修 schema。
跨地区团队需要稳定访问开发者后台时，可<a href="/" target="_blank" rel="noopener noreferrer">访问 PuppyIP 官网</a>了解固定网络出口，并参考<a href="/resources/proxy-connection-troubleshooting-checklist">代理连接排查清单</a>。网络出口不会改变 eBay 的枚举或索赔规则。
资料来源
常见问题
eBay PSNAD_ID 是什么？
它是 Finances API ReferenceTypeEnum 的新值，用于标识 Partial Significantly Not as Described 索赔的引用。
PSNAD_ID 会出现在哪个接口？
官方 release notes 指向 getTransactions 返回的 Reference；集成方应检查该接口及共用 Reference schema 的解析链路。
看到 PSNAD_ID 是否应该自动退款？
不应该只凭该引用类型采取资金动作。还要核对交易类型、状态、金额、币种和关联业务记录。
旧 SDK 不认识新枚举怎么办？
先确认是否有支持 1.19.1 schema 的 SDK；升级前后都应保留未知字符串兼容层、原值和告警，避免整批反序列化失败。
数据库需要怎样修改映射？
检查 enum、CHECK 约束、维表和报表分组，加入 PSNAD_ID；仍保留 UNKNOWN_OR_NEW 兜底，避免下次新增值再次中断。
如何确认升级没有造成对账遗漏？
用新旧 payload 回放分页和幂等逻辑，并比较 API 拉取数、落库数、未知值数及财务汇总；差异未解释前暂停自动动作。