快递100及快递管家二开对接非供应链领域销售模块下的单据

    目前金蝶云星空供应链领域销售模块下对接了快递100及快递管家，涉及的单据有销售订单，发货通知单，销售出库单，销售退货单(销售退货单与快递100和快递管家的对接是在2021.6版本之后添加的)。近期收到部分客户想实现此功能对接第三方单据(包括客户自行添加的单据和非销售模块下的单据)，目前由于销售模块下是通过动态表单‘获取电子面单’实现对接的，且默认只处理本模块下的单据，对于非销售模块下的单据，可通过参阅本文二开实现。注：此二开流程需要客户升级到PT-146894 [7.7.0.202111]补丁，由于本帖子有C#二开代码的对接实现且本二开功能比较全面，因此需要客户有开发人员，或者需要客户找金蝶机构或分公司实现。如果仅想实现简单功能且无专门开发人员，可参阅 https://vip.kingdee.com/article/328262470009906944?productLineId=1。下面以财务领域的收款单为例说明如何二开对接快递100及快递管家：

    1，打开BOS IDE，扩展‘获取电子面单’动态表单，在单据名称字段下的过滤属性中添加收款单的单据标识ID(值为AR_RECEIVEBILL，它对应BOSIDE中的收款单单据的唯一标识)，如下图1-1所示：

图1-1

    在表单插件中，禁用通版插件 GetKuaidiBillEdit 插件，添加自定义GetKuaidiBillEditExtend插件，此自定义插件类名可以是任意合法名称，但是要继承至GetKuaidiBillEdit 通版插件，后面会详细说明其中的代码逻辑，如下图1-2所示。

图1-2

    2，通版在‘获取电子面单’中选择销售模块下的单据（如销售订单，发货通知单，销售出库单，销售退货单）时，已经有选择单据后自动填充界面相关字段的逻辑。默认情况下，其大致逻辑是通过选择的单据，获取其中的客户名称当作'获取电子面单'中的客户列值，销售模块下的单据客户页签下的收货方联系人，收货方地址，收货方联系人基础资料中的的固定电话和移动电话（注意不是客户页签下的收货人姓名和联系电话）当作‘获取电子面单’中的收件人相关信息。针对收款单，它没有客户页签，也就没有相关收件人，收件电话，收件地址等信息，这些信息都是依赖单据的，这需要客户自行扩展通版插件在特定的重写方法中获取收件相关的字段值逻辑，其他一些如快递公司，寄件人等信息通版都已经处理好，这些信息默认是通过快递100参数配置获取的。在满足客户自身需求时可以不用考虑其填充逻辑。如下图2-1所示为通版自带的发货通知单选择后自动填充相关界面值的示意图：

图2-1

    对于二开的单据或非销售模块下的单据，一些依赖单据上的字段值通版默认是无法填充到界面上的，此时需要客户自定义逻辑。下面以收款单的销售员当收件人，往来单位当客户为例(如果这种逻辑不是客户要的，可自行参照并修改)，简单说明下自定义插件GetKuaidiBillEditExtend 的逻辑，首先创建类库，并创建自定义类 GetKuaidiBillEditExtend ，此类继承于通版 GetKuaidiBillEdit 插件类（此类在应用程序集 Kingdee.K3.SCM.Sal.Business.PlugIn.dll 中），重写其中的 CustomPopulateRowData 方法(这个方法主要是定义客户选择单据后填充到’获取电子面单‘中相关字段的逻辑，此方法会在通版的一些字段填充逻辑处理完毕后调用，必要时客户可自行在这个方法中覆盖通版逻辑)，其中的代码有比较详细的注释，此代码适用于快递100接口和快递管家接口，如下图2-2所示：

图2-2

    如果在上图中遇到调试第三方单据或非销售模块的单据时没有进入断点，而销售订单，发货通知单，销售出库单等默认的单据又能进入断点则可能是二开单据在填充时就报错了，即在调用CustomPopulateRowData 前就报错了，此时可以通过服务器日志文件大概窥探出原因，有一种可能如下图2-2.1所示（本图来源于真实二开客户，客户在简单生产领料单二开支持获取电子面单功能，可以看到报错是因为物料没有销售相关的引用属性，添加下就能进入断点）：

图2-2.1

    通版针对快递100电子面单接口，主要是通过‘获取电子面单’界面中的‘申请电子面单’按钮实现的，此方法会对接三种电子面单接口，包括电子面单HTML接口，电子面单图片接口，电子面单打印机接口(调用哪个接口是依据快递100参数配置来决定的)。对于收款单，通版已经兼容处理了其中的大部分逻辑，但是获取完毕后，如果要把快递100返回的信息保存到星空系统中，这种情况是客户要自行处理的，通版对于销售模块下的单据一般是把快递100返回的物流单号保存到相关单据物流跟踪页签上，且通版处理的比较复杂，不仅要加物流单号相关表，还添加了从销售出库单回填物流单号到上游发货通知单和销售订单的逻辑，对于收款单客户也可以参照销售单据处理。但下面为了简化流程，以申请电子面单后把物流公司和物流编码回写追加到收款单的备注字段为例简单说明下，首先在自定义 GetKuaidiBillEditExtend 类中重写基类 GetKuaidiBillEdit 中的CustomHandleExpressNo 方法 (此方法主要是快递100电子面单接口调用成功后的一些处理，其中的属性SuccessDataEntity已经保存了大部分快递100电子面单接口的返回信息)，试例代码有比较详细的注释，注意此代码只适用快递100接口，快递管家不调用此方法，同时也注意下其中的UPDATE语句的语法，拼接字符串时用 || 操作符而不是+ ，这是因为底层按照金蝶SQL语法写的，它会依据底层数据库类型自动转成SQL Server或Oracle语法，如下图2-3所示。

