Skip to content

Commit 40faa9a

Browse files
author
liqinglong
committed
修改文档
1 parent 39fd666 commit 40faa9a

2 files changed

Lines changed: 167 additions & 39 deletions

File tree

‎README.md‎

Lines changed: 161 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# 滴滴企业级开放接口SDK
1+
# 滴滴企业级开放接口SDK[`Java版本`]
22

33
## 概述
44

@@ -32,7 +32,7 @@
3232

3333
---
3434

35-
### Maven 仓库
35+
### 1、Maven 仓库
3636

3737
```xml
3838

@@ -44,6 +44,14 @@
4444
</dependency>
4545
```
4646

47+
### 2、手动下载
48+
49+
- 1、下载最新的源码
50+
- 2、使用Maven命令打包：`mvn clean install`
51+
- 3、将生成的jar包引入到项目中
52+
53+
---
54+
4755
## 快速使用
4856

4957
### 流程概述
@@ -55,17 +63,63 @@
5563
3. 设置IP白名单 [前3步参考：[接入前必读](https://opendocs.xiaojukeji.com/version2024/10957)]
5664
4. 调用API
5765

58-
### 使用示例 [以查询公司主体为例,更多示例请参考：`sample`module]
66+
---
67+
68+
### SDK配置参数说明(`com.xiaoju.open.sdk.didies.core.Config`)
69+
70+
| 配置项 | 配置方式 | 描述 |
71+
|-----------------------------|----------------------------------------|----------------------------------------------------------|
72+
| `clientId` | 必填 | 客户端 ID，用于身份认证。 |
73+
| `clientSecret` | 必填 | 客户端密钥，用于身份认证。 |
74+
| `signKey` | 必填 | 签名密钥，用于请求签名。 |
75+
| `baseUrl` | 可选，默认值：`https://api.es.xiaojukeji.com` | 接口请求的基础 URL。 |
76+
| `grantType` | 可选，默认值：`client_credentials` | OAuth 认证的授权类型，默认使用客户端凭证模式。 |
77+
| `unauthorizedRetryTimes` | 可选，默认值：`2` | 因 Token 失效导致接口请求失败时的重试次数。 |
78+
| `unauthorizedRetryInterval` | 可选，默认值：`1000`（毫秒） | Token 失效重试的时间间隔，默认1秒。 |
79+
| `httpTransport` | 可选，默认自动创建 `RestHttpTransport` 实例 | 自定义 HTTP 请求实现类，需实现 `IHttpTransport` 接口。未设置时使用默认实现。 |
80+
| `signMethod` | 可选，默认值：`MD5` | 签名方法，可选枚举值（如 `MD5`、`SHA256`，默认MD5）。 |
81+
| `enableHoldToken` | 可选，默认值：`true` | 是否开启自动获取并持有 Token（如未开启，需用自己管理token在每个接口中设置，推荐开启）。 |
82+
| `enableRequestLog` | 可选 | 是否开启请求日志打印。需配合 `logLevel` 使用。 |
83+
| `logLevel` | 可选 | 请求日志的打印级别（需开启 `enableRequestLog`），可选枚举如 `DEBUG`、`INFO` 。 |
84+
| `enableAES` | 可选，默认值：`false` | 是否启用 AES 加密（此加密为整体加密，开启整体加密时人员信息不需要额外加密）。 |
85+
| `aesKey` | 条件必填（当 `enableAES` 为 `true` 时需设置） | AES 加密使用的密钥。 |
86+
| `encryptType` | 可选，默认值：`NORMAL` | 加密类型。默认不加密（`NORMAL`），启用 AES 时可选择 `AES128` 或 `AES256` 。 |
87+
| `connectTimeout` | 可选，默认值：`3000`（毫秒） | 网络连接超时时间（单位由 `timeoutUnit` 决定）。 |
88+
| `callTimeOut` | 可选，默认值：`3000`（毫秒） | 接口调用超时时间（单位由 `timeoutUnit` 决定）。 |
89+
| `timeoutUnit` | 可选，默认值：`MILLISECONDS` | 超时时间单位（如 `MILLISECONDS`、`SECONDS` 等）。 |
90+
91+
---
92+
说明：
93+
94+
1. 必填项：`clientId`、`clientSecret`、`signKey` 必须通过代码手动设置（如 `setClientId("your-id")`）。
95+
2. 条件必填：`aesKey` 仅在启用 AES 加密（`enableAES=true`）时需设置。
96+
3. 默认行为：
97+
• `httpTransport` 未设置时，自动使用 `RestHttpTransport` 实现类。
98+
99+
• 接口整体加密默认关闭（`enableAES=false`），签名方法默认使用 `MD5`。
100+
101+
4. 超时配置：`connectTimeout` 和 `callTimeOut` 的单位由 `timeoutUnit` 统一控制，默认毫秒。
102+
5. 依赖关系：
103+
• `logLevel` 仅在 `enableRequestLog=true` 时生效。
104+
105+
• `encryptType` 的具体值需根据 `EncryptTypeEnum` 枚举定义选择（如 `NORMAL` 表示不加密）。
106+
107+
---
108+
109+
### 使用示例
110+
111+
1、以查询公司主体为例,更多示例请参考：`sample`module
59112

60113
```java
61114

62-
public class test {
115+
public class Test {
63116

64117
public static void main(String[] args) {
65118
Config config = Config.builder()
66119
.clientId("your_client_id")
67120
.clientSecret("your_client_secret")
68121
.signKey("your_sign_key")
122+
.signMethod(SignMethodEnum.MD5) // 默认使用MD5签名，可选SHA256签名，具体和对接人确认
69123
.build();
70124

71125
ApiClient client = new ApiClient(config);
@@ -92,48 +146,117 @@ public class test {
92146
}
93147
```
94148

95-
> 注意：
149+
2、使用整体加密
96150

97-
1. 请替换代码中的`clientId`、`clientSecret`和`signKey`为实际的值，以及替换实际入参中的`companyId`
98-
2. 所有用例代码均在`sample`module下
151+
```java
99152

100-
## SDK配置参数说明[`com.xiaoju.open.sdk.didies.core.Config`]
153+
public class EncryptTest {
101154

102-
| 配置项 | 配置方式 | 描述 |
103-
|-----------------------------|----------------------------------------|----------------------------------------------------------|
104-
| `clientId` | 必填 | 客户端 ID，用于身份认证。 |
105-
| `clientSecret` | 必填 | 客户端密钥，用于身份认证。 |
106-
| `signKey` | 必填 | 签名密钥，用于请求签名。 |
107-
| `baseUrl` | 可选，默认值：`https://api.es.xiaojukeji.com` | 接口请求的基础 URL。 |
108-
| `grantType` | 可选，默认值：`client_credentials` | OAuth 认证的授权类型，默认使用客户端凭证模式。 |
109-
| `unauthorizedRetryTimes` | 可选，默认值：`2` | 因 Token 失效导致接口请求失败时的重试次数。 |
110-
| `unauthorizedRetryInterval` | 可选，默认值：`1000`（毫秒） | Token 失效重试的时间间隔，默认1秒。 |
111-
| `httpTransport` | 可选，默认自动创建 `RestHttpTransport` 实例 | 自定义 HTTP 请求实现类，需实现 `IHttpTransport` 接口。未设置时使用默认实现。 |
112-
| `signMethod` | 可选，默认值：`MD5` | 签名方法，可选枚举值（如 `MD5`、`SHA256`，默认MD5）。 |
113-
| `enableHoldToken` | 可选，默认值：`true` | 是否开启自动获取并持有 Token（如未开启，需用自己管理token在每个接口中设置，推荐开启）。 |
114-
| `enableRequestLog` | 可选 | 是否开启请求日志打印。需配合 `logLevel` 使用。 |
115-
| `logLevel` | 可选 | 请求日志的打印级别（需开启 `enableRequestLog`），可选枚举如 `DEBUG`、`INFO` 。 |
116-
| `enableAES` | 可选，默认值：`false` | 是否启用 AES 加密（此加密为整体加密，开启整体加密时人员信息不需要额外加密）。 |
117-
| `aesKey` | 条件必填（当 `enableAES` 为 `true` 时需设置） | AES 加密使用的密钥。 |
118-
| `encryptType` | 可选，默认值：`NORMAL` | 加密类型。默认不加密（`NORMAL`），启用 AES 时可选择 `AES128` 或 `AES256` 。 |
119-
| `connectTimeout` | 可选，默认值：`3000`（毫秒） | 网络连接超时时间（单位由 `timeoutUnit` 决定）。 |
120-
| `callTimeOut` | 可选，默认值：`3000`（毫秒） | 接口调用超时时间（单位由 `timeoutUnit` 决定）。 |
121-
| `timeoutUnit` | 可选，默认值：`MILLISECONDS` | 超时时间单位（如 `MILLISECONDS`、`SECONDS` 等）。 |
155+
public static void main(String[] args) {
156+
Config config = Config.builder()
157+
.clientId("your_client_id")
158+
.clientSecret("your_client_secret")
159+
.signKey("your_sign_key")
160+
.enableAES(true) // 启用整体加密[默认为false]
161+
.aesKey("your_aes_key") // 设置AES密钥[enableAES为false的时候，该值无效]
162+
.encryptType(EncryptTypeEnum.AES128) // 设置加密方式[enableAES为false的时候，该值无效]
163+
.build();
122164

123-
说明：
165+
ApiClient client = new ApiClient(config);
166+
// 接口的调用不需要任何额外的操作，SDK会自动处理加密和解密
167+
getLegalEntityTest(client);
168+
}
124169

125-
1. 必填项：`clientId`、`clientSecret`、`signKey` 必须通过代码手动设置（如 `setClientId("your-id")`）。
126-
2. 条件必填：`aesKey` 仅在启用 AES 加密（`enableAES=true`）时需设置。
127-
3. 默认行为：
128-
• `httpTransport` 未设置时，自动使用 `RestHttpTransport` 实现类。
170+
/**
171+
* 公司主体查询
172+
* <p>
173+
* 说明： * 查询公司在滴滴侧的具体信息; * 通过获取的信息用于确认相关的配置信息，可以用于同步滴滴ES后台的信息; * 只返回有效的公司信息。不包含禁用和过期的公司主体信息。需要返回全部的，是不是需要重新封接口。
174+
*/
175+
public static void getLegalEntityTest(ApiClient client) throws Exception {
176+
GetLegalEntityRequest request = GetLegalEntityRequest.builder()
177+
.companyId("替换成自己的companyId")
178+
.legalEntityId("xxx")
179+
.build();
129180

130-
• 接口整体加密默认关闭（`enableAES=false`），签名方法默认使用 `MD5`。
181+
GetLegalEntityApiReply response = client.legalentity().v1().getLegalEntity(request);
182+
if (response != null) {
183+
System.out.println(JacksonUtils.toJson(response));
184+
}
185+
System.out.println("getAdjustBillDataResultTest end");
186+
}
187+
}
188+
```
131189

132-
4. 超时配置：`connectTimeout` 和 `callTimeOut` 的单位由 `timeoutUnit` 统一控制，默认毫秒。
133-
5. 依赖关系：
134-
• `logLevel` 仅在 `enableRequestLog=true` 时生效。
190+
3、更多示例
191+
192+
| 示例模块 | 示例代码路径 | 包含接口 | 接口地址 |
193+
|--------|---------------------------------|----------------------|-----------------------------------------------|
194+
| 接口认证 | sample/AuthSample.java | 接口认证(获取access_token) | /river/Auth/authorize |
195+
| 行后授权 | sample/AfterapprovalSample.java | 行后审批结果同步 | /river/AfterApproval/createPersonalReceipt |
196+
| | | 行后审批完订单查询个人付款单 | /river/AfterApproval/getPersonalReceiptOrder |
197+
| 审批对接 | sample/ApprovalSample.java | 创建申请单(已按业务拆分) | /river/Approval/create |
198+
| | | 修改申请单(已按业务拆分) | /river/Approval/update |
199+
| | | 取消申请单 | /river/Approval/cancel |
200+
| | | 查询审批单列表 | /river/Approval/getOrder |
201+
| | | 查询申请单详情 | /open-apis/v1/approval/detail |
202+
| | | 外部审批处理 | /river/Approval/pass |
203+
| 外部审批处理 | sample/OutapprovalSample.java | 外部通知审批单状态变更 | /river/OutApproval/Status |
204+
| 财税信息 | sample/BillSample.java | 账单列表 | /river/Bill/get |
205+
| | | 已出账单(已按业务类型拆分) | /river/Bill/detail |
206+
| | | 未出账单(已按业务类型拆分) | /river/Bill/getNotGeneratedBillDetail |
207+
| | | 网约车，出租车交易明细 | /river/Bill/transactionDetail |
208+
| | | 账单汇总查询-商旅、网约车、出租车 | /river/Bill/summary |
209+
| | | 网约车、商旅账单树查询 | /river/Bill/getBillStructure |
210+
| | | 商旅、网约车账单确认 | /river/Bill/confirm |
211+
| | | 调账提交 | /river/Bill/adjustBillData |
212+
| | | 调账结果查询 | /river/Bill/queryAdjustBillDataResult |
213+
| 部门或项目 | sample/BudgetcenterSample.java | 部门或项目查询 | /river/BudgetCenter/get |
214+
| | | 部门或项目新增 | /river/BudgetCenter/add |
215+
| | | 部门或项目修改 | /river/BudgetCenter/edit |
216+
| | | 部门或项目停用 | /river/BudgetCenter/del |
217+
| 城市 | sample/CitySample.java | 国家查询(全量获取国际ID) | /river/DemeterAres/Country/index |
218+
| | | 全量开城城市列表查询 | /open-apis/v1/city/list |
219+
| 地点 | sample/WorkspaceSample.java | 地点新增 | /open-apis/v1/workplace/create |
220+
| | | 地点删除 | /open-apis/v1/workplace/del |
221+
| | | 地点修改 | /open-apis/v1/workplace/update |
222+
| 外部出行人 | sample/TravelerSample.java | 外部出行人新增 | /open-apis/v1/traveler/create |
223+
| | | 外部出行人修改 | /open-apis/v1/traveler/update |
224+
| | | 外部出行人删除 | /open-apis/v1/traveler/del |
225+
| 角色 | sample/RoleSample.java | 角色查询 | /river/Role/get |
226+
| 制度 | sample/RegulationSample.java | 制度列表 | /river/Regulation/get |
227+
| | | 制度详情 | /river/Regulation/detail |
228+
| 职级 | sample/RankSample.java | 职级新增 | /open-apis/v1/rank/create |
229+
| | | 职级更新 | /open-apis/v1/rank/update |
230+
| | | 职级删除 | /open-apis/v1/rank/del |
231+
| | | 职级查询 | /river/Rank/getRanks |
232+
| 订单 | sample/OrderSample.java | 订单号列表查询 | /open-apis/v1/order/list |
233+
| | | 机票订单详情查询 | /api-gateway/g/flight/orderDetail |
234+
| | | 酒店订单详情查询 | /api-gateway/g/hotel/orderDetail |
235+
| | | 火车票订单详情查询 | /api-gateway/g/train/orderDetail |
236+
| | | 用车订单详情查询 | /river/Order/detail |
237+
| | | 用车列表 | /river/Order/get |
238+
| | | 机票预估价获取 | /api-gateway/g/flight/info/estimatePrice |
239+
| | | 火车票直达列表 | /api-gateway/train/queryLeftTicket |
240+
| | | 火车票中转车次列表 | /api-gateway/g/train/transfer/queryLeftTicket |
241+
| 用户 | sample/MemberSample.java | 用户查询~员工列表（批量查询） | /river/Member/get |
242+
| | | 用户查询~员工明细 | /river/Member/detail |
243+
| | | 员工限额查询 | /river/Member/getQuota |
244+
| | | 用户新增 | /river/Member/single |
245+
| | | 用户修改 | /river/Member/edit |
246+
| | | 用户删除 | /river/Member/del |
247+
| 单点页面 | sample/LoginSample.java | 单点请求 | /river/Login/getLoginEncryptStr |
248+
| 公司主体 | sample/LegalentitySample.java | 公司主体查询 | /river/LegalEntity/get |
249+
| | | 公司主体新增 | /river/LegalEntity/add |
250+
| | | 公司主体修改 | /river/LegalEntity/edit |
251+
| | | 公司主体停用 | /river/LegalEntity/del |
252+
| 拓展 | sample/ExtendSample.java | 拓展信息批量创建 | /river/ExtendInfo/BatchSync |
253+
| | | 档案状态处理 | /river/ExtendInfo/Status |
254+
| | | 拓展信息查询 | /river/ExtendInfo/Get |
135255

136-
• `encryptType` 的具体值需根据 `EncryptTypeEnum` 枚举定义选择（如 `NORMAL` 表示不加密）。
256+
---
257+
`📢注意`： 请替换代码中的`clientId`、`clientSecret`和`signKey`为实际的值，以及替换实际入参中的`companyId`
258+
259+
---
137260

138261
## 特殊说明
139262

0 commit comments

Comments
 (0)