快递柜投放场景短信对接白皮书

1、服务介绍

本服务解决在手机号脱敏背景下，快递投妥后无法进行取货码短信通知问题。

2、对接流程

2.1入驻云鼎平台

云鼎平台网址：https://yd.jdcloud.com/#/
点击入驻云鼎，如已有账号则不需注册。

选择入驻身份为：物流，点击立即入驻，并填写相关资料

2.2创建快递柜系统应用

待资料审核后，在云鼎控制台【业务组件】-【虎符】-【应用管理】页面https://hufu-yd-console.jdcloud.com/#/hufu/list 创建应用，选择业务域：物流，应用类型：快递柜

创建京东云用户签名：AK,SK管理地址 https://uc.jdcloud.com/account/accesskey

2.3接入场景

应用创建后，在云鼎控制台【业务组件】-【虎符】-【三方互通】-【场景列表】页面http://hufu-yd-console.jdcloud.com/#/hufu/generallist，申请用已创建快递柜系统应用接入快递柜场景，接入快递柜场景会为您自动开通短信服务。

接入快递柜场景后，在云鼎控制台【业务组件】-【虎符】-【三方互通】-【我的场景】页面，可查看已接入场景。

2.4短信维护

2.4.1购买短信套餐包

通过控制台【业务组件】-【云鼎短信服务】-【套餐包管理】购买短信套餐包 http://yd-sms-console.jdcloud.com/package。短信账户余额是发送短信的必要条件。

2.4.2创建签名/模板

在控制台【业务组件】-【云鼎短信服务】-【应用管理】页面，点击应用名称，进入应用管理创建签名与模板，待运营审核

账户概览页面支持设置短信余量预警通知，为保障快递投柜业务正常，建议依据业务量设置短信余量预警。

2.5服务上线

2.5.1 服务开发

在【业务组件】-【虎符】-【三方互通】-【我的场景】页面 http://hufu-yd-console.jdcloud.com/#/hufu/generalmylist 点击接入管理。页面可查看授权AK/SK，通过我的API列表，对方API列表查看需要开发的接口信息。进行相应服务开发。

2.5.2 服务上线

在【业务组件】-【虎符】-【三方互通】-【我的场景】页面 http://hufu-yd-console.jdcloud.com/#/hufu/generalmylist 点击接入管理，发起上线申请。

测试时可在【测试业务】发起上线申请，需运营审核，待测试联调无问题后可在【线上业务】发起上线申请。

上线申请输入快递柜系统接收回执地址。

线上业务上线申请提交后，等待云鼎运营审核，审核通过后，可在【环境信息】生成SDK和文档，进行线上环境调用。

3、短信对接API文档及传参示例

3.1 云鼎虎符快递柜解决方案接口文档

1、相关术语

1.1、接口类型

正向接口：需要快递公司实现，上游系统调用
反向接口：上游系统实现，快递公司调用

1.2、前端授权

客户端调用虎符网关需要传入“sign”参数，虎符网关计算签名是否正确，用于校验调用者身份。

1.3、后端签名

虎符网关将请求透传到后端服务时会重新计算“sign”值，如果后端服务需要校验虎符网关的身份是否合法，可以使用相同的算法计算“sign”值，用于校验虎符网关身份。

1.4、虎符签名算法

前端授权、后端签名均使用该算法计算，可以通过虎符控制台验证签名计算是否正确 http://hufu-yd-console.jdcloud.com/#/hufu/signtool
我们用查询收获人信息接口请求为例：

http://hufu.cn-north-1.jdcloud-api.net?app_key=XXXXXXXXXXXXXXXXX&customerId=0100&method=jingdong.hufu.sms.logistics.getConsigneeInfo&sign=917DE2C2258D6DDE20EB3D6F3ED364F3&sign_method=md5&timestamp=2021-11-19 13:53:53&format=json&v=1.0

输入参数为(参数 URL Decode之后再计算签名) 注：参数列表中的sign不参与计算签名，除此之外所有参数都要参与计算签名

  app_key=XXXXXXXXXXXXXXXXX
  customerId=0100
  format=json
  method=jingdong.hufu.sms.logistics.getConsigneeInfo
  sign_method=md5
  timestamp=2021-11-19 13:53:53
  v=1.0

请求body为

{"expressCode":"ZGYZZHDD","billCode":"9830362800090"}

按首字母升序排列

app_key=XXXXXXXXXXXXXXXXX
   customerId=0100
   format=json
   method=jingdong.hufu.sms.logistics.getConsigneeInfo
   sign_method=md5
   timestamp=2021-11-19 13:53:53
   v=1.0

