> For the complete documentation index, see [llms.txt](https://doc.seabird.world/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.seabird.world/jie-kou-gui-ze/xie-yi.md).

# 协议

| 项目           | 说明                 |
| ------------ | ------------------ |
| 传输方式         | HTTP/HTTPS         |
| 提交方式         | POST               |
| 数据格式         | JSON               |
| 字符编码         | UTF-8              |
| Content-Type | `application/json` |
| 网关 Host      | 见 网关               |

## 对接顺序（推荐）

1. 向运营获取测试/正式 `merchant_id`、MD5 密钥；代付还需 RSA，并将出口 IP 加入 **Cloudflare 白名单** 与商户 **IP 白名单**（Block 页会显示实际 IP）。
2. 先跑通 官方签名 Demo，再对照 签名自检清单。
3. 确认签名规则：
   * 代收提单 → 通用验签规则（排序 MD5）
   * 代付提单 v2 → 代付提单签名规则（RSA）
   * 查单 / 余额 → 固定字符串 MD5（见各查询页）
4. 调用代收或代付提单，保存平台返回的 `id`。
5. 以异步回调为主，**务必用查单接口兜底**确认终态。
6. 回调处理完成后，响应纯文本 `SUCCESS`。

## 统一响应结构

### 成功

```json
{
  "code": 200,
  "message": "SUCCESS",
  "data": {}
}
```

### 业务失败

```json
{
  "code": 400,
  "message": "错误原因说明"
}
```

`data` 通常为空或不返回。`message` 为具体失败原因（如签名错误、参数缺失、商户关闭等）。

### 系统异常

未捕获异常时仍返回业务 JSON（`code` 仍为 400）：

```json
{
  "code": 400,
  "message": "request failed,you need connect support staff. - {uuid}"
}
```

请将 `{uuid}` 提供给技术支持排查。

### Cloudflare 拦截（非 JSON）

代付等受 Cloudflare 保护的请求，出口 IP 未加白时，可能收到 **HTML Block 页面**（不是上述 JSON）。Block 页会显示实际出口 IP，请将该 IP 加入 Cloudflare 白名单后重试。详见 网关、代付签名规则。

### 解析建议

1. 先判断响应是否为 JSON；若是 HTML Block，按 IP 加白处理。
2. 再看外层 `code`：`200` 表示接口调用成功，`400` 表示业务/系统失败。
3. 查单类接口：即使 `code=200`，订单是否成功仍以 `data.status` 为准（代收 `0/1`；代付 `1` 处理中 / `2` 成功 / `-2` 失败，失败时可能有 `data.failReason`）。

## 金额单位

所有 `amount`、`fee` 均为**最小货币单位（分）**。例如 INR `10000` = 100.00 INR。