Appearance

订单管理 API ​

1. 接口概述 ​

订单管理 API 提供了订单信息的查询功能。通过这些接口，您可以获取系统中的订单列表信息，支持按时间范围、店铺编码、订单号等条件进行筛选。

2. 接口列表 ​

接口名方法功能描述
orders.getListPOST获取订单列表
orders.getCouponListPOST获取优惠券列表
orders.getPmtListPOST获取支付方式列表

3. 系统级参数 ​

系统级参数是调用所有接口都必须提供的参数：

参数名类型必填名称描述
methodstring是接口方法名例如：orders.getList
app_keystring是应用密钥用于标识调用方身份
timestampstring是时间戳时间戳，格式：10位时间戳
formatstring是响应格式可选值：json
vstring是API版本例如：1.0
signstring是签名用于验证请求的合法性

4. 接口详细说明 ​

4.1 获取订单列表 ​

4.1.1 功能描述 ​

获取系统中的订单列表信息，支持按时间范围、店铺编码、订单号等条件进行筛选。

4.1.2 请求参数 ​

参数名类型必填描述
start_timestring是开始时间（格式：yyyy-MM-dd HH:mm:ss）
end_timestring是结束时间（格式：yyyy-MM-dd HH:mm:ss）
page_noint是页码，默认 1
page_sizeint是每页条数，最小1，最大 1000
shop_bnstring否店铺编码
order_bnstring否订单编号
statusstring否订单状态
pay_statusstring否支付状态
ship_statusstring否发货状态
paymentstring否支付方式

4.1.3 响应参数 ​

参数名类型描述
countint总记录数
listsarray订单列表

lists 数组中的每个对象包含以下字段：

参数名类型描述
order_bnstring订单编号
shop_bnstring店铺编码
shop_namestring店铺名称
buyer_namestring买家名称
consignee_namestring收货人姓名
consignee_mobilestring收货人手机号
consignee_provincestring收货省份
consignee_citystring收货城市
consignee_countystring收货区县
consignee_addressstring收货地址
consignee_zipstring邮政编码
createtimestring创建时间
last_modifiedstring最后修改时间
total_amountdecimal订单总金额
paymentstring支付方式
payment_namestring支付方式名称
shippingstring配送方式
shipping_namestring配送方式名称
freightdecimal运费
discountdecimal折扣金额
order_statusstring订单状态
order_status_namestring订单状态名称
pay_statusstring支付状态
pay_status_namestring支付状态名称
shipping_statusstring配送状态
shipping_status_namestring配送状态名称
channelstring订单来源渠道
channel_namestring订单来源渠道名称
remarkstring订单备注
itemsarray订单商品明细

items 数组中的每个对象包含以下字段：

参数名类型描述
bnstring商品编码
namestring商品名称
spec_infostring规格信息
unitstring单位
pricedecimal商品价格
numsint商品数量
amountdecimal商品金额
barcodestring条码

4.1.4 请求示例 ​

http
<?php
// 应用标识（需要替换为实际的flag）
$flag = 'your_oms_flag';

// 私钥（需要替换为实际的token）
$token = 'your_interface_key';

// 接口方法（例如，查询订单列表：orders.getList）
$method = 'orders.getList';

// 系统级参数
$systemParams = array(
    'flag' => $flag, // 应用标识
    'method' => $method, // 接口方法
    'ver' => 1,
    'charset' => 'utf-8',
    'type' => 'json',
    'timestamp' => time(),
);

// 应用级参数
$ApiParams = array(
    'start_time' => '2025-10-01 00:00:00',
    'end_time' => '2025-11-01 00:00:00',
    'page_no' => 1,
    'page_size' => 50
);

// 组装接口参数
$params = array_merge($systemParams, $ApiParams);

// 签名生成函数
function gen_sign($params, $token)
{
    // 参数排序
    ksort($params, SORT_STRING);
    
    // 拼接字符串
    $assemble_str = '';
    foreach($params AS $key=>$val){
        if(is_null($val)) continue;
        if(is_bool($val)) $val = ($val) ? 1 : 0;
        $assemble_str .= $key . (is_array($val) ? assemble($val) : $val);
    }
    
    // 生成签名
    return strtoupper(md5(strtoupper(md5($assemble_str)).$token));
}

// 递归拼接数组参数
function assemble($params)
{
    if(!is_array($params)) return null;
    
    ksort($params, SORT_STRING);
    
    $sign = '';
    foreach($params AS $key=>$val){
        if(is_null($val)) continue;
        if(is_bool($val)) $val = ($val) ? 1 : 0;
        $sign .= $key . (is_array($val) ? assemble($val) : $val);
    }
    
    return $sign;
}

// 生成签名
$params['sign'] = gen_sign($params, $token);

// curl发送请求
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http(s)://www.***.com/index.php/openapi/rpc/service/');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

// 处理响应
$result = json_decode($response, true);

// 测试Api接口返回的结果
echo('<pre>Response：<br>');
print_r($response);
echo('<br><br>Result：<br>');
print_r($result);
exit;

4.1.5 响应示例 ​

