> ## 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` |

各接口的完整路径见接口文档「请求地址」，均位于上述前缀之下。

<Note>
  联调与生产环境使用同一网关域名；通过渠道商凭据（app\_key/app\_secret）区分环境，具体以平台开通为准。
</Note>

## 联调参数

联调测试使用的参数由平台开通渠道商时分配，请向对接支持人员索取。示例值（仅演示，不可用于线上）：

| 参数          | 示例值                                |
| ----------- | ---------------------------------- |
| app\_key    | `a1b2c3d4e5f67890a1b2c3d4e5f67890` |
| app\_secret | `f6e5d4c3b2a19087f6e5d4c3b2a19087` |

## 公共请求头

| Header           | 必填 | 说明                                    |
| ---------------- | -- | ------------------------------------- |
| `Content-Type`   | 是  | `application/json`                    |
| `Client-Id`      | 是  | app\_key，32 位十六进制                     |
| `Signature-Type` | 是  | 固定 `HmacSHA256`                       |
| `Timestamp`      | 是  | 秒级时间戳，与平台时间差 ≤ 5 分钟                   |
| `Nonce-Str`      | 是  | 随机串（建议 32 位十六进制），5 分钟内不可重复            |
| `Signature`      | 是  | 请求签名，构造方法见[签名验签说明](../spec/signature) |
| `X-Request-Id`   | 否  | 请求链路标识，可自生成（建议 UUID 类随机串）             |

## 通用响应

| 项              | 说明                                                                                             |
| -------------- | ---------------------------------------------------------------------------------------------- |
| 成功             | HTTP 200，业务数据平铺在 body，无业务码包装                                                                   |
| 失败             | HTTP 4xx/5xx + 统一错误体（`code`/`message`/`detail`/`request_id`），见[返回码说明](../appendix/return-code) |
| `X-Request-Id` | 所有响应头恒带；失败响应 body 的 `request_id` 与之对应                                                          |
| `Signature`    | 响应头携带平台签名（含错误响应），验签方式见[签名验签说明](../spec/signature)                                              |

## 业务字段约定

| 约定 | 说明                                                                |
| -- | ----------------------------------------------------------------- |
| 时间 | 一律秒级时间戳（int64），与签名头 `Timestamp` 一致；日期字段统一格式 `yyyy-MM-dd`          |
| 金额 | 一律为分（int64）                                                       |
| 枚举 | 字符串编码，取值见[枚举值说明](../appendix/enums)                               |
| 空值 | 空值字段省略，不返回也不上送                                                    |
| 附件 | 图片先通过[图片上传](../merchant/file-upload)获取 `key`（7 天有效），进件时以 `key` 引用 |