供应链领域销售模块与快递100和快递管家对接简介

    供应链销售模块目前既对接了快递100也对接了快递管家，本文以最新版本(2020年11月发布)为例，以略带开发者角度简单介绍一下现有相关接口及未来将要添加的接口和一些过去常出现的问题，以方便客户二开对接此功能。相关快递100参数配置及功能说明可参阅我同事ken的视频链接 https://vip.kingdee.com/school/2742， https://vip.kingdee.com/school/3313 及其帖子：https://vip.kingdee.com/article/164785582197813504 

一，参数说明：

    对接快递100和快递管家之前，必须先配置好相关参数，如下图1-1和1-2所示

图1-1

图1-2

二，快递100相关接口对接：

    无论是快递100还是快递管家接口，都是在快递100参数配置好后，由‘获取电子面单’动态表单发起。如下图2-1所示

    图2-1

    在‘获取电子面单’界面选择好相关单据时，点击图中的‘申请电子面单’按钮，会根据图中的发货组织选择对应的电子面单账号，’申请电子面单‘操作将对接快递100电子面单中的‘电子面单HTML’接口(未在快递100参数配置中配置模板时，调用接口http://poll.kuaidi100.com/eorderapi.do?method=getElecOrder)或‘电子面单图片接口’(配置有模板参数时，调用接口https://poll.kuaidi100.com/printapi/printtask.do?method=getPrintImg)，如下图2-2所示及说明

图2-2

    申请电子面单后，一般会立即生成星空'电子面单'基础资料，此基础资料会关联星空相关单据和电子面单接口返回的物流单号，这些物流单号会反写回对应的单据中的物流跟踪页签上，下图2-3所示为没有子母单的情况截图：

图2-3

    下图2-3.1所示为对应单据上的物流单号回写示意图

图2-3.1

    下图2-4所示为有子母单的情况：

图2-4

    无论是'获取电子面单'界面中的'申请电子面单'返回的快递单号还是'快递管家订单导入'(此功能需要导入后在快递管家官网打印或星空电子面单列表中自动打印后才会回填快递单号)后返回的快递单号，都可以统一通过‘销售物流信息’基础资料手动刷新物流信息（调用快递100接口http://poll.kuaidi100.com/poll/query.do），如下图2-5所示

图2-5

    快递100接口有一个‘智能单号识别接口’，请求地址为http://www.kuaidi100.com/autonumber/auto?num=&key=，此接口应用在星空销售出库单物流跟踪页签中，在物流跟踪页签中输入物流单号而没有选择物流公司时，会在光标离开物流单号输入框后自动调用此接口，获取物流公司代码，填充到物流公司中。

    申请电子面单操作对应的接口核心代码段在程序集 ‘Kingdee.K3.SCM.Sal.Business.PlugIn.dll’ 中的类 'Kingdee.K3.SCM.Sal.Business.PlugIn.GetKuaidiBillEdit,Kingdee.K3.SCM.Sal.Business.PlugIn' 中的方法 ‘RequestKuaidiBill()’ ，RequestKuaidiBill()方法会调用程序集 ‘Kingdee.K3.SCM.App.Core.dll’ 中的类 'Kingdee.K3.SCM.App.Core.KuaidiBillService,Kingdee.K3.SCM.App.Core' 中的方法 ‘RequestKuaidiBill()’。有二开需求的客户，如想添加通版没有的接口参数(比如电子面单接口中的 ‘collection 代收货款额度’ 参数)可使用类似dnSpy工具反编译这些程序集，修改其中的逻辑来实现；处理逻辑大致如下：二开‘获取电子面单’动态表单，添加列‘代收货款额度’，在GetKuaidiBillEdit类中的方法RequestKuaidiBill添加读取'代收货款额度'的逻辑并转递到KuaidiBillService类中。

如果想修改通版在选择单据后对 ‘获取电子面单’ 动态表单中的各列赋值逻辑，可修改类 'GetKuaidiBillEdit' 中的方法 'FillKuaidiInfo' 中的逻辑。

三，快递管家相关接口对接：

    与‘获取电子面单’中的‘申请电子面单’功能类似，选择好单据后，点击‘快递管家订单导入’，会异步(界面上会立即显示导入成功的提示，但不一定代表着真正导入成功，真正导入成功的消息是快递管家通过回调地址传给金蝶星空系统的，星空系统通过日志会记录导入成功与否)地将数据导入到快递100管家，此接口调用地址'http://b.kuaidi100.com/v5/open/api/send'(没有启用多用户打单时调用此接口地址)或'https://b.kuaidi100.com/v6/open/api/send'(启用了多用户打单时调用此接口，管家V6版本接口支持更复杂功能)，可通过快递管家官网查看导入后的单据。

    管家订单导入后，快递管家会通过在管家官网APIKey中配置的回调地址(快递管家官网配置，配置格式如：http://k3cloudlightapp.kingdee.com/k3cloud/ScmKuaidiService/Kuaidi100HttpHandler)  将是否成功导入的信息传送给金蝶星空系统，当用户在快递管家官网打印单据或点击星空系统中电子面单列表的跳转打印(跳转打印通过调用接口 https://b.kuaidi100.com/v5/open/api/print   或 https://b.kuaidi100.com/v6/open/api/print ，使用哪个地址与导入时使用的版本对应)后，会根据回调地址将物流单号回填到星空对应的‘电子面单’基础资料和相关单据的物流跟踪页签中。

    如果客户购买了快递管家的物流推送服务(据说内部还是调用快递100的物流接口)，则快递管家在有物流更新时会自动通过回调地址将物流信息推送给金蝶云星空，此功能类似于‘销售物流更新’执行计划，会刷新相关物流单据的物流详情。从开发者角度来讲，快递管家无论是导入成功的确认信息，物流单号的回填还是物流轨迹的推送，都是通过星空系统的类 'Kingdee.K3.SCM.Business.PlugIn.Kuaidi100HttpHandler, Kingdee.K3.SCM.Business.PlugIn' (此类在程序集Kingdee.K3.SCM.Business.PlugIn.dll中)进行处理的。回填地址为何要加上ScmKuaiDiService是由于星空系统安装路径下的配置文件 ‘K3Cloud\WebSite\App_Data\Common.config’ 定义的 system.web节点下的httpHandlers节点有ScmKuaiDiService，所以类 ‘Kuaidi100HttpHandler’ 它就是一个aps.net的一般处理程序，有二开需求的客户可以反编译此组件并修改相关逻辑。

    供应链销售模块中其它快递管家相关的接口还有管家自动打印接口(调用 https://b.kuaidi100.com/v5/open/api/autoPrint 或 https://b.kuaidi100.com/v6/open/api/autoPrint 至于调用哪个与上面的逻辑类似)和云设备获取接口(调用 https://b.kuaidi100.com/v5/open/api/getCloudPrintMachineList 或 https://b.kuaidi100.com/v6/open/api/getCloudPrintMachineList)和V6版本access_token获取接口(调用https://b.kuaidi100.com/open/oauth/token)

    管家订单导入接口核心逻辑在程序集 ‘Kingdee.K3.SCM.Sal.Business.PlugIn.dll’ 中的类 'Kingdee.K3.SCM.Sal.Business.PlugIn.GetKuaidiBillEdit,Kingdee.K3.SCM.Sal.Business.PlugIn' 中的方法 ‘BatchImportOrder() ’，‘SendOrders()’，‘OrderImport()’，这三个方法关系是 BatchImportOrder 调用 SendOrders ， SendOrders 调用 OrderImport 。有二开需求的客户，如想添加通版没有的接口参数可反编译这些程序集，修改其中的逻辑来实现。

四，版本更新记录及未来规划

    1，目前有客户提单反馈申请电子面单后返回的电子面单地址或电子面单图片不太好处理后续操作，比如客户可能还要直接打印电子面单图片或电子面单地址必须在浏览器中打开后才能打印。目前BOS平台未能提供图片控件的直接打印功能，只能通过自定义套打模块变相实现，规划后续版本对接快递100的云打印接口（要购买快递100云打印机），请参阅快递100相关功能说明，地址为： https://api.kuaidi100.com/document/5f0ffbdebc8da837cbd8aefd.html和接口说明，地址为： https://api.kuaidi100.com/document/5f0ffbed2977d50a94e1023d.html；另外目前正在和快递100沟通新接口‘电子面单打印’的相关事宜，其接口说明参见：https://api.kuaidi100.com/document/5f0ff6adbc8da837cbd8aef8.html，电子面单打印接口预计在2021年3月份发布(2021.3.25已发布，调用打印接口需要在快递100参数配置中设置好模板id和设备码，如下图4-1所示)。

图4-1

    2，另外有客户提出快递100和快递管家想实现与第三方单据的对接，目前此需求已纳入规划中，预计2021.10月上线此功能，此功能需要代码二开实现，可参阅：https://vip.kingdee.com/article/216286725399032576（2021.09.16发布包含此功能），简单的二开单据配置可参阅：https://vip.kingdee.com/article/328262470009906944?productLineId=1 

    3，国际电子面单功能添加，目前有计划对接国际电子面单，国际电子面单功能预计在2021.11月上线（PT-146899 [7.7.0.202112]发布包含此功能），届时获取电子面单菜单将有两个，一个是获取电子面单，一个是获取电子面单(国际)，用户升级版本后可以使用后者进入国际电子面单操作界面，选择单据，录入相关面单信息，申请后就可以看到国际电子面单，由于此功能用的客户比较少，后续可能会根据客户提单需要随时修改，大致的操作界面如下图4-2，图4-3，图4-4所示：

图4-2

图4-3

图4-4

    4，快递100重复打印功能添加，在对接了电子面单云打印后（通过快递100打印机打印，不支持HTML电子面单接口），可以实现重复打印功能，此功能预计在2021.11月发布(PT-146899 [7.7.0.202112]发布包含此功能)，子单，签回单的重复打印功能在后两个版本中已发布。

    5，快递100快递信息推送服务接口对接，目前版本仅有快递管家才有物流推送服务，快递100对应的尚未对接。快递管家物流推送需要充值相关API，如下图4-5所示：

图4-5

    快递100的推送服务接口目前正在规划中，预计会通过过滤方案控制要推送的物流单号（此方案建议配置成一个月内查询条件作为过滤方案数据），并在快递100参数配置中提供回调地址配置（类似于快递管家的回调地址配置），预计在2022.05发布（2022.03.31版本已包含此功能，相关功能使用说明可参阅金蝶云星空社区论坛地址： https://vip.kingdee.com/article/288016181233754624?productLineId=1 ），其相关接口及功能可参阅快递100官网接口文档地址：https://api.kuaidi100.com/document/5f0ffa7f2977d50a94e1023b ，接口文档如下图：4-6所示：

图4-6

    6，有客户提单反馈要求添加电子面单取消功能，目前此功能正在开发中，预计在2022.9月补丁中发布（PT-146926 [8.0.0.20220922]已包含此功能）。

    7，电子面单多设备码支持在获取电子面单界面中选择(支持显示别名)，快递类型支持一行记录中按分号拆分，电子面单账号支持关联( PT-146930 [8.1.0.20221110]已包含此功能)，详情介绍可参阅：https://vip.kingdee.com/article/376423425566472192?productLineId=1 。

    8，快递100申请电子面单，快递100取消电子面单，快递管家订单导入，快递管家官网删除导入的单据后，要在销售模块单据上的物流跟踪面签中标识出物流单号的类型，比如有母单，签回单，子单，后缀单，删除单。子单，删除单（通过快递100取消电子面单功能或者在快递管家官网删除导入的单据后就会在星空系统中标识为删除单，如果是在星空电子面单列表中物理删除，则单据上的物流跟踪页签同步删除），后缀单（在获取电子面单界面没有勾选需要子单，但快递100电子面单接口有时依然会在回传给星空的数据包中含有 childNum = "XXXXXXX 00010001" 的数据，目前这种单据在星空命名为后缀单，如果获取电子面单界面勾选需要子单，快递100接口也是通过childNum回传子单数据给星空系统。后缀单一般是快运类的物流公司的包裹上需要显示唯一一单的打印条码数据，格式通常是母单+8位后缀，比如母单号为320017264988，后缀单为32001726498800010001）不参与物流详细信息的查询，此功能已纳入通版后续规划中，预计在2022.12发布(PT-146934 [8.1.0.20230112]已包含此功能)。

    9，有客户提单反馈要求支持快递100电子面单V2版本功能，此功能正在开发中，预计发布时间在2023年4月，详情可参阅：https://vip.kingdee.com/article/419584224942064640  。

五，常见提单问题及解决方案：

    1，快递管家有签回单功能的单据打印后快递单号回填失败，此问题是由于之前未考虑多单号回填导致的(数据库字段不够长)，请更新到2020.07之后的补丁；

    2，快递管家合并订单再打印快递单号回填失败，此问题预计在2021.03补丁中处理；

    3，在星空系统完全关闭公网权限后通过WEBAPI无法处理销售出库单新增，修改等操作，请更新到2021.01之后的补丁；

    4，管家签回单，电子面单子母单功能的支持，请更新到2020.07之后补丁；

    5，管家导入后地址解析错乱的问题，请完整输入省市区等地址；

    6，申请电子面单提示‘存在多个网点问题’，此问题是由于快递100电子面单接口文档前期未能对外公布tbNet参数导致的当前星空系统版本未能对接此接口参数，计划在2021年3月发版时对接此参数(2021.3.25已发布此功能)。