连接字符串: 连接参数名与参数值，body参数拼接在query参数后，并在首尾加上secret ，此处假设 secret=test ，如下：

testapp_keyXXXXXXXXXXXXXXXXXcustomerId0100methodjingdong.hufu.sms.logistics.getConsigneeInfosign_methodmd5timestamp1621318983000{"expressCode":"ZGYZZHDD","billCode":"9830362800090"}test

生成签名sign: 32位大写 MD5 值-> 211E472XXXXXXXXXXXXX288F9F368

2、系统参数

2.1、公共请求参数

2.2、公共响应信息

Error

3、接口文档

3.1、jingdong.hufu.sms.logistics.getConsigneeInfo

3.1.1、请求方式

POST

3.1.2、请求地址

https://hufu.cn-north-1.jdcloud-api.net/v1/getConsigneeInfo?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.getConsigneeInfo&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx

3.1.3、请求参数

3.1.4、请求示例

curl -X POST 'https://hufu.cn-north-1.jdcloud-api.netm/v1/getConsigneeInfo?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.getConsigneeInfo&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx' \
-H 'Content-Type: application/json' \
--data-raw '{"expressCode":"ZGYZZHDD","billCode":"983036200000"}'

3.1.5、返回参数

Data

3.1.6、响应示例

{
  "requestId": "c6ea14iet0se3hg2r5m5169qajr8rttn",
  "data": {
      "expressCode": "ZGYZZHDD",
      "billCode": "983036200000",
      "phone": "188****3290"
  }
}

3.2、jingdong.hufu.sms.logistics.sendMessageByBillCode

3.2.1、请求方式

POST

3.2.2、请求地址

https://hufu.cn-north-1.jdcloud-api.net/v1/sendMessageByBillCode?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.sendMessageByBillCode&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx

3.2.3、请求参数

3.2.4、请求示例

curl -X POST 'https://hufu.cn-north-1.jdcloud-api.net/v1/sendMessageByBillCode?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.sendMessageByBillCode&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx' \
-H 'Content-Type: application/json' \
--data-raw '{"appId":"yd-app-test0100","templateId":"3b2ef8546af94b2e83f566c5b100xxx","signId":"05bf88e6a1f84abb97c5fcc1d78xxxx","expressCode":"ZGYZZHDD","billCode":"983036200000","params":[123]}'

3.2.5、返回参数

Data

3.2.6、响应示例

{
  "requestId": "c6ea5qamcdmw0dw3h5pkjvpgdbpwu9p4",
  "data": {
      "expressCode": "ZGYZZHDD",
      "billCode": "983036200000",
      "phone": "188****3290",
      "ReqCode": "00",
      "ReqMsg": "提交成功",
      "ReqId": "211123161429108512100003"
  }
}

3.3、jingdong.hufu.sms.logistics.report

快递公司按照接口标准实现该接口

3.3.1、请求方式

POST

3.3.2、请求地址

[backendUrl]/v1/report?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.report&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx

注：backendUrl 为在虎符控制台配置得后端服务地址

3.3.3、请求参数

3.3.4、请求示例

curl -X POST '[backendUrl]/v1/report?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.report&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx' \
-H 'Content-Type: application/json' \
--data-raw '{"reqid":"211123161429108512100003","phone":"188****3290","time":"2021-11-23 16:14:37","status":"0","code":"DELIVRD","desc":"成功","expressCode":"ZGYZZHDD","billCode":"98303620000"}'

3.3.5、返回参数

Data

3.3.6、响应示例

{
  "requestId": "c6ea14iet0se3hg2r5m5169qajr8rttn",
  "data": {
      "status": true
  }
}

3.4、jingdong.hufu.sms.logistics.uplink

快递公司按照接口标准实现该接口

3.4.1、请求方式

POST

3.4.2、请求地址

[backendUrl]/v1/uplink?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.uplink&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx

注：backendUrl 为在虎符控制台配置得后端服务地址

3.4.3、请求参数

3.4.4、请求示例

curl -X POST 'https://hufu.cn-north-1.jdcloud-api.net/v1/uplink?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.uplink&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx' \
-H 'Content-Type: application/json' \
--data-raw '{"content":"very good","phone":"188****3290","time":"2021-11-19 13:53:53","subcode":"","sign":"测试"}'

3.4.5、返回参数

Data

3.4.6、响应示例

{
  "requestId": "c6ea14iet0se3hg2r5m5169qajr8rttn",
  "data": {
      "status": true
  }
}

