# Generated by ShowAPI OpenAPI generator
# source: market/2650
# generated-at: 2026-06-26T04:36:30.339Z
openapi: 3.0.3
info:
  title: 全球快递物流查询-V2
  description: 【顺丰快递-快递查询-物流查询-快递物流单号查询--快递单号查询】支持国内外1500多家快递物流公司，覆盖顺丰、四通一达、宅急送、德邦、百世、天天、京东、EMS等快递，与官网同步数据更新。提供物流轨迹，可配合快递订阅推送使用！【快递新用户请使用：全国快递物流查询-V2，V2与V1的区别<a href=' https://www.showapi.com/images/apiGateway/kd_v1VSv2.png'  target='_blank'>点击查看</a>】。
  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: |-
        同步查询快递物流信息，按单计费。
        30天内1个快递单多次查询只扣1次费。
        更多帮助请查看 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: |-
                              调用说明
                              0 查询成功 或 提交成功
                              1 输入参数错误
                              2 查不到物流信息
                              3 单号不符合规则
                              4 快递公司编码不符合规则
                              5 快递查询渠道异常
                              6 auto时未查到单号对应的快递公司,请指定快递公司编码
                              7 单号与手机号不匹配 其他参数：接口调用失败

                              101 揽件
                              102 在途中
                              103 派送中
                              104 已签收 (完结状态)
                              105 用户拒签
                              106 问题/疑难件
                              107 无效单 (完结状态) 
                              108 超时单
                              109 签收失败
                              110 退回
                              111 转投
                              112 待签
                              113 邮件回收
                          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: |-
                                    状态信息
                                    101 揽件
                                    102 在途中
                                    103 派送中
                                    104 已签收 (完结状态)
                                    105 用户拒签
                                    106 疑难件
                                    107 无效单 (完结状态) 
                                    108 超时单
                                    109 签收失败
                                    110 退回
                                    111 转投
                                    112 待签
                                location:
                                  type: string
                                  description: 位置对应的坐标信息，坐标系是：GCJ-02
                                address:
                                  type: string
                                  description: 位置信息
                                sub_status:
                                  type: number
                                  description: |-
                                    （试营）子状态
                                    status=104 已签收 (完结状态)		
                                    - 10401	已签收
                                    - 10402	从快递柜或者驿站取出
                                    - 10403	退回签收
                            description: 物流跟踪信息列表，即在途数据
                          com_name:
                            type: string
                            description: 快递公司名字
                          possible_exp_list:
                            type: array
                            items:
                              type: string
                            description: |-
                              猜测列表。仅当com参数值为auto，且查询失败时才有返回值。返回结果参考如下："possible_exp_list": [
                                    {
                                      "com": "zhongtong",
                                      "com_name": "中通快递"
                                    },...
                                  ]
                          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: |-
                    快递公司字母简称，可以从"快递公司列表"或"快递公司查询" 接口中查到该信息
                    如不知道快递公司名,可以使用"auto"代替，此时将自动识别快递单号【auto是基于以往单号的特征进行人工智能分析，会有一定的误差，请谨慎使用】   
                nu:
                  type: string
                  description: "快递单号 "
                phone:
                  type: string
                  description: |-
                    收件人或寄件人电话号码后四位。目前，查【顺丰、跨越、中通】该参数必填。
                    注：隐私号需要完整后四位，例：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：查询成功
                              1：参数错误
                          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: |-
        本服务采用按次计费模式，即用户每次进行查询快递时都会产生相应的费用。
        调用此服务时，接口会以阻塞式同步调用方式运行，这意味着在请求处理完成并收到响应之前，调用者将无法进行其他操作，需耐心等待结果返回。
        更多帮助请查看  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: |-
                              调用说明
                              0 查询成功 或 提交成功
                              1 输入参数错误
                              2 查不到物流信息
                              3 单号不符合规则
                              4 快递公司编码不符合规则
                              5 快递查询渠道异常
                              6 auto时未查到单号对应的快递公司,请指定快递公司编码
                              7 单号与手机号不匹配 其他参数：接口调用失败

                              101 揽件
                              102 在途中
                              103 派送中
                              104 已签收 (完结状态)
                              105 用户拒签
                              106 问题/疑难件
                              107 无效单 (完结状态) 
                              108 超时单
                              109 签收失败
                              110 退回
                              111 转投
                              112 待签
                              113 邮件回收
                          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: |-
                                    状态信息
                                    101 揽件
                                    102 在途中
                                    103 派送中
                                    104 已签收 (完结状态)
                                    105 用户拒签
                                    106 疑难件
                                    107 无效单 (完结状态) 
                                    108 超时单
                                    109 签收失败
                                    110 退回
                                    111 转投
                                    112 待签
                                sub_status:
                                  type: number
                                  description: |-
                                    （试营）子状态
                                    status=104 已签收 (完结状态)		
                                    - 10401	已签收
                                    - 10402	从快递柜或者驿站取出
                                    - 10403	退回签收
                            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": [
                                    {
                                      "com": "zhongtong",
                                      "com_name": "中通快递"
                                    },...
                                  ]
                          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: |-
                    快递公司字母简称，可以从"快递公司列表"或"快递公司查询" 接口中查到该信息
                    如不知道快递公司名,可以使用"auto"代替，此时将自动识别快递单号【auto是基于以往单号的特征进行人工智能分析，会有一定的误差，请谨慎使用】   
                nu:
                  type: string
                  description: "快递单号 "
                phone:
                  type: string
                  description: |-
                    收件人或寄件人电话号码后四位。目前，查【顺丰、跨越、中通】该参数必填。
                    注：隐私号需要完整后四位，例：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由"【工具】设置推送回调地址"接入点来设定），直至签收结束。
        由于是异步操作，易源加入了多次重试、容错切换等机制，可以大大避免快递查询高峰带来的业务抖动，提高查询成功率。
        更多帮助请查看 https://www.showapi.com/book/editorDoc/4232/1
        推送时，您的服务器需要返回 ：【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：提交成功
                              1：参数错误
                          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: |-
                                    记录类型
                                    1：运单号错误
                                    3：运单号格式不正确
                                    4：当前快递编码未收录或者已失效
                                    6：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: |-
                                    记录类型
                                    0：提交成功
                                    8：重复单号，订阅记录更新成功
                            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个单号。格式如下：
                    [
                        {
                            "com":"shunfeng",
                            "nu":"299801844590",
                            "phone":"",
                            "shipping_address":"",
                            "delivery_address":"",
                            "out_code":"my_order_id123",
                            "format":"json"
                        }
                    ]

                    其中phone用于顺丰、跨越，后续会根据物流官方需求更新
                    注：隐私号需要完整后四位，例：13xxxxx1-234,则需要传入的后四位为1234；

                    com为快递公司简称也叫做快递编码【支持auto】；

                    nu为快递单号；

                    out_code为该笔快递单号的对应的唯一业务标识，由使用方自行定义，返回该笔物流轨迹时数据中会携带该参数信息。

                    shipping_address为该笔订单发货地址，添加时最少需要包含省市区，默认为最新的轨迹地址

                    delivery_address 为该笔订单收货地址，添加时最少需要包含省市区，默认为最终的轨迹地址
                    *计费说明: 提交多个单号,通常会扣减多笔费用(重复提交的不扣费).

                    format  为该笔订单推送格式目前支持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: |-
                              是否开启加密：用于推送数据时保证数据来源的安全性
                              0-不开启 
                              1-开启 
                          callback_secret:
                            type: string
                            description: 密钥
                          ret_code:
                            type: number
                            description: |-
                              0 提交成功;
                              1 参数错误-回调地址设置失败
                          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: |-
                    回调地址 
                    注意，新建了应用的，请按照帮助手册进行配置

                    用户服务器收到易源请求后，需要回复一个消息以确认。此消息的要求是：
                    - http的返回状态为必须为200。
                    - http的返回体是：{"success":true}
                    如果不满足上面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
