当前位置： API文档 > 订单类

logistics_sync_query.php（查询物流同步）

¥标准

1.接口说明

1.1 接口描述：旺店通ERP销售订单的发货状态、物流单号等同步给其他系统，注：”查询物流同步”与“物流同步回写”两个接口配合使用，完成“销售订单发货同步”，仅支持自有/其它平台店铺
1.2 适用版本：客户端 V2.4.5.1及以上版本
1.3 调用建议：物流同步业务分两部分，一部分是数据抓取，另一部分是状态回写，建议每五分钟从待同步物流数据池中，抓取一次物流数据，每次100条，处理完成一百条之后，把成功或者失败状态回写到OMS中，如此循环，直到数据池中取不出数据为止。

1.4 注意事项：①本接口logistics_sync_query是与logistics_sync_ack（物流同步状态回写）配合调用的，调用一次logistics_sync_query获得的待同步物流信息处理完成后，需要调用logistics_sync_ack响应同步结果；②测试环境如何测试物流同步请看本文档最下边的附录说明。

1.4  常见场景处理：                 

1.4. 1拆分发货：商城推送过来的是一个订单，但是因为实际情况需要（例：库存不足有货先发），在ERP系统拆分开了，分开发货。

①：商城订单只有一条货品明细，且货品数量>=2被拆分成多个系统订单的

  •   一个tid对应一个oid，num>=2,拆分后的多个系统订单tid和oid相同，此情景下拆分后的多个系统单，只有一个系统订单可成功同步物流单号，其余系统单不同步。

②：商城订单有多条货品明细，被拆分成多个系统订单的

  • 一个tid对应多个oid，拆分后的多个系统订单tid相同、oid不同，此情景下拆分后的多个系统单，每个系统订单可以同步一个单号

③注意事项：

  • 物流同步时物流单号对应的最小维度是子订单（oid），一个子订单只能同步一个单号

  • 需要在客户端设置--系统设置--订单设置中勾选自有平台拆单发货的配置，否则一个平台订单编号只能回传一个物流单号

  • 平台（商城、官网等）必须支持拆分发货功能


1.4.2 多包裹发货：ERP系统内单个订单包含的货品数量过多或者重量过重，因实际包装需要或物流公司要求（例如：单个包裹不能超过5kg），此时单个订单需要打印多个物流单进行发货。

①：单个系统订单，实际多个包裹发货，每个包裹对应一个物流单号

  • 一个trade_no,对应多个logistics_no，此情景下与系统订单包含子订单（oid）条数无关，只能同步一个物流单号


2.调用场景

2.1 自研商城、分销系统、全渠道等系统对接

3.请求参数说明

   3.1 请求地址

环境HTTP地址
测试环境https://sandbox.wangdian.cn/openapi2/logistics_sync_query.php
正式环境https://api.wangdian.cn/openapi2/logistics_sync_query.php

   3.2 公共请求参数

名称字段类型长度
必须描述
卖家账号sidString
是购买ERP时由旺店通分配给ERP购买方，请从ERP购买方获取。
接口账号appkeyString
是本开放平台“自助对接”功能模块内自助申请，获取方式点击这里
时间戳timestampint
是北京时间1970-01-01 08:00:00起至现在的总秒数，10位int值,旺店通企业版API服务端允许请求最大时间误差为5min，date.timezone = Asia/Shanghai。
签名signString
是API输入参数签名结果，签名算法介绍单击这里

   3.3 业务请求参数

名称字段类型长度必须描述
获取条数limittinyint4是

每次请求需返回发货记录条数控制，取值范围大于等于，1小于等于100，limit输入值大于100时接口默认limit=100.

注：数据获取同步给商城系统后，一定要通过logistics_sync_ack.php回写结果，否则会出现ERP发货状态不能同步到商城的情况。

店铺编号shop_novarchar20否代表店铺所有属性的唯一编码，用于店铺区分，ERP内支持自定义（ERP店铺界面设置），用于获取指定店铺待同步数据信息
是否支持拆单发货is_part_sync_abletinyint1否是否支持拆单发货 0 否 1 是（支持开启多物流单号回传的卖家，没有对应需求的卖家请不要传该字段）

4.响应参数

   4.1 公共响应参数