图2-3

    针对快递管家接口，由于它和快递100有点不同，快递100是申请电子面单完毕后就立马返回了物流单号，附带还有电子面单链接或电子面单图片等信息，快递管家的物流单号是先在‘获取电子面单’界面中通过‘管家订单导入’后，然后在快递管家官网打印后通过回调地址回写到星空系统中的，这里的二开就比快递100复杂点，但是9月之后的通版也兼容考虑了这种情况。快递管家接口的回调是依赖通版的 Kuaidi100HttpHandler 类(在应用程序集Kingdee.K3.SCM.Business.PlugIn.dll中，它是一个.NET Framework下的一般处理程序)，下面以收款单为例，简单说明下如何扩展通版的回调处理类 Kuaidi100HttpHandler ，首先创建自定义类CustomKuaidi100HttpHandler ，此类可以是任意合法类名，但必须继承至通版 Kuaidi100HttpHandler 类，注意此类仅适用于快递管家相关，快递100相关接口不调用此类，然后重写其中的CustomExpressNoCallback 方法，试例代码仅简单地记录了日志，客户实际情况一般是要反写回对应的收款单相关物流表中(收款单默认没有物流单号记录表，真实处理时客户要自行添加物流单号记录表)，如下图2-4所示：

图2-4

    下图2-5为相关日志输出示意图，其中记录了以空格分隔的快递公司编码，快递单号和orderNum值：

图2-5

    其中的JSON数据包中的orderNum属性值简单说明下：orderNum是订单导入时传给快递管家的值，回调时，管家再原封不动地传回给星空，它的格式为：单据编码 + II + 单据标识 + II + 单据内码 + II + 唯一值，其中的II为分隔符，下面举个例子：比如orderNum值为 SKD00000001IIAR_RECEIVEBILLII100001II100448 时，SKD00000001为收款单单号，AR_RECEIVEBILL为收款单单据标识，100001为SKD00000001在数据库中的内码，即 T_AR_RECEIVEBILL 表中的FID列的值，100448是一个唯一值，此唯一值来自表 T_SAL_KUAIDIBILL (此表为星空‘电子面单’基础资料主表)中待使用的内码，利用这些信息可以精确地将相关物流详情信息回写到相关单据上，也可以利用orderNum值更新星空电子面单中的相关字段(比如通版就是通过orderNum和星空的电子面单中的orderNum匹配再把物流单号更新回星空电子面单中，同时也更新回相关销售模块下的单据物流跟踪页签中)。

    针对上面的仅继承通版的回调处理是不够的，因它还不像快递100接口那样直接在BOS中添加个自定义插件，禁用通版插件那样简单直接，回调地址的修改处理还必须配置common.config文件(此文件一般是在X:\Program Files (x86)\Kingdee\K3Cloud\WebSite\App_Data\ 目录下)，在这个文件中删除通版一般处理程序配置节点，添加自定义的一般处理程序配置节点，如下图2-6所示：图中红框中被注释的那行是通版的一般处理程序配置节点，未注释的那行是客户要自已添加的。

图2-6

    配置好后，要重启IIS，再通过快递管家官网更新配置下回调地址，如下图2-7所示：

图2-7

    写在最后：在通版 GetKuaidiBillEdit 类中，其实还有其它一些方法或属性可以重写，比如通版选择单据后的填充逻辑方法FillKuaidiInfo ，还有保存快递100参数配置信息的属性 Kuaidi100Parameter ，以及选择单据时自定义的过滤条件配置方法CustomSetSelectionFilters，当然还有BOS底层的方法，比如 AfterBindData，这些都可以供客户自行二开配置。下图3-1为一些方法重写试例，其中有比较详细的注释说明：

图3-1

    另外，基类Kuaidi100HttpHandler 中的 CustomLogisticsDetailInfo方法也是可以重写的，它主要用来实现快递管家物流详情主动推送的自定义方法，其中有一个参数orderNum和前面说的类似，通过这个参数可以确定是哪种类型的单据，也能确定是哪个单据编码。另外的参数是一个JSON数据包，包含了特定物流单号的详情物流信息。下图3-2红框中的第一行和第二分别是快递管家生成的电子面单和快递100生成的电子面单，这两个星空的电子面单分别对应不同的收款单(通过关联单据编号)，由于二开快递管家回调的一般处理程序在处理物流单号回填时只是记录了日志，所以即使快递管家官网打印后，第一行还是没有快递单号，真实二开情况下应该要在回调代码中通过快递公司订单号更新星空电子面单的快递单号。客户可以对比下第一行和第二的字段值的差别。

图3-2

    如果想对二开的单据使用 销售物流信息列表 统一管理物流单号下的物流轨迹信息，可参阅论坛地址：https://vip.kingdee.com/article/223033855618894592 靠后的内容。