> ## Documentation Index
> Fetch the complete documentation index at: https://opendocs.xft.xin/llms.txt
> Use this file to discover all available pages before exploring further.

# 接口格式定义

## 协议规则

| 项 | 约定 |
| - | - |
| 传输方式 | 接口域名： 测试环境 `https://go-test.xft.xin` 生产环境 `https://gw.xft.xin` 接口路径统一以 `/openapi` 开头 |
| 提交方式 | 全部采用 **POST** + 固定路径，不使用路径参数；业务标识（`out_apply_no`、`merchant_code` 等）一律放在请求 body |
| 数据格式 | JSON，字符编码统一 UTF-8，`Content-Type: application/json`（图片上传为 `multipart/form-data`） |
| 签名 | app\_key 对称签名（HMAC-SHA256），请求携带签名头，响应头恒带 `Signature`，见[签名验签说明](https://opendocs.xft.xin/open/payment/spec/signature.md) |

## 公共参数

身份与签名通过 **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` | 请求签名，见[签名验签说明](https://opendocs.xft.xin/open/payment/spec/signature.md) | 是 |

## 请求报文

```http theme={"system"}
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，**无任何业务码包装**，响应头恒带 `Signature`：

```json theme={"system"}
{
  "out_apply_no": "P20260815001",
  "apply_no": "AP2026081500001",
  "apply_status": "AUDITING",
  "timestamp": "2026-08-15 10:00:23"
}
```

### 失败响应

HTTP 4xx/5xx + 统一错误体：

```json theme={"system"}
{
  "code": 400,
  "reason": "PARAM_ERROR",
  "message": "参数错误,参数[merchant_code]",
  "metadata": {}
}
```

| 字段 | 说明 |
| - | - |
| `code` | 错误码数值（int32），取值见[返回码说明](https://opendocs.xft.xin/open/payment/appendix/return-code.md)；业务错误时与 HTTP 状态码一致 |
| `reason` | 错误码枚举（ErrorReason），机器可读，**排查与重试判断以 `reason` 为准** |
| `message` | 可读描述，面向渠道商，不使用内部术语；参数类错误带出错字段名 |
| `metadata` | 附加定位信息，可为空 |

> [!NOTE]
>
> 网关层拒绝是「`code` 与 HTTP 状态码一致」的例外：验签失败返回 HTTP 401，但 body 中 `code` 为 `NO_AUTH`（403）；`Client-Id` 对应的 app\_key 无效返回 HTTP 400，body 同为 `NO_AUTH`（403）。详见[签名验签说明](https://opendocs.xft.xin/open/payment/spec/signature.md#平台验签流程)。

> [!NOTE]
>
> 商户录入重复提交（同一调用主体、同一 `out_apply_no`）属于幂等例外：不报错，返回 HTTP 200 与已受理申请单的当前状态。

## 公共约定

| 项 | 约定 |
| - | - |
| 时间 | 业务字段（如 `timestamp`）一律为字符串，格式 `yyyy-MM-dd HH:mm:ss`（北京时间）；签名头 `Timestamp` 为秒级时间戳 |
| 金额 | 一律为字符串，单位为分（如 `"100"` 表示 1 元）；费率 `val` 为十万分比（0.6% → `"600"`） |
| 枚举 | 状态/类型类字段一律英文语义值（如 `AUDITING`、`FLAT`），不使用数字裸值 |
| 空值 | 空值字段省略，不返回也不上送 |
| 图片 | `multipart/form-data` 上传（单张 ≤5MB），上传后 `key` 7 天有效，录入时以 `category` + `key` 引用 |
| 回调地址 | `back_url` 必须为 HTTPS |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.