快递100扩展属性简介及使用案例

    金蝶云星空供应链领域销售模块对接了快递100和快递管家功能，最主要的接口有快递100电子面单接口和快递管家接口，这两个接口中的大部分字段通版都已经实现了，但一些比较不常用的接口字段通版无法满足，对于这些字段可使用扩展属性功能。在8.0.100.202202版本发布时，获取电子面单界面添加了'扩展属性'字段，目前此'扩展属性'字段在当前版本中仅适用于快递100Api接口，快递管家接口不适用（快递管家中的扩展属性功能预计将在2022年8月中支持），此属性与快递100参数配置中的扩展属性（仅适用于快递100Api接口，快递管家接口不支持从参数配置中读取扩展属性）共同给客户提供部分二开功能，界面如下图1-1和图1-2所示：

图1-1

图1-2

这两个属性都必须是合法的JSON字符串，且获取电子面单接口中的扩展属性优先级高于快递100参数配置中的扩展属性，即如果两个地方都配置了相同的字段的不同值，比如获取电子面单配置了扩展属性值为： {"partnerId":"123456", "startGotTime":"1605256080000"}，参数配置中设置了扩展属性值为{"partnerId":"987654", "startGotTime":"1605256080000"}，最终将使用'获取电子面单'中的 123456 当作快递100企业API电子面单接口中的'电子面单客户账户或月结账号'。

    上面的JSON 字符串 {"partnerId":"123456", "startGotTime":"1605256080000"} 做下解释：由于通版在快递100参数中仅能根据不同组织区别相同物流公司的不同电子面单账号。比如在获取电子面单中选择一个销售出库单，通版逻辑是优先在默认寄件信息中查询与销售出库单发货组织相同的记录，并选择勾选了默认的那行记录（如果都没有勾选，则取相同记录的第一行），然后再用对应的快递公司和发货组织去电子面单通用设置中找同一快递公司和相同组织的电子面单账号（如果找不到，则仅按快递公司一个条件找），如下图2-1所示，如果在获取电子面单中选择的销售出库单发货组织是金蝶国际，则获取电子面单界面的快递公司默认是德邦快递，如果销售出库单发货组织是云科技深圳公司，则获取电子面单界面的快递公司默认是顺丰，但是这有一个问题，如果电子面单通用设置中的顺丰公司有不同的电子面单账号，且它们的组织都是一样的，则下图第3行的顺丰对应的电子面单账号是一直未使用的（快递公司顺丰有两行，且他们的组织是一样的，这种情况只会使用第一个顺丰电子面单账号）。扩展属性此时就可以派上用场，可以如上图1-1中动态配置电子面单账号partnerId参数为特定的值，比如我在获取电子面单界面中有100行记录，可以对前60条批量填充扩展属性为{"partnerId":"123456"}，后40条默认不写，这样就可以确保前60条使用123456当作电子面单账号，后40条使用通版默认逻辑的电子面单账号。当然通过此参数也可以配置一些比较少用或通版没有对接的属性，比如上图中的startGotTime参数，它主要是用于跨越物流公司网点没有收到预约揽件信息的变通处理，多传了一个预约取件的参数。

图2-1

注意事项：

    此扩展属性字段不是所有的电子面单接口参数都能覆盖，它目前仅能够覆盖如下图2-2所示的param首层结构上的参数：

图2-2

在上图中，电子面单HTML接口中param中的partnerId是可以覆盖的，但是recMan.name是覆盖不了的，因为它是多层数据包(根据通版规划安排，预计在2022.08发布时支持多层数据包JSON对象，届时更新补丁后可在扩展属性中输入类似如下的文本   {"sendMan.company":"金蝶软件国际集团"}  以达到扩展寄件方公司多层数据包目的 ，如果是电子面单图片接口，则直接输入{"sendManCompany":"金蝶软件国际集团"} )。如果是快递管家订单导入功能，则相关的扩展属性需要使用快递管家中的参数名，快递管家订单导入接口参数名如下图3-1所示：

图3-1

    从上图可以看到，如果想扩展快递管家寄件人公司名称，则需要在扩展属性字段中输入{"sendCompany":"金蝶软件国际集团"}，可以看到不同接口是要根据快递100或快递管家接口文档中参数名确定的，但要注意的是对于快递管家由于其特殊性，只支持data参数内的字段扩展，不支持诸如appid，access_token及sign之类的字段扩展。

最后说下快递100 V2模板的电子面单接口中的customParam参数如何通过获取电子面单界面中的'扩展属性'字段传递的。快递100官方接口文档中此字段的说明截图如下图4-1所示：

图4-1

从上图描述可以看到，这个字段的类型是： Map<String, String>，相当于C#的字典类型。通常很容易地以为在获取电子面单是通过在扩展属性字段中输入诸如 {"customParam": {"key1": "value1", "key2": "value2" }} 的文本格式来传递相关值，但这种写法是错误的，获取电子面单中的扩展属性是通过英文点号隔离不同字段名，前面的文本要通过格式 {"customParam.key1":"value1", "customParam.key2":"value2"} 来实现。