接口格式定义 - 星富通科技有限公司

协议规则

项	约定
传输方式	接口域名 `https://gw.xft.xin/openapi`
提交方式	全部采用 POST + 固定路径，不使用路径参数；业务标识（`out_apply_no`、`merchant_code` 等）一律放在请求 body
数据格式	JSON，字符编码统一 UTF-8，`Content-Type: application/json`
签名	app_key 对称签名（HMAC-SHA256），见签名验签说明
请求标识	每次请求响应头恒带 `X-Request-Id`，用于链路追踪与报障

公共参数

身份与签名通过 HTTP Header 传递，业务字段平铺在请求 body，无嵌套信封：

Header	说明	必填
`Content-Type`	`application/json`	是
`Client-Id`	渠道商 app_key（32 位十六进制），平台据此定位身份与密钥	是
`Signature-Type`	固定 `HmacSHA256`	是
`Timestamp`	请求时间，秒级时间戳（int64），与平台时间差不得超过 5 分钟	是
`Nonce-Str`	随机字符串（建议 32 位十六进制），同一 app_key 下 5 分钟内不可重复	是
`Signature`	请求签名，见签名验签说明	是
`X-Request-Id`	请求链路标识，可自生成；不传则由平台生成	否

请求报文

POST /openapi/v1/merchant/apply/query
Host: gw.xft.xin
Content-Type: application/json
Client-Id: a1b2c3d4e5f67890a1b2c3d4e5f67890
Signature-Type: HmacSHA256
Timestamp: 1755234000
Nonce-Str: 9f8e7d6c5b4a39281706f5e4d3c2b1a0
Signature: 5b2f9c3d...

{
  "out_apply_no": "P20260815001"
}

响应报文

成功响应

HTTP 200，业务数据直接平铺在响应 body，无任何业务码包装，响应头恒带 X-Request-Id 与 Signature：

{
  "out_apply_no": "P20260815001",
  "apply_no": "AP2026081500001",
  "apply_status": "AUDITING",
  "timestamp": 1755234000
}

失败响应

HTTP 4xx/5xx + 统一错误体（code 为 HTTP 状态码、reason 为错误码枚举）：

{
  "code": 400,
  "reason": "PARAM_ERROR",
  "message": "参数错误,参数[merchant_code]",
  "metadata": {}
}

字段	说明
`code`	HTTP 状态码（int），与响应状态一致
`reason`	错误码枚举（ErrorReason），机器可读，码表见返回码说明
`message`	可读描述，面向渠道商，不使用内部术语；参数类错误带出错字段名
`metadata`	附加定位信息（如当前状态、出错字段），可为空

进件重复提交（同 out_apply_no）属于幂等例外：不报错，返回 HTTP 200 与当前申请单状态。

公共约定

项	约定
时间	一律秒级时间戳（int64），与签名头 `Timestamp` 一致
金额	一律为分（int64）
空值	空值字段省略，不返回也不上送
图片	`multipart/form-data` 上传（单张 ≤5MB），上传后 `key` 7 天有效，进件时以 `category` + `key` 引用
回调地址	`back_url` 必须为 HTTPS