Skip to content

keqin-inc/UnifiedExpress

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

27 Commits
src
src
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
package.json
package.json
 
 

Repository files navigation

UnifiedExpress

封装不同快递接口，并返回统一格式

目前支持的快递和接口

快递 代码 接口 接口的申请网址
中通 ZTO 中通开放平台 https://zop.zto.com/
申通 STO 涪擎（阿里云市场） https://market.aliyun.com/products/56928004/cmapi022273.html
京东物流 JD 涪擎（阿里云市场） https://market.aliyun.com/products/56928004/cmapi022273.html
韵达快递 YUNDA 涪擎（阿里云市场） https://market.aliyun.com/products/56928004/cmapi022273.html
圆通 YTO 圆通开放平台 http://open.yto.net.cn/
顺丰 SF 顺丰丰桥接口 https://qiao.sf-express.com

未来将增加更多快递和接口支持

Quick Start

// 查询中通的示例，需要把 key 和 company_id 替换成自己在中通开放平台的信息

const UE = require('unifiedexpress');
const ue = new UE({
  ZTO: {
    source: 'zto',
    cfg: {
      key: '', //  替换成自己的配置
      company_id: '' // 中通公司ID
    }
  },
});
ue.query({
    no: '73107975056357',
    company: '中通'
  })
  .then(body => {
    console.log(body);
  })
  .catch(err => {
    console.log('出现异常', err);
  });

返回的数据

