快递100企业版接口申请和使用
分类:物流企业录 热度:

最近公司的订单业务模块需要一个根据快递单号查询快递信息的功能,经筛选比较之后,选择了 快递100 作为第三方接口服务接入,主要原因是看到了他家提供 推送/订阅 模式,可以很大程度上减少不必要的查询请求,同时也可以解决缓存造成的数据延迟问题。

快递接口申请

首先,需要申请一个企业版的快递接口,申请地址:快递100企业版接口申请

填写相应资料,提交申请后,快递100 会在 5分钟 内给你填写的邮箱发送一封邮件,邮件里包含了你的账号和密码,以及一个开通网址。

登录之后在线签订合同,填写发票相关信息,选择 支付宝 或者 微信 预付费,当然也可以采用月结的方式付费。这里我们选择了在线预付费的形式。

充值完毕之后,快递100 会向你的邮箱发送两封邮件,一封是 【快递100通知:充值成功】 充值成功的邮件,如果采用在线预付费的形式付款,这封邮件里包含了电子发票的下载链接。另一封邮件是 快递100-企业版快递查询接口(API)——授权key及相关工具 里面包含了:

管理后台账号密码

订阅推送接口 key

实时查询接口 key 和 customer

智能判断接口 key

电子面单接口 key 和 secret

短信接口 key 和 用户ID

以及附件中的 技术文档及工具下载地址

以上信息需要妥善保密保存,在使用 快递100 提供的相关服务时将会用到。

快递信息查询功能需求

根据快递单号查询快递公司

订阅跟踪快递单号

快递信息推送处理

根据快递单号查询快递公司

API请求URL: ?num=[单号]&key=[key]

请求方式:GET

参数说明:

单号 卖家录入的快递单号

key 上面邮件里给的 智能判断接口 key

返回结果字段:

comCode 公司编码,快递公司对应的编码,前面邮件里会有给到 快递100 最新的公司编码 Excel 文件,对照文件里的编码可知是哪家快递公司

id 快递100内部字段,忽略

noCount 快递100内部字段,忽略

noPre 快递100内部字段,忽略

startTime 快递100内部字段,忽略

我们实际业务中,只需要知道单号对应的快递公司即可,所以只需知晓 comCode 这个值。在设计快递相关的数据库时,需要有针对 快递100 提供的编码规则对照字段,存储对应的 comCode,方便我们根据 comCode 来查询数据库中快递公司对应的 id。

返回结果示例:

[{ "comCode":"shunfeng", "id":"", "noCount":302236, "noPre":"9069", "startTime":"" }, { "comCode":"yuantong", "id":"", "noCount":24, "noPre":"9069", "startTime":"" }]

接口返回的是一组可能的结果,所以如果猜测有多个快递公司时,我们还需将结果展示给卖家,让其选择实际的快递公司。当然如果没有猜到快递公司,需要做一个降级处理,将所有可用的快递公司展示给卖家选择。

订阅跟踪快递单号

API请求URL:

请求方式: POST

参数说明:

schema 参数格式,可以是 json 或者 xml,schema 决定了参数列表的格式和推送回调的内容格式

param 参数列表

company 小写格式的订阅的快递公司的编码,使用 快递100 提供的最新快递公司编码 Excel 文件中提供的快递公司编码

number 快递单号

from 出发城市,格式为 省-市-区,非必填项,填了有助于提升签收状态的判断的准确率

to 目的地城市,非必填项,格式同出发城市,填了有助于提升签收状态的判断的准确率,且到达目的地后会加大监控频率

key 上面邮件里给的 订阅推送接口 key

parameters 其他参数

callbackurl 推送回调接口地址,当快递信息更新时会调用此接口

salt 签名用随机字符串

resultv2 是否开通行政区域解析功能

autoCom 值为 1 表示开始智能判断单号所属公司的功能,开启后,company字段可为空,即只传运单号(number字段)。建议只有在无法知道单号对应的快递公司(即company的值)的情况下才开启此功能

interCom 值为 1 表示开启国际版,如果 number 是国际单号,则会返回出发国与目的国两个国家的跟踪信息,此功能暂时只支持邮政体系(国际类的邮政小包、EMS)内的快递公司

departureCountry 出发国家编码,非必填,中国为 CN,使用 快递100 提供的最新快递公司编码 Excel 文件中提供的国家编码

departureCom 出发的快递公司的编码,非必填,使用 快递100 提供的最新快递公司编码 Excel 文件中提供的快递公司编码

destinationCountry 目的地国家编码,非必填,使用 快递100 提供的最新快递公司编码 Excel 文件中提供的国家编码

destinationCom 目的地快递公司编码,非必填,使用 快递100 提供的最新快递公司编码 Excel 文件中提供的快递公司编码

返回结果字段:

result true 表示成功,false 表示失败

returnCode 请求结果状态码

200 请求成功

701 拒绝订阅的快递公司

700 订阅方的订阅数据存在错误(如不支持的快递公司、单号为空、单号超长等)或错误的回调地址

702 识别不到该单号对应的快递公司

600 授权 Key 出错

601 授权 Key 过期

500 服务器错误(即快递100的服务器出理间隙或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误)

501 重复订阅

message 请求结果说明

返回结果示例:

{ "result":false, "returnCode":"500", "message":"POLL:参数错误" } 快递信息推送处理

推送参数列表:

sign 签名

param 参数列表

status 监控状态: polling 监控中,shutdown 结束,abort 中止,updateall 重新推送

message 监控状态相关消息,如:3天查询无记录,60天无变化

autoCheck 快递公司编码是否出错

comOld 原始的快递公司编码

comNew 纠正后的快递公司编码

lastResult 最新查询结果,若在订阅报文中通过interCom字段开通了国际版,则此lastResult表示出发国的查询结果,全量,倒序(即时间最新的在最前)

state 快递单当前签收状态,有 在途中,1 已揽收,2 疑难、3 已签收、4 退签、5 同城派送中、6 退回等状态

condition 快递单明细状态标记,当 state 为 时,CU001 等待清关,CU002 清关中,CU003 已清关,CU004 清关异常

ischeck 是否签收标记

com 快递公司编码,小写

nu 运单号

data 快递详细信息列表

签名校验:

判断 MD5(param + salt) 的值是否等于 sign,salt 即为订阅请求参数中的 签名用随机字符串

快递公司编码纠正:

如果 param 中的 status 为 abort 且 comNew 不为空,说明订阅时传的快递公司编码有误,需要纠正。

实时快递信息查询

由于 快递100 限制了此接口的并发频率为 1单/秒,故而没有太大意义,使用其推荐的 订阅/推送 模式足矣。

上一篇:如何成为一个合格的物流快递企业管理者? 下一篇:快递企业国内外研究现状
猜你喜欢
各种观点
热门排行
精彩图文