json
{
  "count": 100,
  "lists": [
    {
      "order_bn": "SO202401010001",
      "shop_bn": "SHOP001",
      "shop_name": "测试店铺",
      "buyer_name": "test_buyer",
      "consignee_name": "张三",
      "consignee_mobile": "13800138000",
      "consignee_province": "北京市",
      "consignee_city": "北京市",
      "consignee_county": "朝阳区",
      "consignee_address": "测试路1号",
      "consignee_zip": "100000",
      "createtime": "2024-01-01 10:00:00",
      "last_modified": "2024-01-01 10:30:00",
      "total_amount": 1000.00,
      "payment": "alipay",
      "payment_name": "支付宝",
      "shipping": "express",
      "shipping_name": "快递",
      "freight": 10.00,
      "discount": 0.00,
      "order_status": "active",
      "order_status_name": "已下单",
      "pay_status": "succ",
      "pay_status_name": "已支付",
      "shipping_status": "unshipped",
      "shipping_status_name": "未发货",
      "channel": "pc",
      "channel_name": "PC端",
      "remark": "测试订单",
      "items": [
        {
          "bn": "PROD001",
          "name": "测试商品",
          "spec_info": "规格信息",
          "unit": "个",
          "price": 100.00,
          "nums": 10,
          "amount": 1000.00,
          "barcode": "1234567890123"
        }
      ]
    }
  ]
}

4.2 获取优惠券列表 ​

4.2.1 功能描述 ​

获取系统中的优惠券列表信息，支持按优惠券名称、类型等条件进行筛选。

4.2.2 请求参数 ​

参数名类型必填描述
page_noint是页码，默认 1
page_sizeint是每页条数，默认 50，最大 1000
coupon_namestring否优惠券名称
coupon_typestring否优惠券类型

4.2.3 响应参数 ​

参数名类型描述
countint总记录数
listsarray优惠券列表

lists 数组中的每个对象包含以下字段：

参数名类型描述
coupon_idint优惠券 ID
coupon_namestring优惠券名称
coupon_typestring优惠券类型
coupon_type_namestring优惠券类型名称
valuedecimal优惠金额/折扣
min_amountdecimal最低消费金额
start_timestring有效期开始时间
end_timestring有效期结束时间
statusstring状态

4.2.4 请求示例 ​

http
POST /api/open/orders/getCouponList HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

method=orders.getCouponList&app_key=your_app_key&timestamp=2024-01-01%2000:00:00&format=json&v=1.0&sign=your_signature&page_no=1&page_size=50

4.2.5 响应示例 ​

json
{
  "count": 10,
  "lists": [
    {
      "coupon_id": 1,
      "coupon_name": "满100减10元优惠券",
      "coupon_type": "minus",
      "coupon_type_name": "满减券",
      "value": 10.00,
      "min_amount": 100.00,
      "start_time": "2024-01-01 00:00:00",
      "end_time": "2024-12-31 23:59:59",
      "status": "active"
    }
  ]
}

4.3 获取支付方式列表 ​

4.3.1 功能描述 ​

获取系统中的支付方式列表信息。

4.3.2 请求参数 ​

参数名类型必填描述
page_noint是页码，默认 1
page_sizeint是每页条数，默认 50，最大 1000
payment_namestring否支付方式名称

4.3.3 响应参数 ​

参数名类型描述
countint总记录数
listsarray支付方式列表

lists 数组中的每个对象包含以下字段：

参数名类型描述
payment_idint支付方式 ID
paymentstring支付方式标识
payment_namestring支付方式名称
statusstring状态

4.3.4 请求示例 ​

http
POST /api/open/orders/getPmtList HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

method=orders.getPmtList&app_key=your_app_key&timestamp=2024-01-01%2000:00:00&format=json&v=1.0&sign=your_signature&page_no=1&page_size=50

4.3.5 响应示例 ​

json
{
  "count": 5,
  "lists": [
    {
      "payment_id": 1,
      "payment": "alipay",
      "payment_name": "支付宝",
      "status": "active"
    },
    {
      "payment_id": 2,
      "payment": "wechat",
      "payment_name": "微信支付",
      "status": "active"
    }
  ]
}

5. 错误码说明 ​

错误码错误信息解决方案
0成功-
1001非法的app_key请检查app_key是否正确
1002请求已过期请检查timestamp是否正确，请求有效期为5分钟
1003签名错误请检查签名算法和参数是否正确
1004不支持的format格式请使用json格式
2001缺少必要的参数请检查请求参数是否完整
2002非法的请求参数请检查参数格式和范围是否正确
2003接口不存在请检查接口方法名是否正确
e000001system params lost or error系统级参数缺失或错误
e000002sign error签名错误，请检查签名算法和参数
e000003class or method not exist接口类或方法不存在
e000004no permissions to access没有权限访问该接口
e000005init interface fail初始化接口失败
e000006application params error应用级参数错误
e000007init template fail初始化模板失败
e000008refer server time invalid时间戳无效，与服务器时间偏差过大
e000009repeat request invalid重复请求，签名已存在于缓存中

6. 注意事项 ​

  1. 时间格式必须为：时间戳，格式：10位时间戳，否则可能导致查询失败。
  2. page_size 参数最大支持 1000，超过将被限制为 100。
  3. 对于大数据量的查询，建议使用时间范围进行筛选，以提高查询效率。
  4. 请妥善保管接口密钥，避免泄露。
  5. 时间戳必须与服务器时间保持同步，误差不超过3600秒。
  6. 每个请求必须生成唯一的签名，避免重复提交。
  7. 所有请求参数中的特殊字符必须进行 URL 编码，特别是在使用 GET 方法时。
  8. 请确保在请求头中设置正确的 Content-Type，对于 POST 请求建议使用 application/json。
  9. 为了系统性能和稳定性，请避免短时间内发送大量请求，建议控制调用频率。
  10. 敏感数据（如签名、密钥等）请勿在日志中记录，确保数据安全。