> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API 版本与变更记录

> 解答商户跟进 Waffo API 变化时最常见的问题：X-API-VERSION 请求头的取值、变更日志版本号与 SDK 版本的区别、如何发现新字段，以及 2026-07 至 2026-10 对外变更摘要。

本页回答商户在跟进 Waffo API 变化时最常问的问题：`X-API-VERSION` 请求头填什么、变更日志里的 `v1.3` 是什么、SDK 版本和 API 版本是什么关系、怎么知道接口有了新字段，以及近期对外变更的摘要。完整、最新的记录以官网[API 版本历史](https://waffo.com/docs/zh/developer-docs/tools-and-references/references/changelog.md)为准。

## `X-API-VERSION` 请求头应该填什么？

| 你的调用方式 | 怎么处理 |
| - | - |
| 直接发 HTTP 请求 | 发送 `X-API-VERSION: 1.0.0` |
| 使用 Waffo SDK | SDK 自己管理这个请求头，**不要设置或覆盖** |

## 变更日志里的 `v1.3` 能填进这个请求头吗？

不能。API 版本历史里的 `v1.0`、`v1.1`、`v1.2`、`v1.3` 标识的是 **Waffo API 文档和对外契约的修订系列**，不是请求头的取值。请求头的值始终是 `1.0.0`。

## SDK 的版本号和 API 的版本是同一回事吗？

不是，是两套独立的记录：

| 记录 | 内容 | 在哪看 |
| - | - | - |
| API 版本历史 | Waffo API 的文档与契约修订（新增接口、新增字段、新增错误码等） | 官网[API 版本历史](https://waffo.com/docs/zh/developer-docs/tools-and-references/references/changelog.md) |
| SDK 变更日志 | Node.js / Java / Go / Python / PHP 各 SDK 包的发布说明 | 官网[SDK 变更日志](https://waffo.com/docs/zh/developer-docs/sdk/changelog.md) |

API 新增了字段，不代表你已经安装的 SDK 有对应的类型。SDK 的选择和升级注意事项见[SDK 概览与选择](https://waffo.com/docs/zh/support/sdk-overview-and-selection-faq.md)。

## 我怎么知道 API 有了新字段或新接口？

* 定期查看官网[API 版本历史](https://waffo.com/docs/zh/developer-docs/tools-and-references/references/changelog.md)，它按日期列出每次对外变更。
* 变更涉及你已接入的接口时，同时对照该接口的 API 参考页确认字段是否必填、长度限制是否变化。
* 变更涉及 SDK 类型时，查看 SDK 变更日志里对应语言有没有新版本。

## 近期对外变更摘要（2026-07 至 2026-10）

下面是 `v1.3` 系列近期条目的中文摘要，方便你快速判断哪些变更和你有关。**这是摘要，不是完整清单**，以官网记录为准。

| 日期 | 变更要点 |
| - | - |
| 2026-10-22 | `PAYMENT_NOTIFICATION` 中新增 `subscriptionInfo.subscriptionEvent`，取值 `PERIOD_CHARGE`（周期扣款）、`USER_ADD_PAYMENT_METHOD`（用户新增支付方式）、`TOPUP_CHARGE`（订阅升级或加购补差）。同时澄清了「主状态通知」与「各周期最终支付结果」的区别，建议在发放周期权益前核对周期、金额和支付结果 |
| 2026-10-19 | 澄清 Payout 创建请求、创建响应和查询响应中的收款人信息：`payeeType` 为 `INDIVIDUAL` 时用 `payeeInfo`，为 `BUSINESS` 时用 `receivingBusinessInfo`；字段结构和必填标记不变 |
| 2026-10-12 | 新增 `POST /api/v1/subscription/resume`，用于撤销预约取消；订阅取消的请求、响应和查询响应新增 `scheduledCancelAt`，预约取消生效前，取消响应的 `orderStatus` 为 `ACTIVE`；订单创建、退款及其查询响应新增 `taxInfo`，订单和退款查询响应新增 `orderTaxAmount`；当你改为提供含税金额时，`orderAmount` 和 `refundAmount` 不再无条件必填，`refundAmount` 最大长度为 24；Payout 创建与查询新增 `payeeType` 和 `receivingBusinessInfo`，`PayeeInfo.payeeType` 标记为废弃并去掉必填标记，创建请求里的 `payeeInfo` 也去掉必填标记；Payout 电子钱包标识类型 `PHONE` 由「默认」改为「推荐」 |
| 2026-10-09 | 新增公开错误码 A0051、A0052、A0053（申报税额校验）；新增 A0056、A0058、A0059、A0060、A0062（订阅预约取消校验） |
| 2026-09-29 | 订阅创建、查询、管理响应的 `subscriptionStatus` 中补充文档化 `PLATFORM_CANCELLED` |
| 2026-09-08 | 订阅变更请求和响应新增加座补差 `topupInfo`，订阅查询的支付详情新增 `topupDetails`；订阅创建、变更、查询的支付信息新增 `payMethodCountry`，订阅变更请求新增 `cashierLanguage`；Payout 订单数据 `PayoutOrderData` 新增 `purpose`，移除 `feeStatus`、`mid`、`subMid`；`PayeeInfo.payeeId` 不再标记必填；拒付证据字段 `EvidenceField.evidenceFields` 从公开 schema 移除；拒付和欺诈举报列表响应的分页 schema 改名为 `ApiPageResponse...` |
| 2026-09-07 | 新增公开错误码 A0055、B0014、B0015、B0016（订阅变更进行中、卡状态校验） |
| 2026-08-24 | 新增欺诈举报查询接口 `POST /api/v1/fraud-report/list`；订单和订阅的支付信息新增 `receiptTemplateId`；拒付详情和列表响应新增 `merchantOrderId`；拒付查询请求里 `chargebackId` 和 `originalOrderId` 不再标记必填 |
| 2026-08-21 | 新增公开错误码 A0048、A0049、A0050、A0054（订阅换套餐的状态：支付中、取消中、已支付成功、另一个变更请求进行中） |
| 2026-08-20 | 新增点卡充值（Waffo Point Topup）API：`GET /redirect` 签名跳转端点、`POST /api/v1/gamepin/fulfillment-inquiry` 履约查询，以及 `FULFILLMENT_RESULT_NOTIFY` 履约结果 Webhook |
| 2026-07-24 | 订阅创建请求中 `subscriptionManagementUrl` 标记为必填；`PayMethodDetail` 新增币种、订单金额上下限、支付方式类型和是否支持退款等字段，`currentStatus` 不再标记必填；Payout 订单数据 `PayoutOrderData` 恢复 `mid`、`subMid`，并更新 Payout 收款账号、描述和用途的说明；`AcqCardInfo` 里的卡号、有效期、CVV、持卡人姓名不再标记必填 |
| 2026-07-22 | 订单创建和订阅创建请求里的 `userEmail` 说明：该字段必填；拿不到真实邮箱时，传一个基于用户 ID 的唯一兜底邮箱，不要用占位符或共享邮箱 |
| 2026-07-17 | 新增公开错误码 A0047（收银台页面语言取值不符合 IETF BCP 47） |
| 2026-07-13 | 新增订单扣款确认接口 `POST /api/v1/order/capture`，用于授权-扣款模式下手动确认扣款 |

更早的条目（2026-07-08 的错误码表同步、`payMethodName` 长度上限从 24 放宽到 256 等，以及 v1.0 至 v1.2）请直接查看官网记录。

## 我应该怎么处理这些变更？

* **新增的必填或不再必填字段**：对照接口参考页确认你现有的请求是否仍然合法。「不再必填」不需要你改代码，「新增必填」才需要。
* **新增错误码**：把它加进你的错误处理分支。错误码的含义见官网[错误码速查](https://waffo.com/docs/zh/developer-docs/tools-and-references/developer-tools/error-codes.md)和[API 参考速查表](https://waffo.com/docs/zh/support/api-reference-tables.md)[常见错误排查](https://waffo.com/docs/zh/support/errors-troubleshooting-guide.md)。
* **新增通知字段或事件**：确认你的 Webhook 处理逻辑能容忍新字段，对未识别的字段不要报错，处理逻辑见[回调通知事件字典与批量重发](https://waffo.com/docs/zh/support/webhook-events-and-resend-faq.md)。
* **官网记录与你手头的接口规格不一致时**：以官网当前发布的页面为准。

## 相关入口

* 官网 API 版本历史：[https://waffo.com/docs/zh/developer-docs/tools-and-references/references/changelog.md](https://waffo.com/docs/zh/developer-docs/tools-and-references/references/changelog.md)
* 官网 SDK 变更日志：[https://waffo.com/docs/zh/developer-docs/sdk/changelog.md](https://waffo.com/docs/zh/developer-docs/sdk/changelog.md)
* 官网 API 概览（认证与签名）：[https://waffo.com/docs/zh/developer-docs/integration/api/overview.md](https://waffo.com/docs/zh/developer-docs/integration/api/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.