API Reference

生成表单采集链接

为指定收款人生成税务信息采集链接。商户可以直接分发链接，也可以由平台将填写入口发送到指定邮箱。

POST

Path/taxForm/v1/api/link

AuthenticationApiKey

请求头

Header Key	必填	说明	格式 / 长度约束
Content-Type	是	固定为 application/json	固定值
ApiKey	是	Onerway 提供给商户的访问密钥	必须传入

请求参数

字段	类型	必填	说明	校验规则
merchantRefId	string	是	商户系统中的用户ID	不可为空白；最大长度 128
taxType	string	是	报税类型	取值见 taxType，当前仅支持 TAX1099NEC
formType	string	否	信息采集表单类型	取值见 formType，默认 UNKNOWN
deliveryMode	string	否	交付方式	取值见 deliveryMode，默认 LINK
recipientEmail	string	否	收件人邮箱	当 deliveryMode=EMAIL 时必填；必须是合法邮箱格式；最大长度 255

请求示例

{
  "merchantRefId": "payee_10001",
  "taxType": "TAX1099NEC",
  "formType": "W9",
  "deliveryMode": "LINK"
}

响应参数

字段	类型	说明
url	string	表单采集链接
taxType	string	报税类型
formType	string	信息采集表单类型

响应示例

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "url": "https://tax.example.com/form/abc123",
    "taxType": "TAX1099NEC",
    "formType": "W9"
  }
}

错误码映射

业务码	message 示例	场景说明
95004	merchantRefId: merchantRefId is required	merchantRefId 为空
95004	taxType: taxType is required	taxType 为空
95004	invalid taxType	taxType 非法
95004	invalid formType	formType 非法
95004	invalid deliveryMode	deliveryMode 非法
95004	recipientEmail is required	deliveryMode=EMAIL 时未传 recipientEmail
95004	invalid recipientEmail	recipientEmail 不是合法邮箱
95006	Duplicate or concurrent request	重复提交或并发创建冲突
95001	System error	系统内部异常

使用建议

• 如果同一收款人只应存在一份有效采集表单，建议商户侧自行控制 merchantRefId 的幂等语义
• 当选择 EMAIL 模式时，建议先校验邮箱地址可用性
• 建议保留 merchantRefId 与返回链接的映射关系，便于后续查询与排障