Guide

鉴权说明

Tax API 通过请求头中的 `ApiKey` 识别商户身份并校验请求权限。请在服务端安全保存密钥，并在每次请求时正确传入。

Header AuthenticationServer-side Only

请求头要求

Header Key	必填	说明
ApiKey	是	由 Onerway 提供给商户的接口访问密钥

使用要求

• ApiKey 应仅在服务端保存和使用
• 不应在前端页面、移动端应用或公开代码仓库中暴露密钥
• 建议通过配置中心、密钥管理系统或受控环境变量保存密钥

调用示例

curl --request POST 'https://api.onerway.com/tax/taxForm/v1/api/link' \
  --header 'Content-Type: application/json' \
  --header 'ApiKey: your-api-key' \
  --data '{
    "merchantRefId": "payee_10001",
    "taxType": "TAX1099NEC"
  }'

失败场景

当以下情况发生时，平台将返回鉴权失败：

• 未传 ApiKey
• ApiKey 非法或格式错误
• ApiKey 已失效
• ApiKey 未关联有效商户

典型返回示例：

{
  "message": "Invalid API key in request"
}

鉴权失败时，平台返回的 HTTP Status 为 401。

安全建议

• ApiKey 由 Onerway 负责提供，请妥善保管
• 建议记录请求时间、请求路径和响应码，便于问题排查
• 如遇调用失败，请结合请求日志、返回码与时间戳信息进行定位