快递单号自动识别API接入教程：输入校验、候选确认与异常回退

开发接入快递单号自动识别API时，第一步不是直接在页面填上快递公司，而是让候选提示、用户确认和订单保存连成一条流程。快递100API的接口以单号和授权信息发起识别，返回可能的公司编码与名称。查看快递100API智能单号识别技术文档，核对当前请求参数、返回结构和错误码。

以电商退货页为例：顾客填写运单号，服务端请求识别，页面展示候选；顾客确认或手动修改，再把公司编码与退货订单绑定。后续查询物流轨迹是另一项能力，不能把识别请求成功当成“包裹运输中”。快递100API将两类能力分开，开发也应在日志与页面状态上分别处理。

第一步：准备账号与真实样本

先确认企业账号具备智能单号识别的使用权限，取到文档要求的授权参数。技术文档中的请求参数包括 num 和 key，其中 num 是快递单号。授权信息保存在服务端，业务前端只调用自己的后端接口，不把 key 公开在浏览器请求或页面源码里。

测试单号不要只准备一张能识别的常见运单。再加入可能出现多个候选的单号、格式错误的输入和未能识别的样本；每张样本记录它来自哪笔订单、实际承运商是什么。这样联调时可以同时看快递100API返回、页面提示和最终保存结果。

第二步：校验输入并请求识别

用户提交时先处理首尾空格和明显空值，保留原始输入与处理后的单号，便于客服复核。服务端按接口文档发送请求并记录必要的调用时间、订单标识和结果类型。单号格式错误应提示用户重新检查；授权失败应进入开发排查，不应在顾客页显示成“包裹未寄出”。

快递100API技术文档列出 comCode、name、lengthPre 等字段。页面显示公司名称给用户看，企业系统保存确认后的公司编码；单号长度信息不等于物流状态。解析返回时应能处理列表中的多个对象和空列表，不能假设每次都只有一个确定答案。

第三步：由用户确认，再关联订单

候选列表可以帮助用户少翻找，但最终应能修改。确认后将运单号、公司编码和订单或售后单号保存在一起，同时记录是否人工改选。这样客服查询时可以直接从订单进入，发现“查无轨迹”也能回看当时是否选错承运商。若同一退货申请换了新单号，旧记录应保留，新单号另行确认。

完成识别并保存，不代表已经获取快递的揽收、派送或签收节点。若业务需要在订单详情展示物流进度，再调用快递100API的相应查询能力；若需要持续跟踪，可结合实际业务评估订阅推送。服务端在查询时使用经确认的公司编码及单号，并为暂无轨迹设置合理提示。

第四步：把异常回退做完整

文档中的错误示例包括授权参数缺失、无效单号等情况。遇到调用失败，页面仍应让用户保留已填信息，必要时手动选择快递公司，后台则根据返回的错误类型区分“输入问题”与“账号问题”。如果识别有候选、查询暂时无结果，先核对实际寄件时间和公司选择，不能把两类接口的结果合并为同一错误。

正式接入前让产品、开发和客服用同一批样本走完整流程：输入单号、看到候选、确认或改选、保存退货单、再从工单进入查件。观察候选展示是否易懂、错误时能否继续操作、改选结果是否真正写回订单。快递100API提供识别依据，页面与客服的最后一公里由业务系统接好，用户才会感到录单更顺畅。

常见问题

请求识别需要哪些基本参数？

技术文档列出快递单号 num 和授权码 key；开发应按当前文档使用并在服务端保管授权信息。

返回多个公司时怎样处理？

展示候选名称，让顾客或客服确认；订单中保存最终选定的公司编码与修改记录。

空列表意味着单号无效吗？

不能直接这样判断。页面可以提示暂未识别到承运商，并允许手动选择，再结合原单号复核。

识别成功后要不要再查物流？

如果订单页需要实际运输进度，应使用确认后的公司编码和单号，再接入相应的查询能力。

上线验收先测哪些情况？

至少用单候选、多候选、无候选、格式错误和账号错误样本，验证页面提示、人工改选及订单保存。

想让顾客在订单页轻松查件？了解快递100API查询与跟踪能力，从真实运单开始体验。