名称字段类型长度必须描述
错误码codeint40是状态码:0表示成功,其他表示失败
错误原因messagevarchar255是错误原因
数据条数total_countint11是待物流同步数据总条数
待同步物流订单信息列表tradesdata[]
否响应参数的1级数据节点，包含当前页的订单待同步物流订单信息的数据节点,节点下数据字段详见下述“trades”

   4.2 业务响应参数

   trades

名称字段类型长度必须描述
主键rec_idint11是主键,用于logistics_sync_ack回写状态
店铺编号shop_novarchar20是代表店铺所有属性的唯一编码，用于店铺区分，ERP内支持自定义（ERP店铺界面设置）
原始订单tidvarchar40是原始订单编号，商城或平台订单号
物流单号logistics_novarchar100是物流或者快递面单对应的编号
物流方式logistics_typesmallint6是响应值为代表物流方式的数字，数字对应的物流方式名称单击这里
发货条件delivery_termtinyint4是1款到发货 2货到付款(包含部分货到付款) 3分期付款
发货时间consign_timedatetime
是发货时间    时间格式：yyyy-MM-dd HH:mm:ss
是否拆分发货is_part_syncvarchar1是是否拆分发货,1:拆单发货,0:不进行拆单发货
原始子订单oidsvarchar208是子订单编号串，以逗号(,) 分隔,(is_part_sync非0时才有效) 字段超过上限后会分多条trades返回
平台IDplatform_idsmallint6是平台ID，固定值127
订单IDtrade_idint11是订单ID
erp物流编号logistics_code_erpvarchar20是代表物流所有属性的唯一编码，用于物流区分，ERP内支持自定义（ERP物流界面设置）
erp物流公司名称logistics_name_erpvarchar40是ERP内自定义的物流名称，（对应ERP设置-基本设置-物流界面的物流名称）
物流方式名称logistics_namevarchar40是物流方式类型名称，（ERP设置-基本设置-物流界面的物流类型中文名称）
出库单idstockout_idint11是出库单id
是否同步is_need_syncint1是1:需要同步,0:不需要同步
同步状态 sync_statusint1是0:等待同步2:同步失败,3:同步成功4:手动设置为同步成功,5:手动取消同步
是否需要多次同步is_lastint
否 一个订单要多次同步时，最后一个为1,用于同步回写状态
店铺idshop_idsmallint6是默认为0
物流idlogistics_idint11是默认为0
描述descriptionvarchar200是
同步说明

同步时间

sync_timedatetime
是默认为'0000-00-00 00:00:00'，成功同步时间
在线is_onlinetinyint1是默认为0，是否使用淘宝在线发货
错误码error_codevarchar200是默认为 ''，平台返回的错误码
错误描述error_msgvarchar200是默认为 ''，平台返回的错误描述
重试次数try_timestinyint4是默认为0，重试计数(有些同步失败可重试)
最后修改时间modifieddatetime
是最后修改时间， 时间格式：yyyy-MM-dd HH:mm:ss
创建时间createddatetime
是创建时间，时间格式：yyyy-MM-dd HH:mm:ss
序列号sn_listdata[]

否

序列号（存在序列号时返回序列号，无序列号时返回 flag）

    sn_list

名称字段

类型

长度必须描述
子订单编号oidvarchar40是子订单编号
序列号snvarchar
40
是

序列号

5.请求示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?php
    require_once("../WdtClient.php");
    $c = new WdtClient;
    $c->sid = '';
    $c->appkey = '';
    $c->appsecret = '';
    $c->gatewayUrl = 'http://sandbox.wangdian.cn/openapi2/logistics_sync_query.php';
 
    $c->putApiParam('shop_no','api_test');
    $c->putApiParam('is_part_sync_able',0);
    $c->putApiParam('limit',100);
    $json = $c->wdtOpenApi();
    var_dump($json);
     
?>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
package com.wangdian.api.trade;
 
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
 
import com.wangdian.api.WdtClient;
 
public class LogisticsSyncQuery {
 
