API Reference

状态通知

当税务信息采集表单状态发生变化时，平台会向商户配置的通知地址发送异步回调。当前通过该通知方式推送表单状态结果。

POST

PathMerchant Webhook URL

Authenticationx-signature

通知方式

项目	说明
请求方法	POST
Content-Type	application/json;charset=UTF-8
事件类型	tax.form.status.change

请求头

Header Key	类型	必填	说明	格式 / 长度约束
Content-Type	string	是	固定为 application/json;charset=UTF-8	固定值
x-timestamp	string	是	Unix 时间戳	秒级时间戳字符串
x-signature	string	是	使用 webhook_secret 计算出的十六进制签名	64 位十六进制字符串

鉴权方式和标准请求结构请参考 Webhook 接入。

触发场景

当税务信息采集表单状态变为以下值时，平台会发送状态通知：

• READY
• FAILED
• EXPIRED

说明

PENDING_VERIFICATION（验证进行中）状态不会触发 Webhook 通知。如需获取该状态，请通过查询接口主动查询。

eventType

tax.form.status.change

请求体格式

顶层字段

字段	类型	说明	格式 / 长度约束
requestId	string	本次通知请求 ID	-
eventType	string	固定为 tax.form.status.change	固定值
createdAt	string	通知创建时间	时间字符串，格式为 YYYY-MM-DD HH:mm:ss
version	string	当前固定为 v1.0	固定值，长度为 4
data	object	税务信息采集表单业务数据	对象结构见下表

data 字段

字段	类型	说明	格式 / 长度约束
merchantNo	string	商户号	-
merchantRefId	string	商户系统中的用户ID	来源于商户请求；最大长度 128
taxType	string	报税类型，取值见 taxType	枚举值
formType	string	信息采集表单类型，取值见 formType	枚举值
formStatus	string	最新表单状态，取值见 formStatus	枚举值
submitTime	string(datetime) / null	表单提交时间	时间字符串，格式为 YYYY-MM-DD HH:mm:ss，或 null

回调示例

POST /notify/10001 HTTP/1.1
Content-Type: application/json;charset=UTF-8
x-timestamp: 1777012345
x-signature: 4d2f...

{
  "requestId": "1987654321123456789",
  "eventType": "tax.form.status.change",
  "createdAt": "2026-04-27 17:20:31",
  "version": "v1.0",
  "data": {
    "merchantNo": "10001",
    "merchantRefId": "payee_10001",
    "taxType": "TAX1099NEC",
    "formType": "W9",
    "formStatus": "READY",
    "submitTime": "2026-04-27 17:18:01"
  }
}

字段说明

formStatus

值	说明
READY	税务信息采集和验证完成，可进入后续业务处理流程（如允许提现）
FAILED	表单校验失败，需重新填写或人工处理
EXPIRED	表单已过期，建议重新生成链接

完整枚举说明请参考 枚举定义。

商户处理建议

• 先进行签名校验，再处理业务逻辑
• 使用 requestId 做通知级幂等控制
• 建议将 merchantRefId + formStatus + submitTime 作为业务侧补充去重键
• 当状态为 FAILED 或 EXPIRED 时，可结合查询接口或业务规则引导后续处理