好的，请看这篇为“号易号卡haoyi.hk分销系统官网”的“接口文档”页面撰写的文章，旨在为技术型代理提供API对接的开发指南：
---
**号易号卡haoyi.hk分销系统官网接口文档：技术型代理API对接开发指南**
欢迎您，尊敬的技术型代理！号易号卡(haoyi.hk)分销系统致力于为您提供稳定、高效、易用的API接口，以实现您业务系统与我们的分销平台的无缝对接。通过集成我们的API，您可以自动化地查询账户信息、下单购买号卡、管理订单状态、获取交易明细等，从而显著提升运营效率，拓展业务边界。
本“接口文档”页面是您进行API对接开发的核心参考资料，详细阐述了所有可用的接口、请求参数、响应格式、认证方式及使用示例。我们将按模块为您梳理，助您快速上手，顺利集成。
**一、 准备工作：获取必要凭证**
在开始调用API之前，您需要完成以下准备工作：
1. **注册与认证：** 确保您已在haoyi.hk分销系统官网完成代理注册，并通过了必要的资质审核。
2. **获取API密钥：** 登录您的代理后台，在指定的“API设置”或“开发者中心”区域，申请并获取您的专属 `API Key`（或类似的访问密钥/Token）。**请务必妥善保管此密钥，切勿泄露！** 它是您调用API的身份凭证。
**二、 API基础规范**
为确保API调用的稳定性和一致性，请遵循以下基础规范：
1. **请求方式：** 我们提供多种HTTP请求方法，如 `GET`（用于获取数据）、`POST`（用于提交数据）、`PUT`/`PATCH`（用于更新数据）、`DELETE`（用于删除数据）。具体请参考各接口说明。
2. **请求地址（Endpoint）：** 所有API请求的公共基础地址为 `[请在此处插入实际的API基础域名，例如：api.haoyi.hk/v1]`。具体接口路径将在各接口文档中给出。
3. **请求格式：**
* **请求头 (Headers)：** 通常需要包含认证信息，例如：
* `Authorization: Bearer YOUR_API_KEY` （或根据我们实际使用的认证方式调整）
* `Content-Type: application/json` （对于POST/PUT请求，通常发送JSON格式的数据）
* **请求体 (Body)：** 对于POST、PUT等需要发送数据的请求，数据通常以JSON格式封装在请求体中。
* **查询参数 (Query Parameters)：** 对于GET请求，参数通常通过URL查询字符串传递，例如 `?param1=value1¶m2=value2`。
4. **响应格式：** 绝大多数API响应将以 `JSON` 格式返回。
5. **状态码 (Status Codes)：** 我们遵循标准的HTTP状态码来指示请求结果。例如：
* `200 OK`：请求成功。
* `201 Created`：资源创建成功（如成功下单）。
* `400 Bad Request`：客户端请求错误（如参数缺失、格式错误）。
* `401 Unauthorized`：未授权，API密钥无效或缺失。
* `403 Forbidden`：禁止访问，权限不足。
* `404 Not Found`：请求的资源不存在。
* `500 Internal Server Error`：服务器内部错误。
6. **时区：** 所有涉及时间的字段，除非特别说明，均采用 `UTC` 或 `GMT+8` 时区。请根据您的业务需求进行转换。
**三、 核心API模块介绍**
我们的API主要围绕代理核心业务展开，主要模块包括（具体接口列表请参考下方详细文档）：
1. **账户管理接口：**
* 查询账户余额
* 查询账户信息（如等级、可用优惠券等）
* （可能）查询充值记录
2. **号卡商品接口：**
* 获取号卡商品列表（支持筛选，如运营商、类型、地区等）
* 获取指定商品详情（价格、库存、规格等）
3. **订单管理接口：**
* 创建新订单（下单购买号卡）
* 查询订单列表（支持分页、状态筛选）
* 查询指定订单详情（包括物流信息、状态、实际价格等）
* （可能）取消订单（如支持取消的规则）
4. **交易记录接口：**
* 查询代理的交易流水记录（收入、支出等）
5. **（可能）其他扩展接口：**
* 如获取物流信息、管理子代理（如适用）等。
**四、 详细接口文档与示例**
以下是我们提供的主要API接口列表及简要说明。**请点击具体接口名称或滚动页面查看每个接口的详细参数、请求示例、响应示例和错误码说明。**
* **[GET] /account/balance** - 查询账户余额
* **描述：** 获取当前代理账户的可用余额。
* **请求参数：** 无特殊请求体参数。
* **响应示例：**
```json
{
"code": 200,
"message": "Success",
"data": {
"balance": 10000.50,
"currency": "CNY"
}
}
```
* **[GET] /products/list** - 获取号卡商品列表
* **描述：** 根据条件筛选并获取可购买的号卡商品列表。
* **查询参数：**
* `operator` (可选): 运营商代码 (如 'cmcc', 'unicom', 'telecom')
* `type` (可选): 号卡类型 (如 'prepaid', 'postpaid')
* `province` (可选): 省份代码
* `page` (可选): 页码
* `page_size` (可选): 每页数量
* **响应示例：**
```json
{
"code": 200,
"message": "Success",
"data": {
"total": 150,
"page": 1,
"page_size": 20,
"list": [
{
"product_id": "prod_12345",
"name": "全国通用预付费卡",
"operator": "cmcc",
"price": 99.00,
"stock": 1000
},
...
]
}
}
```
* **[POST] /orders/create** - 创建订单
* **描述：** 提交购买号卡的订单请求。
* **请求体参数：**
* `product_id` (必需): 要购买的商品ID。
* `quantity` (必需): 购买数量。
* `receiver_name` (可选): 收件人姓名。
* `receiver_phone` (必需): 收件人手机号。
* `receiver_address` (可选): 收件地址。
* `note` (可选): 备注信息。
* **响应示例：**
```json
{
"code": 201,
"message": "Order created successfully",
"data": {
"order_id": "order_67890",
"product_id": "prod_12345",
"quantity": 1,
"total_amount": 99.00,
"status": "pending"
}
}
```
* **[GET] /orders/list** - 查询订单列表
* **描述：** 获取当前代理的所有订单列表。
* **查询参数：**
* `status` (可选): 订单状态 (如 'pending', 'paid', 'shipped', 'completed', 'cancelled')
* `start_time` (可选): 开始时间戳
* `end_time` (可选): 结束时间戳
* `page` (可选): 页码
* `page_size` (可选): 每页数量
* **响应示例：** (结构类似商品列表，但 `list` 中的元素是订单信息)
* **[GET] /orders/{order_id}** - 查询指定订单详情
* **描述：** 获取单个订单的详细信息。
* **路径参数：**
* `order_id`: 要查询的订单ID。
* **响应示例：**
```json
{
"code": 200,
"message": "Success",
"data": {
"order_id": "order_67890",
"product_id": "prod_12345",
"product_name": "全国通用预付费卡",
"quantity": 1,
"total_amount": 99.00,
"status": "shipped",
"create_time": "2023-08-01T12:00:00Z",
"update_time": "2023-08-01T12:30:00Z",
"tracking_number": "SF123456789CN",
"shipping_method": "SFExpress"
}
}
```
* **[GET] /transactions/list** - 查询交易记录
* **描述：** 获取当前代理的交易流水记录。
* **查询参数：**
* `type` (可选): 交易类型 (如 'income', 'expense')
* `start_time` (可选): 开始时间戳
* `end_time` (可选): 结束时间戳
* `page` (可选): 页码
* `page_size` (可选): 每页数量
* **响应示例：** (结构类似订单列表，但 `list` 中的元素是交易记录)
**五、 错误处理与排查**
* **统一错误码：** 我们会返回标准的HTTP状态码，并在JSON响应的 `code` 和 `message` 字段中提供更详细的错误信息。
* **常见问题排查：**
* **401 Unauthorized：** 检查API密钥是否正确填写、是否已过期或被禁用。
* **400 Bad Request：** 检查请求参数是否符合要求（类型、必填项、格式），请求体JSON是否格式正确。
* **404 Not Found：** 检查请求的URL路径或查询的 `product_id`、`order_id` 是否存在。
* **500 Internal Server Error：** 这是我们的服务器端错误，请联系我们的技术支持团队。
* **日志记录：** 建议您在开发过程中，详细记录所有API请求的请求头、请求体、URL、响应状态码和响应体，以便于排查问题。
**六、 技术支持与反馈**
* **遇到问题？** 请首先仔细查阅本接口文档。如果问题仍未解决，请通过 [请在此处插入支持渠道，例如：官网的帮助中心、客服邮箱 support@haoyi.hk、QQ群 XXXXXXXX] 联系我们的技术支持团队。
* **功能建议？** 我们欢迎您提出宝贵的API功能建议或改进意见，请通过 [请在此处插入反馈渠道] 进行反馈，帮助我们共同打造更完善的API服务体系。
**结语**
号易号卡(haoyi.hk)分销系统的API接口旨在成为您业务增长的有力工具。我们致力于提供稳定可靠的接口服务。请仔细阅读并理解本开发指南及后续的详细接口文档，开始您的API集成之旅吧！我们期待与您携手，共创价值。
---