zeyi / open-doc

Download as
Browse Code »

Commit 797a71080c783b1ae5c460d507f2a3dcd8fec3d6

Authored by 王富国
1 parent 11da0a5c
Exists in master

init: 初始化接口

Showing 2 changed files with 206 additions and 2 deletions   Show diff stats
guide/notice/则一后端开发注意事项.md
  Diff comments   View file @797a710
... ... @@ -49,7 +49,7 @@ SQL写完一定è¦åœ¨ç”Ÿäº§çŽ¯å¢ƒæ‰§è¡Œä¸€ä¸‹ï¼Œçœ‹ä¸‹æ‰§è¡Œè®¡åˆ’有没有走ç´
49 49  
50 50 ##### 命å规范â­â­â­â­
51 51  
52   -ç±»å需è¦ä½¿ç”¨å¤§é©¼å³°å‘½å法(UpperCamelCase) 风格
  52 +ç±»å一般为åè¯æˆ–åè¯ç»„åˆï¼Œéœ€è¦ä½¿ç”¨å¤§é©¼å³°å‘½å法(UpperCamelCase) 风格
53 53  
54 54 方法åã€å‚æ•°åã€æˆå‘˜å˜é‡ã€å±€éƒ¨å˜é‡éœ€è¦ä½¿ç”¨å°é©¼å³°å‘½å法(lowerCamelCase)
55 55  
... ... @@ -196,7 +196,7 @@ public Response<Void> addDriverVehicleLicenseV1(@RequestBody @Validated DriverVe
196 196 #### git
197 197  
198 198 分支：开å‘分支，测试分支，上线分支，master
199   -å¼€å‘分支: å¼€å‘功能时è¦åˆ›å»ºè‡ªå·±çš„å¼€å‘分支，开å‘分支从master创建分支
  199 +å¼€å‘分支: å¼€å‘功能时è¦åˆ›å»ºè‡ªå·±çš„å¼€å‘分支，开å‘分支从master创建分支，一般一个需求对应一个分支
200 200 测试分支: 测试环境部署的分支，功能开å‘完通过å•å…ƒæµ‹è¯•åŽå°±å¯ä»¥æŠŠä»£ç åˆå¹¶åˆ°æµ‹è¯•åˆ†æ”¯è¿›è¡Œæµ‹è¯•
201 201 上线分支: æ¯å‘¨ä¼šæœ‰ä¸€ä¸ªä¸Šçº¿ç‰ˆæœ¬ï¼Œä¸Šçº¿ä¹‹å‰éœ€è¦æŠŠè¦ä¸Šçº¿çš„代ç åˆå¹¶åˆ°ä¸Šçº¿åˆ†æ”¯ï¼Œä»Žè‡ªå·±çš„å¼€å‘分支åˆå¹¶åˆ°ä¸Šçº¿åˆ†æ”¯
202 202 master: 生产环境部署分支，由上线部署人员从上线分支åˆå¹¶åˆ°master
... ...
order/truck/zsh/2022121401/订单接口.md 0 → 100644
  Diff comments   View file @797a710
... ... @@ -0,0 +1,204 @@
  1 +[toc]
  2 +
  3 +# 订单对接API
  4 +
  5 +则一提供了不同规范的API，调用服务端API前，需了解开发前须知及调用流程。本文提供了调用则一服务端API示例，供开发者参考。
  6 +
  7 +## 白名单
  8 +
  9 +则一服务端API接口访问有IP白名单限制，需要接口调用方提供调用API的服务器IP地址。
  10 +
  11 +## 数据加签
  12 +
  13 +采用md5(32位小写)算法生成签名
  14 +appKey(则一提供) + appSecret(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(请求数据)
  15 +
  16 +## 数据加密
  17 +
  18 +数据加密采用AES算法
  19 +加密模式： CBC
  20 +填充方式：PKCS5Padding
  21 +偏移量：iv(则一提供)
  22 +加密内容：appKey(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(加密数据)
  23 +密钥： appSecret(则一提供)
  24 +输出：base64
  25 +字符集：utf-8
  26 +注：无敏感数据则无需加密
  27 +
  28 +## 获取访问凭证
  29 +
  30 +### 概述
  31 +
  32 +调用则一服务API时，都需要先获取对应权限类型的访问凭证accessToken。访问凭证（accessToken）是由则一权限系统颁发的，用来校验调用者的身份信息，确保调用者具有要执行的操作的权限。
  33 +**说明**： 在使用accessToken时，请注意：
  34 +
  35 +* accessToken的有效期默认为30天，有效期内重复获取会返回相同结果，过期后获取会返回新的accessToken。
  36 +* 开发者需要缓存accessToken，用于后续接口的调用。不能频繁调用获取accessToken接口，否则会受到频率拦截。
  37 +* 当调用业务API时，如果返回状态码为401，则说明accessToken不正确或已过期，这时需要重新获取accessToken后再调用对应的API。
  38 +
  39 +### 接口信息
  40 +
  41 +#### 请求方式：
  42 +
  43 +post
  44 +
  45 +#### 请求地址：
  46 +
  47 +* 生产：https://gw.shjiuze.cn/auth-service-api/login/password
  48 +* 测试：https://test.shjiuze.cn/auth-service-api/login/password
  49 +
  50 +#### Body参数
  51 +
  52 +| 名称 | 类型 | 必填 | 示例值 | 描述 |
  53 +| -------- | ------ | ---- | ----------- | ---------------- |
  54 +| username | String | 是 | zhangsan | 用户名，则一提供 |
  55 +| password | String | 是 | password123 | 密码，则一提供 |
  56 +
  57 +#### 返回参数
  58 +
  59 +| 名称 | 类型 | 示例值 | 描述 |
  60 +| ------------------------------ | ---------- | -------------------------------- | -------------------------------------------------- |
  61 +| success | boolean | true | 成功标识: true 成功，false 失败 |
  62 +| businessException | boolean | false | 业务异常标识: true 业务异常，false 正常 |
  63 +| errorCode | String | 200 | 错误码: 200 业务异常，500 系统异常， 空表示无错误 |
  64 +| message | String | 订单号不能为空 | 错误信息，无错误则返回空 |
  65 +| result | ZYTokenDto | | accessToken结果数据 |
  66 +|     accessToken | String | 000626f15b4b41bba6fe56216a5d2f73 | accessToken |
  67 +|     expiresIn | Integer | 2060 | 有效期限单位秒，accessToken在2060秒后过期 |
  68 +|     tokenType | String | bearer | token类型 |
  69 +
  70 +#### 请求示例
  71 +
  72 +##### Http方式
  73 +
  74 +```http
  75 +POST /auth-service-api/login/password HTTP/1.1
  76 +Host:test.shjiuze.cn
  77 +Content-Type:application/json
  78 +
  79 +{
  80 + "username" : "zeyi",
  81 + "password" : "test1111"
  82 +}
  83 +```
  84 +
  85 +##### Java-sdk方式
  86 +
  87 +##### [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar)
  88 +
  89 +```java
  90 +public class Sample {
  91 + public static void main(String[] args_) {
  92 + String appKey = "appkey";
  93 + String appSecret = "appSecret";
  94 + ZYClient zyClient = new ZYClient(appKey, appSecret);
  95 + ZYTokenRequestDto zyTokenRequest = new ZYTokenRequestDto();
  96 + zyTokenRequest.setUsername("zeyi");
  97 + zyTokenRequest.setPassword("test1111");
  98 + String body = gson.toJson(zyTokenRequest);
  99 + HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + Constants.TOKEN_PATH, body);
  100 + if(httpResponseData == null) {
  101 + throw new TokenException("则一Token请求失败,返回为空!");
  102 + }
  103 + ZYResponse<ZYTokenDto> zyResponse = gson.fromJson(httpResponseData.getBody(), new TypeToken<ZYResponse<ZYTokenDto>>(){}.getType());
  104 + if(!Boolean.TRUE.equals(zyResponse.isSuccess())) {
  105 + throw new TokenException("则一Token请求返回失败!" + zyResponse.getMessage());
  106 + }
  107 + if(zyResponse.getResult() == null) {
  108 + throw new TokenException("则一Token请求返回失败,返回结果为空!" + zyResponse.getMessage());
  109 + }
  110 + if(StringUtils.isBlank(zyResponse.getResult().getAccessToken())) {
  111 + throw new TokenException("则一Token请求返回数据异常,AccessToken为空!" + zyResponse.getMessage());
  112 + }
  113 + // 结果 zyResponse.getResult();
  114 + }
  115 +}
  116 +```
  117 +
  118 +#### 返回示例
  119 +
  120 +```json
  121 +{
  122 + "success": true,
  123 + "businessException": false,
  124 + "errorCode": null,
  125 + "message": null,
  126 + "result": {
  127 + "accessToken": "64d7f367-609b-4f7d-a84d-a3d2a0b5ad85",
  128 + "expiresIn": 602105,
  129 + "tokenType": "bearer"
  130 + }
  131 +}
  132 +```
  133 +
  134 +## 委托单集成接口
  135 +
  136 +### 简要描述
  137 +
  138 +委托单集成接口
  139 +
  140 +### 请求URL
  141 +
  142 +· 测试环境：https://test.shjiuze.cn/oms-service-api/zshOrder/add
  143 +
  144 +· 生产环境：https://gw.shjiuze.cn/oms-service-api/zshOrder/add
  145 +
  146 +### 请求方式
  147 +
  148 +POST
  149 +
  150 +### Headers参数
  151 +
  152 +| 名称 | 类型 | 必填 | 示例值 | 描述 |
  153 +| ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ |
  154 +| Authorization | String | 是&nbsp;&nbsp;&nbsp;&nbsp; | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 |
  155 +| appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 |
  156 +| timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 |
  157 +| nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 |
  158 +| sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 |
  159 +
  160 +### Body参数
  161 +
  162 +参数Json.
  163 +
  164 +### 返回结果正常示例
  165 +
  166 + { "success": true, "businessException": false}
  167 +
  168 +### 返回结果异常示例
  169 +
  170 + { "success": false, "businessException": true, "errorCode": "500", "message": "XXX异常!"}
  171 +
  172 +### 请求示例
  173 +
  174 +#### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar)
  175 +
  176 +```java
  177 +public class Sample {
  178 + public static void main(String[] args_) {
  179 + String appKey = "appkey";
  180 + String appSecret = "appSecret";
  181 + String jsonData = "订单下单Body参数JSON数据";
  182 + ZYClient zyClient = new ZYClient(appKey, appSecret);
  183 + HttpResponseData httpResponseData =
  184 +zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/zshOrder/add", "accessToken", jsonData);
  185 + if(httpResponseData == null) {
  186 + throw new BusinessException("则一请求失败,返回结果为空!");
  187 + }
  188 + if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) {
  189 + //重新获取token再次请求
  190 + httpResponseData = zyClient.doPost(Constants.TEST_HOST +
  191 + "/oms-service-api/zshOrder/add", "accessToken", jsonData);
  192 + }
  193 + }
  194 +}
  195 +```
  196 +
  197 +
  198 +
  199 +------------------------------------------------------------------------------------------
  200 +
  201 +## 2022-05-05更新日志
  202 +
  203 +1. 接口初始化
  204 +
... ...