116f6bb0
 王彪总
feat(garden): 添加开...
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
|
# UrbanOps 开放 API 对接接口文档
> **版本**: v1.0
> **更新日期**: 2026-06-11
> **适用对象**: 第三方系统对接开发人员
> **鉴权方式**: HMAC-SHA256 API 签名
---
## 目录
1. [概述](#1-概述)
2. [签名鉴权机制](#2-签名鉴权机制)
3. [通用规范](#3-通用规范)
4. [接口 1：人员查询](#4-接口-1人员查询)
5. [接口 2：班组查询](#5-接口-2班组查询)
6. [接口 3：考勤查询](#6-接口-3考勤查询)
7. [接口 4：工单查询](#7-接口-4工单查询)
8. [接口 5：物料查询](#8-接口-5物料查询)
9. [接口 6：全量工单统计](#9-接口-6全量工单统计)
10. [错误码说明](#10-错误码说明)
11. [附录：客户端签名代码示例](#11-附录客户端签名代码示例)
---
## 1. 概述
### 1.1 基本信息
| 项目 | 说明 |
|------|------|
| 接口协议 | HTTPS |
| 接口地址 | `https://{host}/open-api/` |
| 鉴权方式 | HMAC-SHA256 API 签名（详见第2节） |
| 响应格式 | JSON |
| 字符编码 | UTF-8 |
### 1.2 接口列表
| # | 接口名称 | 路径 | 方法 | 说明 |
|---|---------|------|------|------|
| 1 | 人员查询 | `/open-api/staff/query` | GET | 获取人员档案，支持按部门筛选 |
| 2 | 班组查询 | `/open-api/teams/query` | GET | 获取班组信息，含班组长和人员数量 |
| 3 | 考勤查询 | `/open-api/attendance/query` | GET | 获取考勤打卡数据 |
| 4 | 工单查询 | `/open-api/tasks/query` | GET | 获取工单全生命周期数据 |
| 5 | 物料查询 | `/open-api/materials/query` | GET | 获取物料消耗与照片数据 |
| 6 | 全量工单统计 | `/open-api/full-order-statistics/query` | GET | 获取公司/班组工单/巡查/养护完成数量 |
### 1.3 接入前提
接入前需向 UrbanOps 平台申请以下凭证（由运维人员配置到 Redis）：
| 参数 | 说明 |
|------|------|
| `appId` | 应用唯一标识（由平台分配） |
| `appSecret` | 应用密钥（妥善保管，不可泄露） |
---
## 2. 签名鉴权机制
### 2.1 签名参数
每个请求必须携带以下 **4 个请求头**：
| 请求头 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `appId` | String | ✅ | 平台分配的应用 ID |
| `timestamp` | String | ✅ | 当前 Unix 时间戳（**毫秒**），与服务器时间误差不能超过 60 秒 |
| `nonce` | String | ✅ | 随机字符串，**长度 ≥ 10**，每次请求必须不同（防重放） |
| `sign` | String | ✅ | 签名字符串（SHA256 计算结果，**小写十六进制**） |
### 2.2 签名算法
#### 签名字符串构造规则
```
签名字符串 = queryParams(按key字母序排列的value拼接)
+ headerParams(按key字母序排列的value拼接)
+ appSecret
```
**具体步骤：**
1. **排序 Query 参数值**：将 URL 中所有 query 参数按 key 字母升序排列，拼接所有 value
2. **拼接 Header 参数值**：按 key 字母升序（即 `appId` → `nonce` → `timestamp`），依次拼接它们的值
3. **追加 appSecret**：在最后拼接 `appSecret`
4. **计算 SHA256**：对上述完整字符串计算 SHA256 哈希，转为**小写十六进制**字符串
#### 签名公式
```
sign = SHA256(
sortedQueryParamValues
+ appId值 + nonce值 + timestamp值
+ appSecret
)
```
> **注意**：GET 请求无 body，body 部分为空字符串（不参与签名）。
### 2.3 签名示例
假设：
- `appId` = `my_app_001`
- `appSecret` = `abc123xyz`
- 请求 URL：`/open-api/staff/query?deptId=100`
**步骤拆解：**
```
queryParams(sorted by key):
deptId=100
→ values = "100"
headerParams(sorted by key):
appId=my_app_001, nonce=a1b2c3d4e5f6, timestamp=1749696000000
→ values = "my_app_001" + "a1b2c3d4e5f6" + "1749696000000"
signStr = "100" + "my_app_001" + "a1b2c3d4e5f6" + "1749696000000" + "abc123xyz"
sign = SHA256(signStr)
```
### 2.4 签名校验规则
| 校验项 | 规则 | 失败返回 |
|--------|------|----------|
| appId 非空 | 必须传递 | `400 签名不正确` |
| timestamp 时效 | `|serverTime - timestamp| ≤ 60s` | `400 签名不正确` |
| nonce 长度 | `len(nonce) ≥ 10` | `400 签名不正确` |
| sign 非空 | 必须传递 | `400 签名不正确` |
| 签名比对 | `serverSign == clientSign` | `400 签名不正确` |
| nonce 防重放 | 同一 appId + nonce 组合只能使用一次 | `900 存在重复请求` |
---
## 3. 通用规范
### 3.1 通用响应格式
```json
{
"code": 0,
"msg": "成功",
"data": [ ... ]
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | Integer | `0` 表示成功，非 `0` 表示失败 |
| `msg` | String | 提示信息 |
| `data` | Array | 业务数据列表（根据查询条件返回所有匹配记录） |
### 3.2 日期时间格式
所有日期时间字段统一使用格式：`yyyy-MM-dd HH:mm:ss`
示例：`2026-06-11 09:00:00`
---
## 4. 接口 1：人员查询
### 4.1 基本信息
| 项目 | 说明 |
|------|------|
| 路径 | `/open-api/staff/query` |
| 方法 | `GET` |
| 说明 | 获取人员基础档案信息，支持按部门、姓名、手机号等条件筛选 |
### 4.2 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | String | 否 | 姓名，模糊匹配 |
| `mobile` | String | 否 | 手机号，模糊匹配 |
| `deptId` | Long | 否 | 部门ID，精确匹配 |
| `status` | Integer | 否 | 状态：0=启用，1=禁用 |
| `busiLine` | String | 否 | 业务线：yl=园林，wy=物业，sz=市政 |
### 4.3 响应字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 人员ID |
| `username` | String | 用户名 |
| `nickname` | String | 姓名 |
| `mobile` | String | 手机号 |
| `deptId` | Long | 部门ID |
| `deptName` | String | 部门名称（如"养护一班"） |
| `postIds` | Array\<Long\> | 岗位ID列表 |
| `postNames` | String | 岗位名称（逗号分隔，如"班组长,技术员"） |
| `busiLine` | String | 业务线 |
| `status` | Integer | 状态（0=启用，1=禁用） |
| `cardNumber` | String | 工卡号（设备编号，用于考勤打卡） |
| `isInner` | Integer | 是否内部人员（1=内部，2=外部） |
| `createTime` | String | 入职日期（格式：yyyy-MM-dd HH:mm:ss） |
### 4.4 请求示例
```bash
curl -X GET "https://test.jichengshanshui.com.cn:28302/open-api/staff/query?deptId=100" \
-H "appId: my_app_001" \
-H "timestamp: 1749696000000" \
-H "nonce: a1b2c3d4e5f6g7h8" \
-H "sign: 3a5f8c9e2b1d4f6a8c0e2b4d6f8a0c2e4b6d8f0a"
```
### 4.5 响应示例
```json
{
"code": 0,
"msg": "成功",
"data": [
{
"id": 1001,
"username": "zhangsan",
"nickname": "张三",
"mobile": "13800138001",
"deptId": 100,
"deptName": "养护一班",
"postIds": [10, 20],
"postNames": "班组长,技术员",
"busiLine": "yl",
"status": 0,
"cardNumber": "DEV001",
"isInner": 1,
"createTime": "2024-01-15 00:00:00"
}
],
"total": 150
}
```
---
## 5. 接口 2：班组查询
### 5.1 基本信息
| 项目 | 说明 |
|------|------|
| 路径 | `/open-api/teams/query` |
| 方法 | `GET` |
| 说明 | 获取组织架构班组信息，含班组长、所属养护所、人员数量 |
### 5.2 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | String | 否 | 班组名称，模糊匹配 |
| `parentId` | Long | 否 | 父部门ID（上级组织），精确匹配 |
| `status` | Integer | 否 | 状态：0=启用，1=禁用 |
### 5.3 响应字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 班组ID |
| `name` | String | 班组名称 |
| `parentId` | Long | 父部门ID |
| `parentName` | String | 父部门名称（所属养护所） |
| `leaderUserId` | Long | 班组长人员ID（Staff.id） |
| `leaderUserName` | String | 班组长姓名 |
| `memberCount` | Long | 人员数量 |
| `sort` | Integer | 排序 |
| `status` | Integer | 状态（0=启用，1=禁用） |
### 5.4 请求示例
```bash
curl -X GET "https://test.jichengshanshui.com.cn:28302/open-api/teams/query" \
-H "appId: my_app_001" \
-H "timestamp: 1749696000000" \
-H "nonce: b2c3d4e5f6g7h8i9" \
-H "sign: ..."
```
### 5.5 响应示例
```json
{
"code": 0,
"msg": "成功",
"data": [
{
"id": 100,
"name": "养护一班",
"parentId": 1,
"parentName": "蓟城山水集团",
"leaderUserId": 1001,
"leaderUserName": "张三",
"memberCount": 15,
"sort": 1,
"status": 0
}
],
"total": 12
}
}
```
---
## 6. 接口 3：考勤查询
### 6.1 基本信息
| 项目 | 说明 |
|------|------|
| 路径 | `/open-api/attendance/query` |
| 方法 | `GET` |
| 说明 | 获取电子围栏打卡与位置数据，支持按班组、人员、时间范围筛选 |
### 6.2 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `userId` | Long | 否 | 人员ID，精确匹配 |
| `deptId` | Long | 否 | 部门ID（班组），精确匹配 |
| `busiLine` | String | 否 | 业务线 |
| `punchType` | String | 否 | 打卡类型（上班/下班） |
| `startTime` | String | 否 | 开始时间（格式：yyyy-MM-dd HH:mm:ss） |
| `endTime` | String | 否 | 结束时间（格式：yyyy-MM-dd HH:mm:ss） |
### 6.3 响应字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Integer | 记录ID |
| `deviceCode` | String | 设备编码 |
| `deviceName` | String | 设备名称 |
| `punchType` | String | 打卡类型 |
| `userId` | Long | 人员ID |
| `nickname` | String | 人员姓名 |
| `deptId` | Long | 部门ID |
| `deptName` | String | 部门名称 |
| `address` | String | 打卡地址 |
| `latGcj02` | BigDecimal | 高德纬度（GCJ-02坐标系） |
| `lngGcj02` | BigDecimal | 高德经度（GCJ-02坐标系） |
| `lat` | BigDecimal | WGS84纬度 |
| `lng` | BigDecimal | WGS84经度 |
| `createTime` | String | 打卡时间 |
> **注意**：当前版本暂不支持"轨迹点集""是否佩戴工卡""记录仪状态"字段（数据库无对应存储）。待业务系统确认后将补充。
### 6.4 响应示例
```json
{
"code": 0,
"msg": "成功",
"data": [
{
"id": 1,
"deviceCode": "DEV001",
"deviceName": "打卡机01",
"punchType": "上班",
"userId": 1001,
"nickname": "张三",
"deptId": 100,
"deptName": "养护一班",
"address": "北京市西城区xx路xx号",
"latGcj02": 39.9042,
"lngGcj02": 116.4074,
"lat": 39.9010,
"lng": 116.4030,
"createTime": "2026-06-11 08:30:00"
}
],
"total": 320
}
}
```
---
## 7. 接口 4：工单查询
### 7.1 基本信息
| 项目 | 说明 |
|------|------|
| 路径 | `/open-api/tasks/query` |
| 方法 | `GET` |
| 说明 | 获取工单全生命周期数据，含发布时间、状态、接单渠道、共同处理人 |
### 7.2 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `orderNo` | String | 否 | 工单号，模糊匹配 |
| `orderName` | String | 否 | 工单名称，模糊匹配 |
| `busiLine` | String | 否 | 业务线 |
| `status` | Integer | 否 | 审批状态 |
| `buzStatus` | String | 否 | 业务状态 |
| `workerId` | Long | 否 | 接单人ID |
| `startDate` | String | 否 | 发布时间起始（yyyy-MM-dd HH:mm:ss） |
| `endDate` | String | 否 | 发布时间截止（yyyy-MM-dd HH:mm:ss） |
### 7.3 响应字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 工单ID |
| `orderNo` | String | 工单号 |
| `orderName` | String | 工单名称 |
| `orderType` | String | 工单类型：Q=快速，C=普通，O=其他 |
| `busiLine` | String | 业务线 |
| `commitDate` | String | 发布时间（工单派发时间） |
| `finishDate` | String | 完成时间 |
| `userId` | Long | 发布人ID |
| `userName` | String | 发布人姓名 |
| `workerId` | Long | 接单人ID |
| `workerName` | String | 接单人姓名 |
| `coHandlers` | Array\<String\> | 共同处理人姓名列表 |
| `woSourceName` | String | 接单渠道（小程序/人工派单等） |
| `status` | Integer | 审批状态 |
| `buzStatus` | String | 业务状态 |
| `remark` | String | 备注 |
| `photos` | Array\<PhotoVO\> | 工单附件照片 |
**PhotoVO 结构：**
| 字段 | 类型 | 说明 |
|------|------|------|
| `busiType` | String | 业务类型：`01`=问题照片，`02`=处理中，`03`=完成 |
| `fileName` | String | 文件名 |
| `url` | String | 文件URL |
### 7.4 响应示例
```json
{
"code": 0,
"msg": "成功",
"data": [
{
"id": 5001,
"orderNo": "WO202606110001",
"orderName": "树木修剪",
"orderType": "C",
"busiLine": "yl",
"commitDate": "2026-06-11 09:00:00",
"finishDate": null,
"userId": 1,
"userName": "管理员",
"workerId": 1001,
"workerName": "张三",
"coHandlers": ["李四", "王五"],
"woSourceName": "小程序",
"status": 1,
"buzStatus": "processing",
"remark": "紧急处理",
"photos": [
{
"busiType": "01",
"fileName": "problem.jpg",
"url": "https://xxx.com/file/abc.jpg"
}
]
}
],
"total": 85
}
}
```
---
## 8. 接口 5：物料查询
### 8.1 基本信息
| 项目 | 说明 |
|------|------|
| 路径 | `/open-api/materials/query` |
| 方法 | `GET` |
| 说明 | 获取物料消耗记录与人机材照片数据，支持按工单筛选 |
### 8.2 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `orderNo` | String | 否 | 工单号，精确匹配 |
| `classifyName` | String | 否 | 物料分类名，模糊匹配 |
| `typeName` | String | 否 | 物料类型名，模糊匹配 |
| `userId` | Long | 否 | 使用人ID |
| `startDate` | String | 否 | 开始时间（yyyy-MM-dd HH:mm:ss） |
| `endDate` | String | 否 | 结束时间（yyyy-MM-dd HH:mm:ss） |
### 8.3 响应字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 记录ID |
| `orderNo` | String | 关联工单号 |
| `materialName` | String | 物料名称 |
| `specifications` | String | 规格 |
| `userCount` | Long | 使用数量 |
| `unitName` | String | 单位 |
| `classifyName` | String | 物料分类 |
| `typeName` | String | 物料类型 |
| `typeDetailName` | String | 物料明细类型 |
| `userId` | Long | 使用人ID |
| `userName` | String | 使用人姓名 |
| `source` | Integer | 来源：1=工单，2=巡检，3=养护 |
| `createTime` | String | 上传时间 |
| `photos` | Array\<PhotoVO\> | 人机材照片（结构同工单接口） |
### 8.4 响应示例
```json
{
"code": 0,
"msg": "成功",
"data": [
{
"id": 3001,
"orderNo": "WO202606110001",
"materialName": "高效氯氰菊酯",
"specifications": "500ml/瓶",
"userCount": 5,
"unitName": "瓶",
"classifyName": "药品",
"typeName": "杀虫剂",
"typeDetailName": "有机磷",
"userId": 1001,
"userName": "张三",
"source": 1,
"createTime": "2026-06-11 14:30:00",
"photos": [
{
"busiType": "02",
"fileName": "material.jpg",
"url": "https://xxx.com/file/def.jpg"
}
]
}
],
"total": 45
}
}
```
---
## 9. 接口 6：全量工单统计
### 9.1 基本信息
| 项目 | 说明 |
|------|------|
| 路径 | `/open-api/full-order-statistics/query` |
| 方法 | `GET` |
| 说明 | 获取各公司/班组在一段时间内实际完成的工单数量、巡查记录数量、养护记录数量 |
### 9.2 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `companyId` | Long | 否 | 公司/班组ID，精确匹配 |
| `companyName` | String | 否 | 公司/班组名称，模糊匹配 |
| `type` | Integer | 否 | 类型：1=按公司，2=按班组 |
| `startDate` | String | 否 | 统计开始日期（格式：yyyy-MM-dd，返回开始日期>=该值的记录） |
| `endDate` | String | 否 | 统计结束日期（格式：yyyy-MM-dd，返回结束日期<=该值的记录） |
### 9.3 响应字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 记录ID |
| `companyId` | Long | 公司/班组ID |
| `companyName` | String | 公司/班组名称 |
| `type` | Integer | 类型：1=按公司，2=按班组 |
| `startDate` | String | 统计开始日期 |
| `endDate` | String | 统计结束日期 |
| `workOrderCount` | Integer | 工单完成数量 |
| `inspectionCount` | Integer | 巡查记录数量 |
| `maintenanceCount` | Integer | 养护记录数量 |
| `remark` | String | 备注 |
| `createTime` | String | 创建时间 |
### 9.4 请求示例
```bash
curl -X GET "https://test.jichengshanshui.com.cn:28302/open-api/full-order-statistics/query?type=1&startDate=2026-06-01&endDate=2026-06-30" \
-H "appId: my_app_001" \
-H "timestamp: 1749696000000" \
-H "nonce: f6g7h8i9j0k1l2m3" \
-H "sign: ..."
```
### 9.5 响应示例
```json
{
"code": 0,
"msg": "成功",
"data": [
{
"id": 1,
"companyId": 100,
"companyName": "养护一班",
"type": 1,
"startDate": "2026-06-01",
"endDate": "2026-06-30",
"workOrderCount": 85,
"inspectionCount": 120,
"maintenanceCount": 60,
"remark": "二季度统计",
"createTime": "2026-06-11 10:00:00"
}
]
}
```
---
## 10. 错误码说明
### 10.1 签名相关错误
### 10.2 业务相关错误
| code | msg | 说明 |
|------|-----|------|
| 400 | 签名不正确 | 签名验证失败（appId不存在/timestamp超时/nonce长度不足/签名不匹配） |
| 900 | 存在重复请求 | nonce 已被使用（重放攻击检测） |
### 10.3 通用错误
| code | msg | 说明 |
|------|-----|------|
| 1-100-020-001 | 人员查询失败 | 人员查询内部错误 |
| 1-100-020-002 | 班组查询失败 | 班组查询内部错误 |
| 1-100-020-003 | 考勤查询失败 | 考勤查询内部错误 |
| 1-100-020-004 | 工单查询失败 | 工单查询内部错误 |
| 1-100-020-005 | 物料查询失败 | 物料查询内部错误 |
| 1-900-005-001 | 全量工单统计不存在 | 记录不存在 |
| 1-900-005-002 | 相同公司/班组同时间段统计已存在 | 重复数据校验 |
### 10.3 通用错误
| code | msg | 说明 |
|------|-----|------|
| 400 | 参数校验失败 | 请求参数格式或值不正确 |
| 500 | 系统内部错误 | 服务器内部异常 |
---
## 11. 附录：客户端签名代码示例
### 10.1 Java 示例
```java
import cn.hutool.crypto.digest.DigestUtil;
import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.core.util.RandomUtil;
import java.util.Map;
import java.util.TreeMap;
public class OpenApiClient {
private static final String BASE_URL = "https://test.jichengshanshui.com.cn:28302";
private static final String APP_ID = "your_app_id";
private static final String APP_SECRET = "your_app_secret";
public static String call(String path, Map<String, Object> params) {
String timestamp = String.valueOf(System.currentTimeMillis());
String nonce = RandomUtil.randomString(16);
String sign = buildSign(params, timestamp, nonce);
String url = BASE_URL + path;
HttpResponse response = HttpRequest.get(url)
.form(params)
.header("appId", APP_ID)
.header("timestamp", timestamp)
.header("nonce", nonce)
.header("sign", sign)
.execute();
return response.body();
}
private static String buildSign(Map<String, Object> params,
String timestamp, String nonce) {
StringBuilder sb = new StringBuilder();
// 1. 排序 query 参数值
if (params != null && !params.isEmpty()) {
new TreeMap<>(params).values().stream()
.map(String::valueOf).forEach(sb::append);
}
// 2. header 参数值（appId, nonce, timestamp 字母序）
sb.append(APP_ID);
sb.append(nonce);
sb.append(timestamp);
// 3. 追加 appSecret + SHA256
sb.append(APP_SECRET);
return DigestUtil.sha256Hex(sb.toString());
}
}
```
### 10.2 Python 示例
```python
import hashlib
import time
import random
import string
import requests
BASE_URL = "https://test.jichengshanshui.com.cn:28302"
APP_ID = "your_app_id"
APP_SECRET = "your_app_secret"
def build_sign(params, timestamp, nonce):
parts = []
if params:
for key in sorted(params.keys()):
parts.append(str(params[key]))
parts.append(APP_ID)
parts.append(nonce)
parts.append(timestamp)
parts.append(APP_SECRET)
sign_str = "".join(parts)
return hashlib.sha256(sign_str.encode()).hexdigest()
def call(path, params=None):
if params is None:
params = {}
timestamp = str(int(time.time() * 1000))
nonce = "".join(random.choices(string.ascii_lowercase + string.digits, k=16))
sign = build_sign(params, timestamp, nonce)
headers = {
"appId": APP_ID,
"timestamp": timestamp,
"nonce": nonce,
"sign": sign
}
response = requests.get(BASE_URL + path, params=params, headers=headers)
return response.json()
```
### 10.3 Shell (cURL) 示例
```bash
#!/bin/bash
APP_ID="your_app_id"
APP_SECRET="your_app_secret"
TIMESTAMP=$(date +%s%3N)
NONCE=$(openssl rand -hex 16)
# 示例：/open-api/staff/query?deptId=100
# query params 排序后 values: deptId=100 → "100"
QUERY_VALUES="100"
HEADER_VALUES="${APP_ID}${NONCE}${TIMESTAMP}"
SIGN_STR="${QUERY_VALUES}${HEADER_VALUES}${APP_SECRET}"
SIGN=$(echo -n "$SIGN_STR" | openssl dgst -sha256 -hex | awk '{print $2}')
curl -X GET "https://test.jichengshanshui.com.cn:28302/open-api/staff/query?deptId=100" \
-H "appId: ${APP_ID}" \
-H "timestamp: ${TIMESTAMP}" \
-H "nonce: ${NONCE}" \
-H "sign: ${SIGN}"
```
---
> **本文档基于 2026-06-11 代码生成，如有接口变更请同步更新。**
|