    public static void main(String[] args) {
        // TODO Auto-generated method stub
        WdtClient client = new WdtClient("传入sid", "传入appkey", "传入appsecret", "传入url");
        //测试环境sid、appkey、密钥请到旺店通开放平台-自助对接-申请测试环境内查看，测试环境url=https://sandbox.wangdian.cn/openapi2/
        //调用正式环境时请将sid、appkey、appsecret切换为实际参数，参数在旺店通开放平台-自助对接-应用管理内应用状态为已上线的应用中查看，调用正式环境注意切换正式环境url=https://api.wangdian.cn/openapi2/
         
        Map<String, String> params = new HashMap<String, String>();
        params.put("shop_no", "mytest");
        params.put("is_part_sync_able", "0");
        params.put("limit", "100");
        try {
            String response = client.execute("logistics_sync_query.php", params);
            System.out.println(response);
        } catch (IOException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }
    }
 
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using WdtSdk;
 
namespace LogisticsSyncQuery
{
    class LogisticsSyncQuery
    {
        static void Main(string[] args)
        {
            WdtClient client = new WdtClient();
            client.sid = "";
            client.appkey = "";
            client.appsecret = "";
            client.gatewayUrl = "http://sandbox.wangdian.cn/openapi2/logistics_sync_query.php";
 
            client.putParams("shop_no", "1223");
            client.putParams("limit", "100");
 
            string result = client.wdtOpenapi();
            Console.WriteLine(result);
            Console.ReadKey();
        }
    }
}
1
2
3
4
5
6
7
8
9
10
import WdtClient
 
t = WdtClient.WdtClient('appkey', 'appsecret', 'sid', 'http://sandbox.wangdian.cn/openapi2/')
params = {}
params.update({"limit": '100'})
params.update({"shop_no": 'test'})
params.update({"is_part_sync_able": '0'})
 
response = t.execute("logistics_sync_query.php", params)
print(response)

6.响应示例

   6.1 正常响应示例 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
    "code": 0,
    "message": "",
    "trades":
        [
                {
                    "rec_id": "1",
                    "shop_no": "xyp2test",
                    "tid": "115580935277840368-1",
                    "logistics_type": "12",
                    "logistics_no": "2313241321",
                    "delivery_term": "1",
                    "consign_time": "2019-05-19 00:45:00",
                    "oids": "",
                    "is_part_sync": "0",
                    "platform_id": "126",
                    "trade_id": "59658",
                    "logistics_name_erp": "圆通速递",
                    "logistics_code_erp": "2313241321",
                    "logistics_name": "圆通速递"
                },
                {
                    "rec_id": "2",
                    "shop_no": "115580935277840368-2",
                    "tid": "test0002",
                    "logistics_type": "12",
                    "logistics_no": "2313241322",
                    "delivery_term": "1",
                    "consign_time": "2015-01-01 10:00:00",
                    "oids": "",
                    "is_part_sync": "0",
                    "platform_id": "126",
                    "trade_id": "59658",
                    "logistics_name_erp": "圆通速递",
                    "logistics_code_erp": "2313241322",
                    "logistics_name": "圆通速递"
                }
        ]
}

   6.2 异常响应示例

1
2
3
4
{
    "code": 1007,
    "message": "接口appkey已停用【解决办法：联系商务人员，重新开启接口appkey】 "
}


附录：

测试环境如何测试物流同步：

  1. 调用trade_ push.php接口创建原始订单。

  2. 到订单>原始订单界面，使用原始单号查询到自己的订单，右键点击，选择递交。

  3. 递交成功后，到订单->订单审核界面，使用原始单号搜索待审核订单，右键--选择物流方式后，进行审核。

  4. 到库存>销售出库->单据打印界面，使用系统订单编号，找到对应的销售出库单，选择测试的物流，填写对应的物流单号,右键直接发货，如果库存不足需要添加库存，可以在库存管理界面右键操作盘点增加库存(更多库存添加方式：1、ERP客户端咨询,可以通过欢迎页面右下角的“在线售后支持”联系我们，2、官网售后咨询：打开官网 http://www.huice.com，在右侧点击售后咨询按钮。3、手机移动端咨询：关注【慧策丨旺店通】微信公众号进行咨询。4、点击并收藏如下链接直接咨询:  http://t.cn/AiuDjYyQ。5、如您有紧急问题，可以直接致电4000101039-2。)。另外注意:如果使用单号找不到销售出库单，请到订单->财审界面，检查一下是否订单进入了财审。

  5. 订单已经发货，物流信息在订单->物流同步界面，已经生成要同步的数据，可以使用接口查询了。




常用工具