3.5、jingdong.hufu.sms.logistics.existByExpressCodeAndBillCode

校验运单号是否属于京东平台（回传取件码前调用此接口校验）

注意：接入该接口需要新创建一个虎符应用，重新接入场景并申请上线（参考接入流程）

3.5.1、请求方式

POST

3.5.2、请求地址

https://hufu.cn-north-1.jdcloud-api.net/v1/existByExpressCodeAndBillCode?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.existByExpressCodeAndBillCode&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx

3.5.3、请求参数

3.5.4、请求示例

curl -X POST 'https://hufu.cn-north-1.jdcloud-api.netm/v1/existByExpressCodeAndBillCode?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.existByExpressCodeAndBillCode&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx' \
-H 'Content-Type: application/json' \
--data-raw '{"expressCode":"ZGYZZHDD","billCode":"983036200000"}'

3.5.5、返回参数

Data

3.5.6、响应示例

判断方法： data节点不为空且exist等于true表示运单是京东平台

{
  "requestId": "cja8n8dfs64p839d7q3ufmhh1kqwrfv8",
  "data": {
    "exist": true
  }
}

3.6、jingdong.hufu.sms.logistics.getEncryptConsigneeInfo

根据运单号查询收货人加密手机号（调用该接口需额外申请权限）

3.6.1、请求方式

POST

3.6.2、请求地址

https://hufu.cn-north-1.jdcloud-api.net/v1/getEncryptConsigneeInfo?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.getEncryptConsigneeInfo&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx

3.6.3、请求参数

3.6.4、请求示例

curl -X POST 'https://hufu.cn-north-1.jdcloud-api.netm/v1/getEncryptConsigneeInfo?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.getEncryptConsigneeInfo&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx' \
-H 'Content-Type: application/json' \
--data-raw '{"expressCode":"ZGYZZHDD","billCode":"983036200000"}'

3.6.5、返回参数

Data

3.6.6、响应示例

{
  "requestId":"cjaa23gr7rj5ikf5wgj4r7m2u0e6qe7n",
  "data":{
    "expressCode":"YTO",
    "billCode":"YT3750123123123",
    "phone":"gVP3TU6jS5gdrg+n/n7WnQ=="
  }
}

3.7、jingdong.hufu.sms.logistics.securityNumber.push

推送京东隐私面单AXE模式虚拟号主号码（用于校验隐私面单是否来自京东，其他场景不适用）

3.7.1、请求方式

POST

3.7.2、请求地址

[backendUrl]/v1/securityNumberPush?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.scurityNumber.push&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx

3.7.3、请求参数

3.7.4、请求示例

curl -X POST '[backendUrl]/v1/securityNumberPush?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.getEncryptConsigneeInfo&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx' \
-H 'Content-Type: application/json' \
--data-raw '{"version":0,"privacyNumberList":["mVPzdLWZq2iwVRpVDTpgGQ==","cRJcYRnIH/mlEUP24Y5UWA=="]}'

3.7.5、返回参数

Data

3.7.6、响应示例

{
  "requestId":"cjaa23gr7rj5ikf5wgj4r7m2u0e6qe7n",
  "data":{
    "status":true
  }
}

3.8、jingdong.hufu.sms.logistics.existByExpressCodeAndBillCodeAndMobileENC

根据运单号+加密手机号校验运单号是否为京东平台运单（仅用于终端查询场景，其他场景不适用）

3.8.1、请求方式

POST

3.8.2、请求地址

https://hufu.cn-north-1.jdcloud-api.net?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.existByExpressCodeAndBillCodeAndMobileENC&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx

3.8.3、请求参数

3.8.4、请求示例

curl -X POST 'https://hufu.cn-north-1.jdcloud-api.netm?app_key=xxx&customerId=xxx&method=jingdong.hufu.sms.logistics.existByExpressCodeAndBillCodeAndMobileENC&format=json&v=1.0&sign_method=md5&timestamp=2021-11-19 13:53:53&sign=xxx' \
-H 'Content-Type: application/json' \
--data-raw '{"expressCode":"ZGYZZHDD","billCode":"983036200000","mobileENC":"129F0CC6C5F5EE33251137A2C0C03214D1ADD9A13B50F49048A54227304164170"}'

3.8.5、返回参数

Data

3.8.6、响应示例

判断方法： data节点不为空且exist等于true表示运单是京东平台

{
  "requestId": "cja8n8dfs64p839d7q3ufmhh1kqwrfv8",
  "data": {
    "exist": true
  }
}

4、快递公司编码信息