本文要点
- 2.10.0 为 Get Inquiry 与 Get Return 增加临时退款相关可选响应数据，没有新增售后调用。
- Inquiry 的 ProvisionalRefund 包含 refundProvided 与 refundReversed；两者都不能单独等同于最终到账。
- 新 schema 还加入 ResolutionEstimate，用 resolutionEstimateDate 表示 inquiry 预计解决日期。
- 旧 SDK、严格 enum、数据库非空约束和封闭状态机都要先做向前兼容，避免 200 响应在解析阶段失败。
- 沙盒与脱敏样本应覆盖字段缺失、已提供未撤销、已提供后撤销及未知组合，并验证分页和幂等。
- 财务与客服动作以最终退款、资金和 case 状态共同判断，临时退款状态先只读展示和告警。
2.10.0 到底改了什么
eBay 官方 Release Notes 将 Post-Order API 2.10.0 标为 2026 年 9 月 2 日发布，说明 Get Inquiry 与 Get Return 开始向卖家和合作方暴露 provisional refund 状态。schema 变化包括新的 inq-api:ProvisionalRefund、ret:ProvisionalRefundType 与 res:ResolutionEstimate，以及相关 response type 和 state enum 的修改。
这是响应数据扩展，不是新的退款写接口。集成方应先确认哪些调用和共享 schema 受影响，再更新生成模型、反序列化器与下游字段；不要仅凭版本号重新发起退款。
refundProvided 与 refundReversed 不能当最终退款
官方 ProvisionalRefund 类型把 refundProvided 定义为是否已向买家发出临时退款，把 refundReversed 定义为该临时退款后来是否被撤销。它们描述临时状态的生命周期，不直接证明最终资金结算、卖家责任或退货已经关闭。
建议内部状态至少拆成 UNKNOWN、NOT_PROVIDED、PROVIDED_ACTIVE、PROVIDED_REVERSED，并保留原始字段和抓取时间。最终自动动作仍要同时读取退款明细、case 或 return 状态、金额、币种与 Seller Hub 记录。
最容易出错的是成功响应后的 schema 解析
接口可能返回 HTTP 200，但旧 SDK 不认识新 type 或 state，严格反序列化、数据库 CHECK 约束、消息 schema 和 switch 分支仍可能报错或丢字段。若游标在解析前后推进不一致，就会出现整页重拉、跳页或重复写入。
先搜索 InquiryDetails、RefundInfoType、InquiryStateEnum 和共用 refund 映射；让新增字段保持可选，并为未知枚举保留原始字符串与 UNKNOWN_OR_NEW 兜底。不能把缺失字段默认成 false，也不能把 true/true 这种历史组合直接解释为当前仍有效退款。
沙盒与回放的六组用例
至少验证：两个字段都缺失；refundProvided=false；true/false；true/true；字段为 null 或新增未知值；同一 inquiry 或 return 跨页重复出现。每组都检查解析、数据库写入、客服展示、告警、游标与幂等键。
再为 ResolutionEstimate.resolutionEstimateDate 测试缺失、时区和已过期时间。预计解决日期只用于计划与提示，不是 SLA 或自动关闭条件；日期变化应保存历史，避免覆盖后无法解释客服承诺。
上线顺序：先只读，再对账，最后才自动化
第一步部署兼容解析并原样落库。第二步只在内部详情页展示临时状态。第三步将 API 样本与 Seller Hub、退款明细和财务流水人工对账。第四步观察一轮完整售后周期。第五步确认状态转移后再开放通知或工作流，资金动作保持额外审批。
上线后比较请求成功数、解析成功数、unknown 数、退款明细数和财务金额。任何差额、状态反复或旧数据回填都应先冻结自动退款与自动关单，保留 inquiryId、returnId、响应时间和脱敏原文，再向 eBay Developer Support 求证。
不要把 schema 变化误判成网络故障
DNS、TLS、超时和代理认证发生在请求或传输层；新增 response type 的错误发生在成功拿到响应之后。先记录 HTTP 状态、响应是否完整、解析异常和失败字段，再决定是重试请求还是修复客户端。盲目重试不会让旧 schema 认识新字段。
跨地区团队需要稳定访问开发者后台时，可<a href="/" target="_blank" rel="noopener noreferrer">访问 PuppyIP 官网</a>了解固定网络出口，并参考<a href="/resources/ebay-finances-api-psnad-id-guide">eBay API 未知枚举兼容指南</a>；网络出口不会改变 provisional refund 的业务含义。
资料来源
常见问题
eBay provisional refund 是最终退款吗？
不是。它说明临时退款是否提供、是否后来撤销；最终资金与售后动作仍要结合退款明细、金额和 case 或 return 状态判断。
Post-Order API 2.10.0 新增了退款调用吗？
官方说明是 Get Inquiry 与 Get Return 的可选响应数据扩展，没有因这次版本新增退款写调用。
refundProvided 和 refundReversed 都是 true 怎么处理？
记录为临时退款曾提供且后来撤销，不要把它当当前有效退款；再核对最终资金记录和 Seller Hub。
旧 SDK 收到新字段一定会报错吗？
不一定，取决于反序列化策略。严格 schema、封闭 enum 或数据库约束更容易失败，应通过真实样本和未知字段测试确认。
resolutionEstimateDate 可以作为自动关单时间吗？
不应。官方把它定义为预计解决日期，不是保证完成的 SLA；应只用于提示和计划，并允许缺失或变化。
请求 200 但同步失败时该先查网络吗？
先查响应解析、schema 和下游约束。已经收到完整 200 响应时，换代理不会修复客户端不认识新类型的问题。