API 接口文档
本 API 使用 OAuth2.0 协议进行身份认证。客户端在调用业务接口之前，必须先获取 Access Token，并在请求头中携带该 Token。
环境信息
| 项目 | 地址 |
|---|---|
| 授权端点 | https://httpsAPI/public/authorize.php |
| Token 端点 | https://httpsAPI/public/token.php |
| 库存查询接口 | https://httpsAPI/public/worehouse.php |
| 订单查询接口 | https://httpsAPI/public/sorder.php |
| 销售出库单查询接口 | https://httpsAPI/public/outbound.php |
一、OAuth2.0 认证
本系统支持两种 OAuth2.0 授权方式：
Authorization Code Grant
授权码模式，适用于有用户交互的 Web 应用，安全性最高。
Client Credentials Grant
客户端凭证模式，适用于服务器间后台通信，无需用户参与。
前置条件
联系服务提供方注册您的应用，获取以下凭据：
| 参数 | 说明 |
|---|---|
client_id | 客户端唯一标识 |
client_secret | 客户端密钥（请妥善保管） |
redirect_uri | 授权回调地址（仅授权码模式需要） |
方式一：Authorization Code Grant（授权码模式）
适用于需要用户授权的 Web 应用。
流程概览
客户端
授权服务器
① 重定向用户到授权页面
→
←
② 用户同意授权
③ 接收授权码
redirect_uri?code=xxx&state=yyy←
④ 用授权码换 Token
POST /token.php→
←
⑤ 返回 Access Token
⑥ 调用业务接口
Authorization: Bearer <token>→
←
⑦ 返回业务数据
1
引导用户访问授权页面
将用户浏览器重定向到授权端点：
GET /public/authorize.php?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&state={STATE}| 参数 | 必填 | 说明 |
|---|---|---|
response_type | 是 | 固定值 code |
client_id | 是 | 注册时获得的客户端 ID |
redirect_uri | 是 | 授权成功后的回调地址，必须与注册时一致 |
state | 否 | 防 CSRF 攻击的随机字符串，将在回调中原样返回 |
2
用户在授权页面确认
用户将在授权页面看到您的应用名称，点击"同意授权"。
3
接收授权码
用户确认后，浏览器重定向到 redirect_uri，携带以下参数：
GET {REDIRECT_URI}?code={AUTHORIZATION_CODE}&state={STATE}
安全提醒：务必验证
state 与您发送的完全一致，以防 CSRF 攻击。
4
用授权码换取 Access Token
POST /public/token.php
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code={AUTHORIZATION_CODE}
&client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}
&redirect_uri={REDIRECT_URI}| 参数 | 必填 | 说明 |
|---|---|---|
grant_type | 是 | 固定值 authorization_code |
code | 是 | 上一步获取的授权码（一次性使用，有效期 10 分钟） |
client_id | 是 | 客户端 ID |
client_secret | 是 | 客户端密钥 |
redirect_uri | 是 | 必须与第 1 步使用的完全一致 |
也支持 HTTP Basic Auth 传递客户端凭据：
Authorization: Basic base64(client_id:client_secret)5
接收 Access Token
200 成功响应：
{
"access_token": "8843534fa0deed...064c0ca20329d4acc4062",
"token_type": "Bearer",
"expires_in": 3600
}| 字段 | 说明 |
|---|---|
access_token | 访问令牌 |
token_type | 令牌类型，固定为 Bearer |
expires_in | 有效期（秒），默认 3600 即 1 小时 |
错误响应：
{
"error": "invalid_grant",
"error_description": "Authorization code expired"
}方式二：Client Credentials Grant（客户端凭证模式）
适用于服务器到服务器的后台通信，无需用户交互。
请求 Token
POST /public/token.php
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}也支持 HTTP Basic Auth：
curl -X POST https://httpsAPI/public/token.php \
-u "{CLIENT_ID}:{CLIENT_SECRET}" \
-d "grant_type=client_credentials"200 成功响应：
{
"access_token": "8843534fa0deed...064c0ca20329d4acc4062",
"token_type": "Bearer",
"expires_in": 3600
}二、调用业务接口
所有业务接口均需在请求头中携带 Access Token：
Authorization: Bearer {ACCESS_TOKEN}库存查询接口
基本信息
| 项目 | 说明 |
|---|---|
| 路径 | /public/worehouse.php |
| 方法 | GET 或 POST |
| 认证 | Bearer Token（必填） |
请求参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
day | string | 否 | 1 | 查询日期，如：2026-05-10 |
page | int | 否 | 1 | 页码 |
page_size | int | 否 | 20 | 每页数量，最大 100 |
请求示例
curl "https://httpsAPI/public/worehouse.php?day=2026-05-06&page=1&page_size=10" \
-H "Authorization: Bearer 8843534fa0deed...4c0ca20329d4acc4062"成功响应
{
"code": 0,
"message": "ok",
"data": {
"list": [
{
"organization_name": "科勒集团",
"organization_code": "KL",
"warehouse_id": "0001",
"warehouse_name": "大库",
"sku_id": "EB1446-NF",
"inventory_cnt": "1.00000000",
"create_at": "2026-05-08",
"update_at": "2026-05-08"
},
{
"organization_name": "科勒集团",
"organization_code": "KL",
"warehouse_id": "0001",
"warehouse_name": "大库",
"sku_id": "P24490-LV-CP",
"inventory_cnt": "1.00000000",
"create_at": "2026-05-08",
"update_at": "2026-05-08"
},
{
"organization_name": "科勒集团",
"organization_code": "KL",
"warehouse_id": "0001",
"warehouse_name": "大库",
"sku_id": "K-23796T-1-0",
"inventory_cnt": "1.00000000",
"create_at": "2026-05-08",
"update_at": "2026-05-08"
}
],
"pagination": {
"page": 1,
"page_size": 3,
"total": 1284,
"total_pages": 65
}
}
}订单查询接口
基本信息
| 项目 | 说明 |
|---|---|
| 路径 | /public/sorder.php |
| 方法 | GET 或 POST |
| 认证 | Bearer Token（必填） |
请求参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
day | string | 否 | 1 | 查询日期，如：2026-05-06 |
page | int | 否 | 1 | 页码 |
page_size | int | 否 | 20 | 每页数量，最大 100 |
请求示例
curl "https://httpsAPI/public/sorder.php?day=2026-05-06&page=1&page_size=10" \
-H "Authorization: Bearer 8843534fa0deed...4c0ca20329d4acc4062"成功响应
{
"code": 0,
"message": "ok",
"data": {
"list": [
{
"organization_name": "科勒",
"billid": 10,
"organization_code": "KL",
"exhibition_hall_sn": "0003",
"exhibition_hall_name": "业务",
"order_sn": "SO-2026-05-00001",
"billdate": "2026-05-06 00:00:00",
"create_at": "2026-05-08 14:30:08.573131",
"order_type": "销售订单",
"order_status": "审核",
"updated_at": "2026-05-08 14:30:08",
"follow_order_flag": null,
"original_order_sn": null,
"withdraw_order_flag": null,
"withdraw_order_sn": null,
"completed_at": "2026-05-08 14:30:08.573131",
"total_amount": "110606.00",
"return_flag": null,
"return_and_exchange_order_sn": null,
"customer_type": null,
"customer_code": "bjsjjygwzxgz",
"receiver_sn": null,
"receiver_province": null,
"receiver_cit": null,
"receiver_area": null,
"order_channel_source": null,
"salesperson_code": "03",
"product_info": [
{
"billid": 10,
"sku_id": "K-2215T-M-0",
"product_type": null,
"number": "11.00000000",
"price": "220.00000000",
"total": "11.00000000",
"batch_sn": null
},
{
"billid": 10,
"sku_id": "K-20441T-0",
"product_type": null,
"number": "50.00000000",
"price": "310.00000000",
"total": "50.00000000",
"batch_sn": null
},
{
"billid": 10,
"sku_id": "K-32787T-NA",
"product_type": null,
"number": "43.00000000",
"price": "660.00000000",
"total": "43.00000000",
"batch_sn": null
},
{
"billid": 10,
"sku_id": "K-23056T-CP",
"product_type": null,
"number": "38.00000000",
"price": "1167.00000000",
"total": "38.00000000",
"batch_sn": null
},
{
"billid": 10,
"sku_id": "K-30764T-ST",
"product_type": null,
"number": "7.00000000",
"price": "600.00000000",
"total": "7.00000000",
"batch_sn": null
},
{
"billid": 10,
"sku_id": "K-EX39738T-9WPL-RGD",
"product_type": "精选",
"number": "1.00000000",
"price": "1566.00000000",
"total": "1.00000000",
"batch_sn": null
},
{
"billid": 10,
"sku_id": "K-11626T-2MB",
"product_type": "常规品",
"number": "2.00000000",
"price": "109.00000000",
"total": "2.00000000",
"batch_sn": null
},
{
"billid": 10,
"sku_id": "K-26340T-NA",
"product_type": "精选",
"number": "2.00000000",
"price": "1158.00000000",
"total": "2.00000000",
"batch_sn": null
},
{
"billid": 10,
"sku_id": "K-11137T-0",
"product_type": "常规品",
"number": "10.00000000",
"price": "1166.00000000",
"total": "10.00000000",
"batch_sn": null
}
]
}
],
"pagination": {
"page": 1,
"page_size": 10,
"total": 1,
"total_pages": 1
}
}
}销售出库单查询接口
基本信息
| 项目 | 说明 |
|---|---|
| 路径 | /public/outbound.php |
| 方法 | GET 或 POST |
| 认证 | Bearer Token（必填） |
请求参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
day | string | 否 | 1 | 查询日期，如：2026-04-29 |
page | int | 否 | 1 | 页码 |
page_size | int | 否 | 20 | 每页数量，最大 100 |
请求示例
curl "https://httpsAPI/public/outbound.php?day=2026-04-29&page=1&page_size=10" \
-H "Authorization: Bearer 8843534fa0deed...4c0ca20329d4acc4062"成功响应
{
"code": 0,
"message": "ok",
"data": {
"list": [
{
"organization_name": "科勒",
"organization_code": "KL",
"exhibition_hall_sn": "0001",
"exhibition_hall_name": "采购",
"order_sn": "SS202604-1007788",
"billid": 11,
"create_at": "2026-05-08 13:24:00.532481",
"order_type": "销售单",
"order_status": "审核",
"updated_at": "2026-05-08 00:00:00",
"follow_order_flag": null,
"original_order_sn": null,
"withdraw_order_flag": null,
"withdraw_order_sn": null,
"completed_at": "2026-04-29 00:00:00",
"total_amount": "315880.00",
"return_flag": null,
"return_and_exchange_order_sn": null,
"delivery_at": "2026-04-29 00:00:00",
"customer_type": null,
"customer_code": "hfsjjybh",
"receiver_sn": null,
"receiver_province": null,
"receiver_city": null,
"receiver_area": null,
"order_channel_source": null,
"salesperson_code": "01",
"product_info": [
{
"billid": 11,
"sku_id": "K-32370T-0",
"product_type": null,
"number": "4.00000000",
"price": "2646.11000000",
"total": "4.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-32372T-0",
"product_type": null,
"number": "2.00000000",
"price": "2358.39000000",
"total": "2.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-33069T-4-CP",
"product_type": null,
"number": "5.00000000",
"price": "581.40000000",
"total": "5.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-31240T-4-CP",
"product_type": null,
"number": "6.00000000",
"price": "621.24000000",
"total": "6.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-2214T-0",
"product_type": "常规品",
"number": "1.00000000",
"price": "311.06000000",
"total": "1.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-2215T-M-0",
"product_type": null,
"number": "4.00000000",
"price": "311.06000000",
"total": "4.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-76509K-0",
"product_type": null,
"number": "9.00000000",
"price": "679.29000000",
"total": "9.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-99742T-C9-CP",
"product_type": null,
"number": "6.00000000",
"price": "1730.60000000",
"total": "6.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-21919T-2PD-NA",
"product_type": null,
"number": "2.00000000",
"price": "1247.61000000",
"total": "2.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-31084T-2HD-UM1",
"product_type": null,
"number": "2.00000000",
"price": "1247.61000000",
"total": "2.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-97830T-N-NA",
"product_type": null,
"number": "2.00000000",
"price": "1198.33000000",
"total": "2.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-22867T-4-BL",
"product_type": null,
"number": "2.00000000",
"price": "907.63000000",
"total": "2.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-99175T-B4-CP",
"product_type": null,
"number": "3.00000000",
"price": "602.12000000",
"total": "3.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-30910T-S-0",
"product_type": null,
"number": "5.00000000",
"price": "1243.20000000",
"total": "5.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-15847T-0",
"product_type": null,
"number": "2.00000000",
"price": "568.48000000",
"total": "2.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-17295T-0",
"product_type": null,
"number": "2.00000000",
"price": "174.42000000",
"total": "2.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-72292T-4-CP",
"product_type": null,
"number": "2.00000000",
"price": "1312.57000000",
"total": "2.00000000",
"source_order_sn": null,
"batch_sn": null
},
{
"billid": 11,
"sku_id": "K-33092T-B9-CP",
"product_type": "常规品",
"number": "4.00000000",
"price": "6480.00000000",
"total": "4.00000000",
"source_order_sn": null,
"batch_sn": null
}
]
}
],
"pagination": {
"page": 1,
"page_size": 10,
"total": 1,
"total_pages": 1
}
}
}未授权响应 401
{
"code": -1,
"message": "Missing or malformed Authorization header",
"data": null
}Token 过期响应 401
{
"code": -1,
"message": "Access token expired",
"data": null
}三、公共响应格式
所有业务接口统一使用以下 JSON 结构：
{
"code": 0,
"message": "ok",
"data": { ... }
}| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 0 成功；-1 认证/授权错误；其他负数表示业务错误 |
message | string | 状态描述 |
data | object | array | null | 业务数据，失败时为 null |
四、完整接入示例（PHP）
<?php
$baseUrl = 'https://httpsAPI/public';
$clientId = 'your_client_id';
$clientSecret = 'your_client_secret';
// 1. 获取 Access Token（Client Credentials 模式）
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $baseUrl . '/token.php',
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query([
'grant_type' => 'client_credentials',
'client_id' => $clientId,
'client_secret' => $clientSecret,
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
if (!isset($response['access_token'])) {
die('获取 Token 失败: ' . json_encode($response));
}
$accessToken = $response['access_token'];
// 2. 调用 worehouse 查询接口
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $baseUrl . '/worehouse.php?keyword=Alpha&page=1&page_size=10',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $accessToken,
],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
if ($response['code'] === 0) {
print_r($response['data']);
} else {
echo '请求失败: ' . $response['message'];
}五、完整接入示例（cURL 命令行）
# 1. 获取 Token
TOKEN=$(curl -s -X POST "https://httpsAPI/public/token.php" \
-d "grant_type=client_credentials" \
-d "client_id=your_client_id" \
-d "client_secret=your_client_secret" \
| python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
# 2. 调用 worehouse 接口
curl -s "https://httpsAPI/public/worehouse.php?keyword=Alpha" \
-H "Authorization: Bearer $TOKEN"六、错误码参考
OAuth2.0 错误（Token 端点）
| 错误码 | 说明 |
|---|---|
invalid_request | 请求参数缺失或格式错误 |
invalid_client | 客户端凭据无效 |
invalid_grant | 授权码无效、已过期或已使用 |
unsupported_grant_type | 不支持的 grant_type（仅支持 authorization_code 和 client_credentials） |
unauthorized_client | 客户端未注册 |
业务接口错误
| code | 说明 |
|---|---|
0 | 成功 |
-1 | 未授权（Token 缺失、无效或过期） |
七、最佳实践
- 安全保管
client_secret— 不要将其暴露在前端代码或版本控制中 - Token 复用 — 在 Token 有效期内复用同一个 Token，避免频繁请求 Token 端点
- 提前刷新 — 在 Token 过期前提前换取新 Token，避免请求中断
- 错误重试 — 当收到 401 错误时，重新获取 Token 后重试
- HTTPS — 生产环境请务必使用 HTTPS，防止 Token 被中间人截获
— End of Document —