API Reference

查询表单信息

查询指定收款人当前税务信息采集表单的最新状态、表单类型和回填结果，可作为状态同步与回调兜底的查询手段。

GET

Path/taxForm/v1/api/detail

AuthenticationApiKey

请求头

Header Key	必填	说明	格式 / 长度约束
ApiKey	是	Onerway 提供给商户的访问密钥	必须传入

Query 参数

字段	类型	必填	说明	校验规则
merchantRefId	string	是	商户系统中的用户ID	不可为空白；最大长度 128
taxType	string	是	报税类型	取值见 taxType

请求示例

GET /taxForm/v1/api/detail?merchantRefId=payee_10001&taxType=TAX1099NEC

响应参数

字段	类型	说明
taxType	string	报税类型，取值见 taxType
formType	string	获取链接时指定的信息采集表单类型，取值见 formType
formDetailType	string	用户实际填写并提交的信息采集表单类型，取值见 formType
formStatus	string	当前表单状态，取值见 formStatus
submitTime	string(datetime)	提交时间，示例格式为 YYYY-MM-DD HH:mm:ss
formDetail	string	表单详情 JSON 字符串
formFileUrl	string	可供下载的表单相关文件链接；通常仅 READY 状态的表单可能返回该字段，如 READY 但字段为空，表示相关文件仍在生成中

响应示例

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "taxType": "TAX1099NEC",
    "formType": "UNKNOWN",
    "formDetailType": "W8IMY",
    "formStatus": "READY",
    "submitTime": "2026-04-25 19:43:03",
    "formDetail": "{\"orgName\":\"sgszdx\",\"incorporationCountry\":\"Benin\",\"incorporationCountryCode\":\"BJ\",\"disregardedEntity\":\"\",\"chapter3Status\":\"Territory financial institution\",\"ein\":\"\",\"hasFtin\":\"NO\",\"ftin\":\"\",\"reference\":\"\",\"certNotQi\":false,\"certTransmit\":false,\"certPool\":false,\"certQsl\":false,\"certAltStmt\":false,\"certQiEntity\":false,\"certQiPrimary\":false,\"certQiSection1446f\":false,\"certQiNominee\":false,\"withholdingCertificate\":\"\",\"withholdingStatement\":\"\",\"certQiQsl\":false,\"certQiInterest\":false,\"certQiForm1099\":false,\"certQiNoForm1099\":false,\"certQiPool\":false,\"certQiFlowThrough\":false,\"certQiQdd\":false,\"certTfiA\":true,\"certTfiB\":true,\"certTfiC\":true,\"certTfiD\":true,\"certTfiE\":true,\"certTfiF\":true,\"certUsbA\":false,\"certUsbB\":false,\"certUsbC\":false,\"certUsbD\":false,\"certUsbE\":false,\"certUsbF\":false,\"certWfp\":false,\"certNwfpA\":false,\"certNwfpB\":false,\"certNwfpC\":false,\"certNwfpD\":false,\"certNwfpE\":false,\"certNwfpF\":false,\"permCountry\":\"Madagascar\",\"permCountryCode\":\"MG\",\"permAddress1\":\"sgszdx\",\"permAddress2\":\"sgszdx\",\"permProvince\":\"sgszdx\",\"permProvinceCode\":\"\",\"permCity\":\"sgszdx\",\"permPostal\":\"12334\",\"mailCountry\":\"Reunion\",\"mailCountryCode\":\"RE\",\"mailAddress1\":\"dfgd\",\"mailAddress2\":\"sgszdx\",\"mailProvince\":\"sgszdx\",\"mailProvinceCode\":\"\",\"mailCity\":\"Saint-Louis\",\"mailPostal\":\"123\",\"capacityCert\":true,\"signature\":\"esdfds\",\"signDate\":\"2026-04-25\"}",
    "formFileUrl": "https://storage.onerway.com/tax/form_example.pdf"
  }
}

状态说明

• formType 表示获取链接时指定的表单类型，取值定义见 formType
• formDetailType 表示用户实际填写并提交的表单类型，取值定义同样见 formType
• formStatus 的取值定义见 formStatus
• 当仅创建了链接、尚未提交表单时，formStatus 可能返回 MISSING
• 当表单已提交且验证进行中时，formStatus 可能返回 PENDING_VERIFICATION
• 当税务信息采集和验证完成时，formStatus 可能返回 READY
• 当表单校验失败或已过期时，商户应结合 Webhook 或业务规则引导后续处理

错误码映射

业务码	message 示例	场景说明
95005	form link not found	根据 merchantRefId + taxType 未查询到采集记录
95001	System error	系统内部异常

使用建议

• 查询接口适合作为 Webhook 的兜底手段，不建议高频轮询
• formDetail 为 JSON 字符串，商户侧如需结构化处理，请先解析
• formFileUrl 适用于需要展示或下载表单相关文件的场景