{ "openapi": "3.0.3", "info": { "title": "全球快递物流查询-V2", "description": "【顺丰快递-快递查询-物流查询-快递物流单号查询--快递单号查询】支持国内外1500多家快递物流公司，覆盖顺丰、四通一达、宅急送、德邦、百世、天天、京东、EMS等快递，与官网同步数据更新。提供物流轨迹，可配合快递订阅推送使用！【快递新用户请使用：全国快递物流查询-V2，V2与V1的区别点击查看】。", "termsOfService": "https://www.showapi.com/helpcenter/view#/4019/2", "version": "1.0.0" }, "servers": [ { "url": "https://route.showapi.com" } ], "paths": { "/2650-12": { "x-pointCode": 12, "x-mode": "mapping", "x-read-timeout": 5, "x-connect-timeout": 5, "post": { "summary": "物流时效查询", "description": "查询货物从发货地到目的地的时效", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "ret_code": { "type": "number", "description": "0 表示查询成功" }, "pre_cost_hour": { "type": "number", "description": "预计用时，单位：小时" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "2650_12_POST", "parameters": [ { "name": "from_address", "in": "query", "description": "省市区地址", "required": true, "schema": { "type": "string" } }, { "name": "to_address", "in": "query", "description": "省市区地址", "required": true, "schema": { "type": "string" } }, { "name": "com", "in": "query", "description": "快递编码", "required": true, "schema": { "type": "string" } } ] } }, "/2650-8": { "x-pointCode": 8, "x-mode": "mapping", "x-read-timeout": 30, "x-connect-timeout": 30, "post": { "summary": "按单计费查询物流", "description": "同步查询快递物流信息，按单计费。\n30天内1个快递单多次查询只扣1次费。\n更多帮助请查看 https://www.showapi.com/book/view/3157/13", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "nu": { "type": "string", "description": "快递单号" }, "logo": { "type": "string", "description": "快递公司logo" }, "ret_code": { "type": "number", "description": "调用说明\n0 查询成功 或 提交成功\n1 输入参数错误\n2 查不到物流信息\n3 单号不符合规则\n4 快递公司编码不符合规则\n5 快递查询渠道异常\n6 auto时未查到单号对应的快递公司,请指定快递公司编码\n7 单号与手机号不匹配 其他参数：接口调用失败\n\n101 揽件\n102 在途中\n103 派送中\n104 已签收 (完结状态)\n105 用户拒签\n106 问题/疑难件\n107 无效单 (完结状态) \n108 超时单\n109 签收失败\n110 退回\n111 转投\n112 待签\n113 邮件回收" }, "com": { "type": "string", "description": "快递编码" }, "update_time": { "type": "string", "description": "更新时间" }, "tel": { "type": "string", "description": "快递公司联系方式" }, "showapi_inner_fee_num": { "type": "number", "description": "计费次数" }, "query_num": { "type": "number", "description": "查询次数" }, "data": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "description": "发生的时间" }, "context": { "type": "string", "description": "跟踪信息" }, "status": { "type": "number", "description": "状态信息\n101 揽件\n102 在途中\n103 派送中\n104 已签收 (完结状态)\n105 用户拒签\n106 疑难件\n107 无效单 (完结状态) \n108 超时单\n109 签收失败\n110 退回\n111 转投\n112 待签" }, "location": { "type": "string", "description": "位置对应的坐标信息，坐标系是：GCJ-02" }, "address": { "type": "string", "description": "位置信息" }, "sub_status": { "type": "number", "description": "（试营）子状态\nstatus=104 已签收 (完结状态)\t\t\n- 10401\t已签收\n- 10402\t从快递柜或者驿站取出\n- 10403\t退回签收" } } }, "description": "物流跟踪信息列表，即在途数据" }, "com_name": { "type": "string", "description": "快递公司名字" }, "possible_exp_list": { "type": "array", "items": { "type": "string" }, "description": "猜测列表。仅当com参数值为auto，且查询失败时才有返回值。返回结果参考如下：\"possible_exp_list\": [\n {\n \"com\": \"zhongtong\",\n \"com_name\": \"中通快递\"\n },...\n ]" }, "msg": { "type": "string", "description": "返回说明" }, "delivery_time": { "type": "string", "description": "预计到达时间（格式：yyyy-MM-dd HH:mm）。该信息是基于历史数据分析的结果，不代表实际情况，仅供参考。" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "2650_8_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "com": { "type": "string", "description": "快递公司字母简称，可以从\"快递公司列表\"或\"快递公司查询\" 接口中查到该信息\n如不知道快递公司名,可以使用\"auto\"代替，此时将自动识别快递单号【auto是基于以往单号的特征进行人工智能分析，会有一定的误差，请谨慎使用】 " }, "nu": { "type": "string", "description": "快递单号 " }, "phone": { "type": "string", "description": "收件人或寄件人电话号码后四位。目前，查【顺丰、跨越、中通】该参数必填。\n注：隐私号需要完整后四位，例：13xxxxx1-234,则需要传入的后四位为1234" }, "delivery_address": { "type": "string", "description": "最终收件地址，可用于反生成最终经纬度和预测收件时间，添加时最少包含省市区" }, "shipping_address": { "type": "string", "description": "寄件地址，用于预测收件时间，添加时最少包含省市区" } }, "required": [ "nu" ] } } } } } }, "/2650-6": { "x-pointCode": 6, "x-mode": "mapping", "x-read-timeout": 30, "x-connect-timeout": 30, "post": { "summary": "单号查快递公司", "description": "通过快递单号猜测出快递公司。适用于需要识别快递公司以提供用户准确物流信息的场景。", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "ret_code": { "type": "number", "description": "0：查询成功\n1：参数错误" }, "data": { "type": "array", "items": { "type": "object", "properties": { "imgUrl": { "type": "string", "description": "快递公司logo" }, "phone": { "type": "string", "description": "快递公司电话" }, "com": { "type": "string", "description": "快递公司编码" }, "com_name": { "type": "string", "description": "快递公司名称" }, "url": { "type": "string", "description": "快递公司官网" } } } }, "msg": { "type": "string", "description": "返回说明" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "2650_6_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "nu": { "type": "string", "description": "快递单号 " }, "addOther": { "type": "string", "description": "存在时返回logo、官网、电话" } }, "required": [ "nu" ] } } } } } }, "/2650-5": { "x-pointCode": 5, "x-mode": "mapping", "x-read-timeout": 30, "x-connect-timeout": 30, "post": { "summary": "快递公司列表查询", "description": "可查询万维易源支持的1500多家快递公司的列表。", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "ret_code": { "type": "number" }, "flag": { "type": "boolean" }, "express_list": { "type": "array", "items": { "type": "object", "properties": { "img_url": { "type": "string" }, "com": { "type": "string" }, "phone": { "type": "string" }, "exp_name": { "type": "string" }, "url": { "type": "string" }, "note": { "type": "string" } } } }, "msg": { "type": "string" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "2650_5_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "exp_name": { "type": "string", "description": "快递公司名 " } } } } } } } }, "/2650-3": { "x-pointCode": 3, "x-mode": "mapping", "x-read-timeout": 35, "x-connect-timeout": 35, "post": { "summary": "按次计费查询物流", "description": "本服务采用按次计费模式，即用户每次进行查询快递时都会产生相应的费用。\n调用此服务时，接口会以阻塞式同步调用方式运行，这意味着在请求处理完成并收到响应之前，调用者将无法进行其他操作，需耐心等待结果返回。\n更多帮助请查看 https://www.showapi.com/apiGateway/view/2650/8?tab=3", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "nu": { "type": "string", "description": "快递单号" }, "logo": { "type": "string", "description": "快递公司logo" }, "ret_code": { "type": "number", "description": "调用说明\n0 查询成功 或 提交成功\n1 输入参数错误\n2 查不到物流信息\n3 单号不符合规则\n4 快递公司编码不符合规则\n5 快递查询渠道异常\n6 auto时未查到单号对应的快递公司,请指定快递公司编码\n7 单号与手机号不匹配 其他参数：接口调用失败\n\n101 揽件\n102 在途中\n103 派送中\n104 已签收 (完结状态)\n105 用户拒签\n106 问题/疑难件\n107 无效单 (完结状态) \n108 超时单\n109 签收失败\n110 退回\n111 转投\n112 待签\n113 邮件回收" }, "com": { "type": "string", "description": "快递公司编码" }, "update_time": { "type": "string", "description": "更新时间" }, "tel": { "type": "string", "description": "快递公司联系方式" }, "showapi_inner_fee_num": { "type": "number", "description": "计费次数" }, "query_num": { "type": "number", "description": "当前单号查询的次数" }, "data": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "description": "发生的时间" }, "context": { "type": "string", "description": "跟踪信息" }, "location": { "type": "string", "description": "位置对应的坐标信息，坐标系是：GCJ-02" }, "address": { "type": "string", "description": "位置信息" }, "status": { "type": "number", "description": "状态信息\n101 揽件\n102 在途中\n103 派送中\n104 已签收 (完结状态)\n105 用户拒签\n106 疑难件\n107 无效单 (完结状态) \n108 超时单\n109 签收失败\n110 退回\n111 转投\n112 待签" }, "sub_status": { "type": "number", "description": "（试营）子状态\nstatus=104 已签收 (完结状态)\t\t\n- 10401\t已签收\n- 10402\t从快递柜或者驿站取出\n- 10403\t退回签收" } } }, "description": "物流跟踪信息列表，即在途数据" }, "com_name": { "type": "string", "description": "快递公司名称" }, "possible_exp_list": { "type": "array", "items": { "type": "object", "properties": { "com": { "type": "string", "description": "快递公司编码" }, "com_name": { "type": "string", "description": "快递公司名称" } } }, "description": "猜测列表。仅当com参数值为auto，且查询失败时才有返回值。返回结果参考如下：\"possible_exp_list\": [\n {\n \"com\": \"zhongtong\",\n \"com_name\": \"中通快递\"\n },...\n ]" }, "msg": { "type": "string", "description": "返回说明" }, "delivery_time": { "type": "string", "description": "预计到达时间（格式：yyyy-MM-dd HH:mm）。该信息是基于历史数据分析的结果，不代表实际情况，仅供参考。" }, "predict_data": { "type": "object", "properties": { "context": { "type": "string", "description": "预测物流信息" }, "address": { "type": "string", "description": "预测地址" }, "status": { "type": "string", "description": "预测状态" }, "time": { "type": "string", "description": "预测时间" }, "location": { "type": "string", "description": "预测坐标" } }, "description": "预测数据" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "2650_3_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "com": { "type": "string", "description": "快递公司字母简称，可以从\"快递公司列表\"或\"快递公司查询\" 接口中查到该信息\n如不知道快递公司名,可以使用\"auto\"代替，此时将自动识别快递单号【auto是基于以往单号的特征进行人工智能分析，会有一定的误差，请谨慎使用】 " }, "nu": { "type": "string", "description": "快递单号 " }, "phone": { "type": "string", "description": "收件人或寄件人电话号码后四位。目前，查【顺丰、跨越、中通】该参数必填。\n注：隐私号需要完整后四位，例：13xxxxx1-234,则需要传入的后四位为1234" }, "delivery_address": { "type": "string", "description": "最终收件地址，可用于反生成最终经纬度和预测收件时间，添加时最少包含省市区" }, "shipping_address": { "type": "string", "description": "寄件地址，用于预测收件时间，添加时最少包含省市区" } }, "required": [ "nu" ] } } } } } }, "/2650-2": { "x-pointCode": 2, "x-mode": "mapping", "x-read-timeout": 30, "x-connect-timeout": 30, "post": { "summary": "批量提交订阅单号", "description": "批量提交快递单号（每次最多提交100单），如果此单物流轨迹有更新，则易源会将物流结果推送至用户定义的回调URL（此URL由\"【工具】设置推送回调地址\"接入点来设定），直至签收结束。\n由于是异步操作，易源加入了多次重试、容错切换等机制，可以大大避免快递查询高峰带来的业务抖动，提高查询成功率。\n更多帮助请查看 https://www.showapi.com/book/editorDoc/4232/1\n推送时，您的服务器需要返回 ：【http返回状态码=200 且 返回体为{\"success\":true} 确认收信成功。】", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "ret_code": { "type": "number", "description": "0：提交成功\n1：参数错误" }, "fail_list": { "type": "array", "items": { "type": "object", "properties": { "nu": { "type": "string", "description": "提交的单号" }, "com": { "type": "string", "description": "提交的快递编码" }, "remark": { "type": "string", "description": "说明" }, "phone": { "type": "string", "description": "手机号" }, "out_code": { "type": "string", "description": "自定义参数" }, "shipping_address": { "type": "string", "description": "寄件地址" }, "delivery_address": { "type": "string", "description": "收件地址" }, "item_code": { "type": "string", "description": "记录类型\n1：运单号错误\n3：运单号格式不正确\n4：当前快递编码未收录或者已失效\n6：auto时未查到单号对应的快递公司,请指定快递公司编码" } } }, "description": "提交失败的列表" }, "update_time": { "type": "string", "description": "提交时间" }, "msg": { "type": "string", "description": "返回说明" }, "showapi_inner_fee_num": { "type": "number", "description": "计费次数（成功次数）" }, "succ_list": { "type": "array", "items": { "type": "object", "properties": { "nu": { "type": "string", "description": "提交的单号" }, "com": { "type": "string", "description": "提交的快递编码" }, "remark": { "type": "string", "description": "说明" }, "phone": { "type": "string", "description": "手机号" }, "out_code": { "type": "string", "description": "自定义参数" }, "shipping_address": { "type": "string", "description": "寄件地址" }, "delivery_address": { "type": "string", "description": "收件地址" }, "item_code": { "type": "string", "description": "记录类型\n0：提交成功\n8：重复单号，订阅记录更新成功" } } }, "description": "提交成功的列表" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "2650_2_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "nu_list": { "type": "string", "minLength": 0, "maxLength": 100000000, "description": "快递编码和单号，每次最多提交100个单号。格式如下：\n[\n {\n \"com\":\"shunfeng\",\n \"nu\":\"299801844590\",\n \"phone\":\"\",\n \"shipping_address\":\"\",\n \"delivery_address\":\"\",\n \"out_code\":\"my_order_id123\",\n \"format\":\"json\"\n }\n]\n\n其中phone用于顺丰、跨越，后续会根据物流官方需求更新\n注：隐私号需要完整后四位，例：13xxxxx1-234,则需要传入的后四位为1234；\n\ncom为快递公司简称也叫做快递编码【支持auto】；\n\nnu为快递单号；\n\nout_code为该笔快递单号的对应的唯一业务标识，由使用方自行定义，返回该笔物流轨迹时数据中会携带该参数信息。\n\nshipping_address为该笔订单发货地址，添加时最少需要包含省市区，默认为最新的轨迹地址\n\ndelivery_address 为该笔订单收货地址，添加时最少需要包含省市区，默认为最终的轨迹地址\n*计费说明: 提交多个单号,通常会扣减多笔费用(重复提交的不扣费).\n\nformat 为该笔订单推送格式目前支持json和xml两种，默认json" }, "callback_url": { "type": "string", "description": "本次批量提交的单号，查询结果推送到该url地址下。如果已经通过\"设置回调地址\"接口设置过回调地址，此处可以不用填写该参数。如果两处均设置了url地址，该批提交的单号以当前设置的为准。" } }, "required": [ "nu_list" ] } } } } } }, "/2650-1": { "x-pointCode": 1, "x-mode": "mapping", "x-read-timeout": 30, "x-connect-timeout": 30, "post": { "summary": "设置回调地址", "description": "设置订阅推送所需的回调地址，用于接收快递查询结果的实时推送。适用于需要自动更新快递状态的电商网站、物流管理系统和第三方服务平台等场景。注意，新建了应用的，请按照帮助手册进行配置", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "callback_open_status": { "type": "string", "description": "是否开启加密：用于推送数据时保证数据来源的安全性\n0-不开启 \n1-开启 " }, "callback_secret": { "type": "string", "description": "密钥" }, "ret_code": { "type": "number", "description": "0 提交成功;\n1 参数错误-回调地址设置失败" }, "update_time": { "type": "string", "description": "更新时间" }, "msg": { "type": "string", "description": "返回说明" }, "callback_url": { "type": "string", "description": "设置成功的回调地址" }, "ret_content": { "type": "string", "description": "回调的内容" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "2650_1_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "callback_url": { "type": "string", "description": "回调地址 \n注意，新建了应用的，请按照帮助手册进行配置\n\n用户服务器收到易源请求后，需要回复一个消息以确认。此消息的要求是：\n- http的返回状态为必须为200。\n- http的返回体是：{\"success\":true}\n如果不满足上面2个条件则认为失败。失败时易源会重复推送5次，间隔时间分别是2,4,8,16,32分钟。" }, "com": { "type": "string", "description": "真实快递编码 " }, "nu": { "type": "string", "description": "真实单号" }, "phone": { "type": "string", "description": "部分快递需要手机号" } }, "required": [ "callback_url", "com", "nu" ] } } } } } } }, "components": { "securitySchemes": { "AppKeyAuth": { "type": "apiKey", "in": "query", "name": "appKey", "description": "从 ShowAPI 控制台获取的 appKey，管理地址：https://www.showapi.com/console#/myApp" } }, "schemas": { "ShowapiResEnvelope": { "type": "object", "description": "ShowAPI 统一返回包裹（业务数据位于 showapi_res_body）", "properties": { "showapi_res_code": { "type": "integer", "description": "API 返回的状态码" }, "showapi_res_error": { "type": "string", "description": "API 返回的错误信息" }, "showapi_res_id": { "type": "string", "description": "API 请求的唯一标识" }, "showapi_fee_num": { "type": "integer", "description": "API 调用计费次数" } } } } }, "security": [ { "AppKeyAuth": [] } ], "externalDocs": { "url": "https://www.showapi.com/apiGateway/view/2650?tab=book" }, "x-apiCode": "2650", "x-is-own": true, "x-is-op": true }