当前位置: API文档

logistics_sync_query.php(查询物流同步)

¥标准

1.接口说明

1.1 接口描述:ERP销售订单的发货状态、物流单号等同步给其他系统,注:”查询物流同步”与“物流同步回写”两个接口配合使用,完成“销售订单发货同步”
1.2 适用版本:客户端 V2.4.0.5及以上版本
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地址
测试环境http://sandbox.wangdian.cn/openapi2/logistics_sync_query.php
正式环境http://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错误原因
待同步物流订单信息列表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_timedate
发货时间
是否拆分发货is_part_synctinyint1是否拆分发货,1:拆单发货,0:不进行拆单发货
原始子订单oidsvarchar
子订单编号串,以逗号(,) 分隔,并且长度不固定(is_part_sync非0时才有效)
平台IDplatform_idtinyint1平台ID
订单IDtrade_idint11订单ID
erp物流编号logistics_code_erpvarchar20代表物流所有属性的唯一编码,用于物流区分,ERP内支持自定义(ERP物流界面设置)
erp物流公司名称logistics_name_erpvarchar40erp对应的物流公司名称
物流公司名称logistics_namevarchar40物流公司名称

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("", "", "", "");
        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();
        }
    }
}

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】 "
}



常用工具