> ## 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://gw.xft.xin/openapi`                                              |
| 提交方式 | 全部采用 **POST** + 固定路径，不使用路径参数；业务标识（`out_apply_no`、`merchant_code` 等）一律放在请求 body |
| 数据格式 | JSON，字符编码统一 UTF-8，`Content-Type: application/json`                             |
| 签名   | app\_key 对称签名（HMAC-SHA256），见[签名验签说明](../spec/signature)                        |
| 请求标识 | 每次请求响应头恒带 `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`      | 请求签名，见[签名验签说明](../spec/signature)          | 是  |
| `X-Request-Id`   | 请求链路标识，可自生成；不传则由平台生成                       | 否  |

## 请求报文

```json theme={null}
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`：

```json theme={null}
{
  "out_apply_no": "P20260815001",
  "apply_no": "AP2026081500001",
  "apply_status": "AUDITING",
  "timestamp": 1755234000
}
```

### 失败响应

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

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

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

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

## 公共约定

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