{ no: '73107975056357',
  deliverRemark: '自提件',
  deliverDate: '2018-12-27 14:06:25',
  hasReject: false,
  received: false,
  delivering: true,
  traces:
   [ { dispOrRecMan: '冯鑫华',
       dispOrRecManCode: '',
       dispOrRecManPhone: '18307857510',
       isCenter: 'F',
       preOrNextCity: '',
       preOrNextProv: '',
       preOrNextSite: '',
       preOrNextSiteCode: '',
       preOrNextSitePhone: '',
       remark: '',
       scanCity: '贵港市',
       scanDate: '2018-12-25 16:17:47',
       scanProv: '广西壮族自治区',
       scanSite: '桂平',
       scanSiteCode: '77530',
       scanSitePhone: '0775-3337900',
       scanType: '收件',
       signMan: '',
       msg: '【贵港市】  【桂平】（0775-3337900） 的 冯鑫华 （18307857510） 已揽收' },
     { dispOrRecMan: '',
       dispOrRecManCode: '',
       dispOrRecManPhone: '',
       isCenter: 'F',
       preOrNextCity: '南昌市',
       preOrNextProv: '江西省',
       preOrNextSite: '南昌中转部',
       preOrNextSiteCode: '79100',
       preOrNextSitePhone: '0791-86150780、0791-86150799',
       remark: '',
       scanCity: '贵港市',
       scanDate: '2018-12-25 19:41:39',
       scanProv: '广西壮族自治区',
       scanSite: '桂平',
       scanSiteCode: '77530',
       scanSitePhone: '0775-3337900',
       scanType: '发件',
       signMan: '',
       msg: '【贵港市】  快件离开 【桂平】 发往 【南昌中转部】' },
     { dispOrRecMan: '',
       dispOrRecManCode: '',
       dispOrRecManPhone: '',
       isCenter: 'T',
       preOrNextCity: '',
       preOrNextProv: '',
       preOrNextSite: '',
       preOrNextSiteCode: '',
       preOrNextSitePhone: '',
       remark: '',
       scanCity: '南宁市',
       scanDate: '2018-12-26 00:01:56',
       scanProv: '广西壮族自治区',
       scanSite: '南宁中转',
       scanSiteCode: '77100',
       scanSitePhone: '0771-4309537、0771-4304127',
       scanType: '到件',
       signMan: '',
       msg: '【南宁市】  快件到达 【南宁中转】' },
     { dispOrRecMan: '',
       dispOrRecManCode: '',
       dispOrRecManPhone: '',
       isCenter: 'T',
       preOrNextCity: '南昌市',
       preOrNextProv: '江西省',
       preOrNextSite: '南昌中转部',
       preOrNextSiteCode: '79100',
       preOrNextSitePhone: '0791-86150780、0791-86150799',
       remark: '',
       scanCity: '南宁市',
       scanDate: '2018-12-26 00:07:24',
       scanProv: '广西壮族自治区',
       scanSite: '南宁中转',
       scanSiteCode: '77100',
       scanSitePhone: '0771-4309537、0771-4304127',
       scanType: '发件',
       signMan: '',
       msg: '【南宁市】  快件离开 【南宁中转】 发往 【南昌中转部】' },
     { dispOrRecMan: '',
       dispOrRecManCode: '',
       dispOrRecManPhone: '',
       isCenter: 'T',
       preOrNextCity: '',
       preOrNextProv: '',
       preOrNextSite: '',
       preOrNextSiteCode: '',
       preOrNextSitePhone: '',
       remark: '',
       scanCity: '南昌市',
       scanDate: '2018-12-26 23:40:48',
       scanProv: '江西省',
       scanSite: '南昌中转部',
       scanSiteCode: '79100',
       scanSitePhone: '0791-86150780、0791-86150799',
       scanType: '到件',
       signMan: '',
       msg: '【南昌市】  快件到达 【南昌中转部】' },
     { dispOrRecMan: '',
       dispOrRecManCode: '',
       dispOrRecManPhone: '',
       isCenter: 'T',
       preOrNextCity: '九江市',
       preOrNextProv: '江西省',
       preOrNextSite: '九江星子',
       preOrNextSiteCode: '79214',
       preOrNextSitePhone: '0792-2678298、0792-2552298',
       remark: '',
       scanCity: '南昌市',
       scanDate: '2018-12-26 23:41:32',
       scanProv: '江西省',
       scanSite: '南昌中转部',
       scanSiteCode: '79100',
       scanSitePhone: '0791-86150780、0791-86150799',
       scanType: '发件',
       signMan: '',
       msg: '【南昌市】  快件离开 【南昌中转部】 发往 【九江星子】' },
     { dispOrRecMan: '',
       dispOrRecManCode: '',
       dispOrRecManPhone: '',
       isCenter: 'F',
       preOrNextCity: '',
       preOrNextProv: '',
       preOrNextSite: '',
       preOrNextSiteCode: '',
       preOrNextSitePhone: '',
       remark: '',
       scanCity: '九江市',
       scanDate: '2018-12-27 08:45:42',
       scanProv: '江西省',
       scanSite: '九江星子',
       scanSiteCode: '79214',
       scanSitePhone: '0792-2678298、0792-2552298',
       scanType: '到件',
       signMan: '',
       msg: '【九江市】  快件到达 【九江星子】' },
     { dispOrRecMan: '刘幼生',
       dispOrRecManCode: '',
       dispOrRecManPhone: '15079270857',
       isCenter: 'F',
       preOrNextCity: '',
       preOrNextProv: '',
       preOrNextSite: '',
       preOrNextSiteCode: '',
       preOrNextSitePhone: '',
       remark: '',
       scanCity: '九江市',
       scanDate: '2018-12-27 08:45:51',
       scanProv: '江西省',
       scanSite: '九江星子',
       scanSiteCode: '79214',
       scanSitePhone: '0792-2678298、0792-2552298',
       scanType: '派件',
       signMan: '',
       msg: '【九江市】  【九江星子】 的刘幼生（15079270857） 正在第1次派件, 请保持电话畅通,并耐心等待' },
     { dispOrRecMan: '',
       dispOrRecManCode: '',
       dispOrRecManPhone: '',
       isCenter: 'F',
       preOrNextCity: '',
       preOrNextProv: '',
       preOrNextSite: '',
       preOrNextSiteCode: '',
       preOrNextSitePhone: '',
       remark: '',
       scanCity: '九江市',
       scanDate: '2018-12-27 14:06:25',
       scanProv: '江西省',
       scanSite: '九江星子',
       scanSiteCode: '79214',
       scanSitePhone: '0792-2678298、0792-2552298',
       scanType: '问题件',
       signMan: '',
       msg: '【九江市】  【九江星子】 的 刘幼生 已进行【问题件】上报，原因：自提件' } ],
  status: '派送中' }

