# Generated by ShowAPI OpenAPI generator
# source: market/64
# generated-at: 2026-06-25T23:03:16.793Z
openapi: 3.0.3
info:
  title: 全球快递查询
  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:
  /64-34:
    x-pointCode: 34
    x-mode: mapping
    x-read-timeout: 30
    x-connect-timeout: 30
    post:
      summary: 按单查询快递物流
      description: |-
        使用快递单号实时查询物流信息轨迹，包括收件、运输、配送情况等。本接入点为阻塞式的同步调用。
        更多帮助请查看 https://www.showapi.com/book/view/3157/13
        30天内1个快递单多次查询只扣1次费。
      responses:
        "200":
          description: 成功响应
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ShowapiResEnvelope"
                  - type: object
                    properties:
                      showapi_res_body:
                        type: object
                        properties:
                          update:
                            type: number
                            description: 更新时间戳
                          upgrade_info:
                            type: string
                            description: 提示信息，用于提醒用户可能出现的情况
                          updateStr:
                            type: string
                            description: 更新时间
                          logo:
                            type: string
                            description: 快递公司logo
                          dataSize:
                            type: number
                            description: 数据节点的长度
                          status:
                            type: number
                            description: |-
                              快递状态
                               1 暂无记录
                               2 在途中
                               3 派送中
                               4 已签收 (完结状态)
                               5 用户拒签
                               6 问题/疑难件
                               7 无效单 (完结状态)
                               8 超时单
                               9 签收失败
                               10 退回
                          fee_num:
                            type: number
                            description: 计费次数。例如：0为计费0次，即不计费；1为计费1次
                          tel:
                            type: string
                            description: 快递公司联系方式
                          data:
                            type: array
                            items:
                              type: object
                              properties:
                                time:
                                  type: string
                                context:
                                  type: string
                          expSpellName:
                            type: string
                            description: 快递编码
                          msg:
                            type: string
                            description: 返回提示信息
                          mailNo:
                            type: string
                            description: 快递单号
                          queryTimes:
                            type: number
                            description: 查询次数
                          ret_code:
                            type: number
                            description: |-
                              0        查询成功 或 提交成功。
                              1        输入参数错误。
                              2        查不到物流信息。
                              3        单号不符合规则。
                              4        快递公司编码不符合规则。
                              5        快递查询渠道异常。
                              6        auto时未查到单号对应的快递公司,请指定快递公司编码。
                              7        单号与手机号不匹配
                              其他参数：接口调用失败
                          flag:
                            type: boolean
                            description: |-
                              true：查询成功，表示ret_code=0且data的长度>0。可使用本字段做是否读取data列表的依据。
                              false：查询失败。
                          expTextName:
                            type: string
                            description: 快递简称
                          possibleExpList:
                            type: array
                            items:
                              type: string
                            description: 自动识别结果
                        description: 业务返回体
      operationId: 64_34_POST
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                com:
                  type: string
                  description: |-
                    快递公司字母简称,可以从"快递公司列表"或"快递公司查询" 接口中查到该信息
                    如不知道快递公司名,可以使用"auto"代替,此时将自动识别快递单号
                    【查询顺丰时，为了保证效率，请尽量提供寄件人或者收件人查询】    
                nu:
                  type: string
                  description: "单号 "
                phone:
                  type: string
                  description: |-
                    手机尾号后四位，顺丰、跨越、中通快递必须填写本字段【寄件人手机号或者收件人手机号】
                    注：隐私号需要完整后四位，例：13xxxxx1-234,则需要传入的后四位为1234
              required:
                - nu
  /64-23:
    x-pointCode: 23
    x-mode: mapping
    x-read-timeout: 25
    x-connect-timeout: 25
    post:
      summary: 批量提交订阅单号
      description: |-
        批量提交快递单号（每次最多提交100单），如果此单物流轨迹有更新，则易源会将物流结果推送至用户定义的回调URL（此URL由"【工具】设置推送回调地址"接入点来设定），直至签收结束。
        由于是异步操作，易源加入了多次重试、容错切换等机制，可以大大避免快递查询高峰带来的业务抖动，提高查询成功率。
        更多帮助请查看 https://www.showapi.com/book/view/3157/14 
        推送时，您的服务器需要返回：
        1.http返回状态码=200
        2.返回体为{"success":true} 或 success 确认收信成功。
      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为成功，其余失败
                          succList:
                            type: array
                            items:
                              type: object
                              properties:
                                com:
                                  type: string
                                  description: 快递编码
                                remark:
                                  type: string
                                nu:
                                  type: array
                                  items:
                                    type: string
                                  description: 单号列表
                            description: 成功的列表
                          failList:
                            type: array
                            items:
                              type: object
                              properties:
                                com:
                                  type: string
                                  description: 快递编码
                                remark:
                                  type: string
                                  description: 失败原因
                                nu:
                                  type: array
                                  items:
                                    type: string
                                  description: 单号列表
                            description: 失败的列表
                          updateTimeStr:
                            type: string
                            description: 提交时间
                          succ_count:
                            type: number
                            description: 计费次数。例如：0为计费0次，即不计费；1为计费1次
                        description: 业务返回体
      operationId: 64_23_POST
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                com_nu:
                  type: string
                  minLength: 0
                  maxLength: 10000000
                  description: |-
                    快递编码和单号：每次最多提交100个 

                    详细参数：
                    com：快递编码
                    nu：快递单号
                    phone：手机号
                    outCode：任意字符串，长度小于200字符

                    示例
                    [{"com":"shunfeng","nu":"299801844590","phone":"","outCode":"任意串，长度小于200字符"},
                    {"com":"shunfeng","nu":"299801844592","phone":"","outCode":"任意串，长度小于200字符"},
                    {"com":"shunfeng","nu":"299801844593","phone":"","outCode":"任意串，长度小于200字符"}]

                    详细说明：https://www.showapi.com/apiGateway/view/?apiCode=64&pointCode=23&tab=supportDoc

                    注：隐私号需要完整后四位，例：13xxxxx1-234,则需要传入的后四位为1234
              required:
                - com_nu
  /64-22:
    x-pointCode: 22
    x-mode: mapping
    x-read-timeout: 20
    x-connect-timeout: 20
    post:
      summary: 设置推送回调地址
      description: 快递单有更新时，易源主动将全量物流轨迹以POST请求到此URL。本接入点负责设置/修改此URL
      responses:
        "200":
          description: 成功响应
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ShowapiResEnvelope"
                  - type: object
                    properties:
                      showapi_res_body:
                        type: object
                        properties:
                          ret_code:
                            type: string
                            description: 接口调用是否成功,0:扣费，表示成功,；1:不扣费，表示设置失败
                          msg:
                            type: string
                            description: 返回说明
                          updateTime:
                            type: string
                            description: 更新时间戳
                          updateTimeStr:
                            type: string
                            description: 更新时间
                          callback_url:
                            type: string
                            description: 回调地址
                          callback_method:
                            type: string
                            description: 回调的方式
                          test_response:
                            type: string
                            description: 设置的回调地址本次返回结果
                        description: 业务返回体
      operationId: 64_22_POST
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                callBackUrl:
                  type: string
                  description: 回调地址
  /64-21:
    x-pointCode: 21
    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: string
                            description: 业务请求是否成功
                          msg:
                            type: string
                            description: 操作提示
                          data:
                            type: string
                            description: 返回的数据
                        description: 业务返回体
      operationId: 64_21_POST
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                nu:
                  type: string
                  description: 快递单号
                addOther:
                  type: string
                  description: 存在时返回logo、官网、电话
              required:
                - nu
  /64-20:
    x-pointCode: 20
    x-mode: mapping
    x-read-timeout: 5
    x-connect-timeout: 5
    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:
                          flag:
                            type: string
                            description: 是否查询到数据
                          expressList:
                            type: string
                            description: 快递公司列表数据
                          expName:
                            type: string
                            description: 快递公司名称
                          simpleName:
                            type: string
                            description: 简称
                          url:
                            type: string
                            description: 官方网址
                          note:
                            type: string
                            description: 描述
                          phone:
                            type: string
                            description: 快递公司服务电话
                          imgUrl:
                            type: string
                            description: 快递公司图标
                          ret_code:
                            type: string
                            description: 0为成功，其他失败
                        description: 业务返回体
      operationId: 64_20_POST
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                expName:
                  type: string
                  description: 快递公司名
                maxSize:
                  type: string
                  description: 分页时,返回的最大数据量
                page:
                  type: string
                  description: 当前页数
  /64-19:
    x-pointCode: 19
    x-mode: mapping
    x-read-timeout: 60
    x-connect-timeout: 60
    post:
      summary: 按次查询快递物流
      description: |-
        使用快递单号实时查询物流信息轨迹，包括收件、运输、配送情况等。
        本接入点为阻塞式的同步调用。如需要异步调用，请联系客服。
        更多帮助请查看  https://www.showapi.com/book/view/3157/11
      responses:
        "200":
          description: 成功响应
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ShowapiResEnvelope"
                  - type: object
                    properties:
                      showapi_res_body:
                        type: object
                        properties:
                          update:
                            type: number
                            description: 更新时间戳
                          upgrade_info:
                            type: string
                            description: 提示信息，用于提醒用户可能出现的情况
                          updateStr:
                            type: string
                            description: 更新时间
                          logo:
                            type: string
                            description: 快递公司logo
                          dataSize:
                            type: number
                            description: 数据节点的长度
                          status:
                            type: number
                            description: |-
                              快递状态
                               1 暂无记录
                               2 在途中
                               3 派送中
                               4 已签收 (完结状态)
                               5 用户拒签
                               6 问题/疑难件
                               7 无效单 (完结状态)
                               8 超时单
                               9 签收失败
                               10 退回
                          fee_num:
                            type: number
                            description: 计费次数。例如：0为计费0次，即不计费；1为计费1次
                          tel:
                            type: string
                            description: 快递公司联系方式
                          data:
                            type: array
                            items:
                              type: object
                              properties:
                                time:
                                  type: string
                                context:
                                  type: string
                          expSpellName:
                            type: string
                            description: 快递编码
                          msg:
                            type: string
                            description: 返回提示信息
                          mailNo:
                            type: string
                            description: 快递单号
                          queryTimes:
                            type: number
                            description: 查询次数
                          ret_code:
                            type: number
                            description: |-
                              0        查询成功 或 提交成功。
                              1        输入参数错误。
                              2        查不到物流信息。
                              3        单号不符合规则。
                              4        快递公司编码不符合规则。
                              5        快递查询渠道异常。
                              6        auto时未查到单号对应的快递公司,请指定快递公司编码。
                              7        单号与手机号不匹配
                              其他参数：接口调用失败
                          flag:
                            type: boolean
                            description: |-
                              true：查询成功，表示ret_code=0且data的长度>0。可使用本字段做是否读取data列表的依据。
                              false：查询失败。
                          expTextName:
                            type: string
                            description: 快递简称
                          possibleExpList:
                            type: array
                            items:
                              type: string
                            description: 自动识别结果
                        description: 业务返回体
      operationId: 64_19_POST
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                com:
                  type: string
                  description: |-
                    快递公司字母简称,可以从"快递公司列表"或"快递公司查询" 接口中查到该信息
                    如不知道快递公司名,可以使用"auto"代替,此时将自动识别快递单号
                    【查询顺丰时，为了保证效率，请尽量提供寄件人或者收件人查询】    
                nu:
                  type: string
                  description: "单号 "
                callBackUrl:
                  type: string
                  description: |-
                    实时物流跟踪查询方式二（执行异步方式的开关），存在回调地址则执行异步任务
                    回调地址（http://www.xxxx.xxxx），请提交真实外网地址。
                    采用后扣费的方式，具体扣费规则和实时查询一样。
                    【查询顺丰时，为了保证效率，请尽量提供寄件人或者收件人查询】
                phone:
                  type: string
                  description: |-
                    手机尾号后四位，顺丰快递必须填写本字段【寄件人手机号或者收件人手机号】
                    注：隐私号需要完整后四位，例：13xxxxx1-234,则需要传入的后四位为1234
              required:
                - 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/64?tab=book
x-apiCode: "64"
x-is-own: false
x-is-op: true
