148 lines
3.8 KiB
Markdown
148 lines
3.8 KiB
Markdown
# 铱云易订货 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)
|
||
```
|