查询接口参数

ue.query({ 
  no: '',
  company: '' ,
  checkPhoneNo: '' // 可选参数
});
  • no 为快递单号
  • company 为指定的快递公司，可以是中文（申通）或代码（STO）
  • checkPhoneNo 可选，当快递为顺丰时可使用，为收件人或发件人后手机号 4 位，验证订单。当丰桥账号已经绑定月结账号或使用的是其他快递公司时，可以省略。

由于不同快递公司使用不同接口，自动根据单号识别公司存在误差，所以必须指定 company 参数

返回结果

{ 
  no: '73107975056357',
  deliverRemark: '自提件',
  deliverDate: '2018-12-27 14:06:25',
  hasReject: false,
  returnNo: '',
  received: false,
  delivering: true,
  traces:
   [],
  status: '派送中'
}

字段说明

  • no: string 查询的快递单号
  • deliverRemark: string 派送备注，可能是签收人信息或者派送中的备注
  • deliverDate: datetime 派送/签收时间，上报派送、签收的时间
  • hasReject: boolean 是否出现过退回信息，拒收、发件公司召回、错分件都有可能产生此信息，拒收以 status 为准
  • received: boolean 是否已签收
  • returnNo: 【顺丰特有】退件时的快递单号，其他快递公司的当前快递会直接追加退件物流状态，顺丰则单独返回单号。你大爷就是你大爷。
  • delivering: boolean 是否出现过派送中的信息
  • traces: array
    • msg: string 路由状态，在 traces 里目前仅此字段是统一的，其他字段由不同接口会返回不同字段；将来可能统一更多字段，例如时间
  • status: string 共五种状态，为 查询不到、运输中 、派送中、已签收、拒收。未来可能增加更多状态，例如“揽收”或“快递柜签收”。

安装

npm i unifiedexpress --save

配置

const UE = require('unifiedexpress');
const ue = new UE({
  // 要查询的快递公司
  ZTO: {
    // 数据源
    source: 'zto',
    // 数据源配置
    cfg: {
      key: '',
      company_id: '' // 中通公司ID
    }
  },
  STO: {
    source: 'fegine',
    cfg:{
      appcode: '', //阿里云市场后台的 AppCode
    }
  },
  YTO: {
    source: 'yto',
    cfg: {
      user_id: '', // 圆通 User_Id
      app_key: '', // 圆通  App_Key
      secret_key: '' // 圆通 Secret_Key
    }
  },
  SF: {
    source: 'sf',
    cfg: {
      customer_code: '', // 顺丰丰桥顾客编码
      checkword: '' // 顺丰丰桥校验码
    }
  },
  JD: {
    source: 'fegine',
    cfg:{
      appcode: '', //阿里云市场后台的 AppCode
    }
  },
  YUNDA: {
    source: 'fegine',
    cfg:{
      appcode: '', //阿里云市场后台的 AppCode
    }
  }
});

环境变量配置

通过环境变量配置，可启用约定的默认接口查询，无需额外配置。 此项目的测试用例也是用这种方式配置的，把 .env 文件放在根目录下后 npm run test 即可运行测试用例。

示例：

ZTO_KEY=
ZTO_COMPANY_ID=
FEGINE_APPCODE=
YTO_USER_ID=
YTO_APP_KEY=
YTO_SECRET_KEY=
SF_CUSTOMER_CODE=
SF_CHECKWORD=

Changelog

  • 1.0.8 支持顺丰丰桥接口
  • 1.0.5 支持圆通开放平台的查询
  • 1.0.1 增加查询不到、运输中状态，并在接口异常时抛出错误
  • 1.0.0 第一版

About

克勤统一快递解析库

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages