当前位置: 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_termtinyint41款到发货 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_erpvarchar40ERP内自定义的物流名称,(对应ERP设置-基本设置-物流界面的物流名称)
物流方式名称logistics_namevarchar40物流方式类型名称,(ERP设置-基本设置-物流界面的物流类型中文名称)
出库单idstockout_idint11出库单id
是否同步is_need_syncint11:需要同步,0:不需要同步
同步状态 sync_statusint10:等待同步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.请求示例

PHP
<?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);
    
?>
JAVA
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();
        }
    }

}
C#
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();
        }
    }
}
python
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 正常响应示例 

JSON
{
    "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 异常响应示例

JSON
{
    "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. 订单已经发货,物流信息在订单->物流同步界面,已经生成要同步的数据,可以使用接口查询了。




常用工具