# 铱云易订货 OpenAPI 2.0 接口文档

> 文档地址：http://openapi-doc.77ircloud.com/
> API 基础地址：https://openapi.77ircloud.com

## 认证流程

### 获取 Access Token

**⚠️ 重要：文档描述有误，实际接口信息如下**

| 项目 | 说明 |
|------|------|
| URL | `https://openapi.77ircloud.com/v2/oauth2/token` |
| 方法 | **GET**（文档写的是 POST，实际是 GET） |
| 参数位置 | URL 查询字符串 |

**请求参数：**
| 参数 | 必填 | 说明 | 示例 |
|------|------|------|------|
| userName | ✅ | 铱云系统登录账号 | 112983083 |
| password | ✅ | 铱云系统登录密码 | 77ircloud |
| client_id | ✅ | API 客户端ID | 6767358 |
| client_secret | ✅ | API 密钥 | 1gk9ApiWV8IA2QrVDnU6Dx7uUo7CLuN2 |
| grant_type | ✅ | 授权类型，固定值 | client_credentials |
| scope | ✅ | 作用域，固定值 | basic |

**响应格式：**
```json
{
  "code": 200,
  "data": {
    "access_token": "b615caeda3562eece7fcf834923685ee3607084",
    "create_time": 1774593254433,
    "expires_in": 2592000,
    "refresh_token": "8caf350dc4f013201af6a10efbf3fecd",
    "scope": "basic",
    "extra": {
      "enabledPassPort": null,
      "hasMoreAccount": null,
      "userId": null,
      "userName": null,
      "userType": null
    },
    "nodeCode": ""
  },
  "message": "操作成功"
}
```

**错误响应：**
```json
{"code":153,"data":null,"message":"illegal client_id"}
```
- `illegal client_id` = client_id 未开通 API 权限

---

## 订单接口

### 订单审核

| 项目 | 说明 |
|------|------|
| URL | `https://openapi.77ircloud.com/order-aggregation/organizations/orders/order-audit` |
| 方法 | **PUT** |
| 认证 | Header: `access_token: {token}` |

**请求 Body：**
```json
{
  "ids": [2384840119003488, 2384830331153312]
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ids | long[] | ✅ | 订单ID数组，可同时审核多个订单 |

**响应：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": []
}
```

**常见错误：**
- `ids: must not be empty` - 未传入订单ID数组
- `illegal parameters!` - 参数格式错误

---

## 客户接口

### 客户列表查询

| 项目 | 说明 |
|------|------|
| URL | `https://openapi.77ircloud.com/openapi/customer/list` |
| 方法 | **POST** |
| 认证 | Header: `access_token: {token}` |

**请求 Body：**
```json
{
  "pageNum": 1,
  "pageSize": 10
}
```

---

## 注意事项

1. **接口方法可能与文档不符**：建议先用 POST 测试，收到 400 错误再切换方法
2. **时间参数必须成对**：startCreateTime 和 endCreateTime 要么都提供，要么都不提供
3. **Token 有效期**：30 天，过期后重新获取
4. **审核接口**：使用 PUT 方法，参数为订单 ID 数组

---

## ⚠️ 重要 Bug：订单查询接口的时间过滤参数不生效

**问题描述：**
实测发现 `startCreateTime` / `endCreateTime` 参数完全无效——无论传入什么值，API 都返回全部数据，后端过滤逻辑未实现。

**验证过程：**
- 传入精确到毫秒的时间范围（如只查1秒：startCreateTime=1773990796000, endCreateTime=1773990796001）
- API 仍返回全部 99 条订单，totalCount 也仍是 99

**createTime 单位：** 确认是毫秒时间戳（13位），如 `1773990796000` = `2026-03-20 14:xx GMT+8`

**正确做法：**
1. 调用 API 时不传时间过滤参数，拉取全部数据
2. 在本地用 `createTime` 字段过滤指定日期范围
3. 可用订单号日期编码校验（格式：`CA000000-260320-78534` → 2026-03-20）

**订单号日期提取方法：**
```python
def parse_order_date(order_code):
    # 格式: CA{yymmdd}-{seq}  例如 CA000000-260320-78534
    yymmdd = order_code.replace('CA','').split('-')[1]
    yy, mm, dd = int('20'+yymmdd[:2]), int(yymmdd[2:4]), int(yymmdd[4:6])
    return datetime.date(yy, mm, dd)
```