人行系统OpenApi接口文档 v1.0

1.概述

本文档面向第三方系统集成开发者，提供人行系统（门禁通行管理系统）的 OpenAPI 接口规范说明，帮助开发者快速对接以下核心功能：

访客模块：支持访客邀请，访客登记，访客信息维护等功能
门禁模块：提供员工及访客通行记录查询，通行状态管理等功能
黑名单模块：支持黑名单人员管理与通行限制控制
通行组模块：支持通行权限分组及权限分配管理
企业模块：支持企业信息及员工归属关系管理

通过本文档，开发者可以了解接口调用方式、参数说明、返回格式及常见问题解决方案。

2.前置准备

2.1 申请应用接入权限

为保障接口安全，所有请求需进行身份认证。具体流程如下：

向基础数据组提交应用接入申请，提供三方系统的名称。审核通过后，将获得以下凭证：

clientId：应用唯一标识
clientSecret：应用密钥（请妥善保管，切勿泄露）
请求签名（sign）生成：在发起接口请求前，需使用 clientSecret 对请求参数进行加密，生成签名 sign，并随请求一同传递。服务端将根据传入的 clientId 查找对应的 clientSecret，对 sign 进行校验，验证通过后方可提供服务。

⚠️ 注意：未携带有效 sign 或签名验证失败的请求将被拒绝。

2.2 统一认证机制

所有请求必须携带以下 Header。其中 sign 由 HMAC-SHA1 算法生成。具体步骤请查看 2.3.签名机制。本文附录一：签名生成包含Java完整实现代码

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

2.3 签名机制

3.名词解释

术语	解释
访客单	员工邀请访客的流程单
通行组	具有相同通行权限的人员分组
人员编码	人员入驻项目后生成唯一标识
访客单号	创建访客邀请后生成的唯一单号
项目编码	项目的唯一标识，由基础数据创建提供

系统交互流程

4.1 创建访客邀请

4.2 访客自助登记

通行组模块

5.1 通行组员工列表

概述：用于获取指定通行组内人员信息

接口定义：POST https://[host]/api/openApi/pass-team/v1.0.0/businessResident/page

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
pageNum	页码，从 1 开始。默认值1	Integer	否
pageSize	每页条数默认值10	Integer	否
projectCode	项目编号	String	是
name	姓名	String	否
mobile	手机号	String	否

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
data	响应数据	Object
+ pageNum	页数	Integer
+ pageSize	每页数量	Integer
+ totalPages	总页数	Integer
+ total	总记录数	Integer
+ list	人员列表	List
++ personCode	人员编码	String
++ name	真实姓名	String
++ gender	性别（0: 女, 1: 男，2：未知）	Integer
++ mobile	手机号	String
++ isVisitorInvite	是否有访客邀约权限（1：是，0：否）	Integer
msg	提示信息	String

企业模块

6.1 员工企业列表

概述：用于通过员工手机号在项目中已入驻的企业列表

接口定义：GET https://[host]/api/openApi/pass-team/v1.0.0/invite/tenantListByUser

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
mobile	员工手机号	String	是
projectCode	项目编号	String	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	List
+ companyFlag	是否公司	Boolean
+ companyId	企业ID	Long
+ spaceId	空间ID	Long
+ name	名称	String
+ children	子级	List
+ invitationStartTime	邀请开始时间，不限制为365	Integer
+ invitationEndTime	邀请结束时间，当天内有效为0	Integer
+ visitorInviteCCFlag	访客邀约抄送服务，0关闭，1开启	Integer
+ visitorRegisterBAApproveFlag	企业管理员审批，0关闭，1开启	Integer
+ visitorRegisterCarNumFlag	访客登记车牌，0关闭，1开启	Integer

6.2 员工楼层列表

定义：用于通过员工手机号在项目中已入驻企业中楼层信息

接口定义：POST https://[host]/api/openApi/pass-team/v1.0.0/invite/spaceFloorListByUser

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
mobile	员工手机号	String	是
projectCode	项目编号	String	是
companyId	企业ID	Long	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Object
+ projectName	项目名称	String
+ spaceNameList	空间名称列表	List
+ spaceDtoList	空间列表	List
++ spaceCode	空间编码	String
++ spaceName	空间名称	String
++ alias	空间别名	String
++ level	空间层级	Integer
++ createTime	创建时间	String
++ sort	排序值	Integer
++ parentSort	上级排序值	Integer
+ projectCode	项目编码	String

访客管理模块

7.1 创建访客邀请

定义：用于员工发起访客邀请

接口定义：POST https://[host]/api/openApi/invite/v1.0.0/addFlow

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
companyId	企业id	Long	是
interviewFloorId	楼层Id	Long	是
projectCode	项目编码	String	是
visitReason	来访事由(见附录)	Integer	是
intervieweeTelephone	被访人手机号	String	是
startTime	来访开始时间(yyyy-MM-dd HH:mm)	String	是
endTime	来访结束时间(yyyy-MM-dd HH:mm)	String	是
followVisitorList	访客列表	List	是
> + visitorName	访客姓名	String	是
> + visitorTelephone	访客手机号	String	是
> + isFollower	是否随访人(默认否，必须有一个主访客。true:主访人/false:随访人)	Boolean	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Object
+ flowUuid	访客单号	String

7.2 访客单列表查询

定义：用于系统中访客单列表

接口定义：POST https://[host]/api/openApi/invite/v1.0.0/front/page

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
pageNum	当前页码，默认 1	Integer	否
pageSize	每页条数，默认 10	Integer	否
projectCode	项目编码	String	是
visitName	访客姓名	String	否
startTime	来访开始时间（起始）	String	否
endTime	来访结束时间（截止）	String	否
applyStatus	申请状态（见附录）	Integer	否
visitStatus	到访状态（见附录）	Integer	否
visitPhone	访客手机号	String	否
tenantId	企业Id	Long	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Object
+ pageNum	当前页	Integer
+ pageSize	每页显示条数	Integer
+ totalPages	总页数	Integer
+ total	总记录数	Integer
+ list	结果集	List
++ visitSourceType	来源类型(见附录)	Integer
++ startTime	来访开始时间（yyyy-MM-dd HH:mm）	String
++ endTime	来访结束时间（yyyy-MM-dd HH:mm）	String
++ visitStatus	来访状态(见附录)	Integer
++ applyStatus	审核状态(见附录)	Integer
++ visitReason	来访事由(见附录)	Integer
++ intervieweeTelephone	被访人手机号	String
++ intervieweeName	被访人姓名	String
++ intervieweeEnterprise	被访人企业	String
++ flowUuid	流程UUID	String
++ visitorId	访客ID	Long
++ visitorName	来访人姓名	String
++ visitorTelephone	来访人电话	String
++ visitorType	访客属性	String
++ linkName	被访地址	String
++ interviewSpaceId	被访地址空间ID	Long
++ showDownloadBtn	是否显示下载通行码按钮	Boolean
++ qrcodeStaticContent	二维码静态内容	String
++ visitIdentityName	访客身份名称	String
++ plateNumber	车牌号	String
++ interviewFloorId	被访楼层ID	Long
++ approvalUserId	审核人ID	String
++ interviewFloorName	到访楼层名称	String

7.3 上传人脸图片

定义：用于上传人脸图片。注意:该接口单纯上传图片到服务器，并不是上传某个访客的人脸,接口返回图片地址。配合上传访客人脸接口使用。图片上传大小限制20KB

接口定义：POST https://[host]/api/openApi/invite/v1.0.0/face/add

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
face	图片base64编码	String	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Object
+ faceId	图片地址	String

7.4 上传访客人脸图片

定义：用于上传访客人脸图片。

接口定义：GET https://[host]/api/openApi/invite/v1.0.0/uploadVisitorFace

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
flowUuid	访客单UUID	String	是
faceId	图片地址	String	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Object

7.5 查询访客单详情

定义：用于查询访客单详情。

接口定义：GET https://[host]/api/openApi/invite/v1.0.0/visitFlow/detail

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
flowUuid	访客单编号	String	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Object
+ visitSourceType	来源类型(见附录)	Integer
+ visitReason	来访事由。备注:访客邀请单或线上预约时填写的来访理由。若用户未进行前台二次登记，此字段为最终展示值。	Integer
+ visitCause	来访事由。备注:前台现场登记时，安保人员或访客重新确认/修改的来访理由 1. 若用户经过前台登记，此字段有值，且优先级高于 visitReason。 2. 若用户直接通行（无前台登记），此字段为空。	Integer
+ visitCauseReasonName	来访事由(文字)	String
+ startTime	来访开始时间（yyyy-MM-dd HH:mm）	String
+ endTime	来访结束时间（yyyy-MM-dd HH:mm）	String
+ limitedTime	限时通行时间段（00:00-23:59）	String
+ visitStatus	来访状态(见附录)	Integer
+ applyStatus	审核状态(见附录)	Integer
+ intervieweeId	被访人ID	Long
+ intervieweeTelephone	被访人手机号	String
+ intervieweeName	被访人姓名	String
+ interviewSpaceId	被访空间ID	Long
+ companyId	企业ID	Long
+ flowUuid	流程UUID	String
+ qrcodeStaticContent	二维码静态内容	String
+ qrcodeContent	二维码内容	String
+ visitorList	访客列表	List
++ visitorName	访客姓名	String
++ visitorCode	访客编号	String
++ visitorPhoto	访客照片	String
++ visitorTelephone	手机号	String
++ visitorIdcard	身份证号	String
++ visitorType	访客类型	Integer
+ interviewSpaceName	被访空间名称	String
+ companyName	企业名称	String
+ visitIdentity	访客身份	Integer
+ visitIdentityName	访客身份名称	String
+ thirdVisitId	第三方访客ID	String
+ approvalUserId	审核人ID	String
+ plateNumber	车牌号	String
+ interviewFloorId	被访楼层ID	Long
+ interviewFloorName	被访楼层名称	String
+ createTime	创建时间（yyyy-MM-dd HH:mm:ss）	String
+ isExpire	是否过期	Integer

7.6 查询被访人是否公司员工

定义：访客自助填写访问信息时，查询被访人是否属于公司员工。

接口定义：GET https://[host]/api/openApi/invite/v1.0.0/register/checkMobile

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
mobile	被访人手机号	String	是
projectCode	项目编码	String	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Boolean

7.7 访客自助登记

定义：访客自助填写访问信息。

接口定义：POST https://[host]/api/openApi/invite/v1.0.0/register/add

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
intervieweeTelephone	被访人手机号	String	是
intervieweeName	被访人姓名	String	是
startTime	开始时间	String	是
endTime	结束时间	String	是
visitReason	来访事由(见附录)	Integer	是
followVisitorList	访客列表	List	是
> + visitorName	访客姓名	String	是
> + visitorTelephone	访客手机号	String	是
> + isFollower	是否随访人(必须有一个人为主访人。true:主访人/false:随访人)	Boolean	是
> projectCode	项目编码	String	是
> companyId	企业Id	Long	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Object

7.8 取消访客邀请

定义：取消访客邀请。

接口定义：POST https://[host]/api/openApi/invite/v1.0.0/visitor/cancel

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
flowUuid	访客单单号	String	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Object

7.9 访客二维码详情

定义：访客二维码，刷闸机使用

接口定义：GET https://[host]/api/openApi/invite/v1.0.0/visitor/qrcode/info/getByMobile

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
mobile	手机号	String	是
projectCode	项目编码	String	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Object
+ projectName	项目名称	String
+ projectCode	项目编码	String
+ qrcodeStaticContent	二维码图片静态内容	String
+ qrcodeContent	二维码内容	String
+ visitorName	访客姓名	String
+ startTime	来访开始时间（yyyy-MM-dd HH:mm）	String
+ endTime	来访结束时间（yyyy-MM-dd HH:mm）	String
+ limitedTime	限时通行时间段（00:00-23:59）	String
+ addressName	访问区域	String
+ visitSourceType	来源类型(见附录)	Integer
+ visitorPhoto	访客照片	String
+ interviewFloorName	访问楼层	String
+ effective	是否在有效期内	Boolean
+ flowUuid	访客单UUID	String
+ visitReason	来访事由（见附录)	Integer
+ applyStatus	审核状态(见附录)	Integer
+ visitPhone	访客手机号	String
+ visitorNumber	来访人数	Integer

黑名单模块

8.1 新增访客黑名单

定义：新增访客黑名单，禁止邀请黑名单中的访客。

接口定义：POST https://[host]/api/openApi/invite/v1.0.0/blacklisted

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
name	姓名	String	是
mobile	手机号	String	是
projectCode	项目编码	String	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Object

8.2 查询访客黑名单列表

定义：查询已添加的黑名单列表

接口定义：POST https://[host]/api/openApi/invite/v1.0.0/blacklistedList

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
pageNum	页码，从 1 开始.默认值1	Integer	否
pageSize	每页条数。默认值10	Integer	否
name	姓名	String	否
mobile	手机号	String	否
startTime	开始时间	String	否
endTime	结束时间	String	否
projectCode	项目编码	String	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Object
+ pageNum	当前页	Integer
+ pageSize	每页显示条数	Integer
+ totalPages	总页数	Integer
+ total	总记录数	Integer
+ list	结果集	List
++ name	姓名	String
++ mobile	手机号	String
++ entryDate	黑名单登记日期	String
++ creator	记录创建者	String

8.3 删除访客黑名单

定义：删除指定访客黑名单。

接口定义：DELETE https://[host]/api/openApi/invite/v1.0.0/blacklisted/del/

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

路径参数:

参数名称	参数说明	参数类型	是否必填
mobile	手机号	String	是

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Object

门禁模块

9.1 通行记录列表

定义：查询访客进出闸机的通行记录

接口定义：POST https://[host]/api/openApi/pass-records/v1.0.0/page

请求头:

参数名	示例值	参数类型	是否必填	参数描述
Authorization	clientId:sign	String	是	权限认证（调用方加密签名）
Date	Tue, 18 Nov 2025 02:09:56 GMT	String	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）服务端校验时差不得超过五分钟
Content-Type	application/json;charset=UTF-8	String	是	请求内容类型。固定格式:application/json;charset=UTF-8

请求参数:

参数名称	参数说明	参数类型	是否必填
pageNum	页码，从 1 开始。默认值1	Integer	否
pageSize	每页条数。默认值10	Integer	否
passTimeStart	通行开始时间	String	否
passTimeEnd	通行结束时间	String	否
projectCode	项目编码	String	是
name	姓名	String	否
mobile	手机号	String	否

返回参数:

参数名称	参数说明	参数类型
code	业务状态码，200 表示成功	Integer
success	操作是否成功	Boolean
msg	提示信息	String
data	响应数据	Object
+ pageNum	当前页	Integer
+ pageSize	每页显示条数	Integer
+ totalPages	总页数	Integer
+ total	总记录数	Integer
+ list	结果集	List
++ projectName	项目名称	String
++ projectCode	项目编码	String
++ personCode	人员编码	String
++ personName	人员姓名	String
++ personPhone	人员手机号	String
++ passType	通行验证方式（10刷卡、20二维码、30人脸、40蓝牙、50远程、60对讲、70密码、80身份证号）	Integer
++ deviceDirection	设备方向（0不限、1入口、2出口）	Integer
++ passTypeName	通行验证方式名称	String
++ employeeType	通行人员属性	Integer
++ employeeTypeName	通行人员属性名称	String
++ personTypeName	人类型名称	String
++ deviceName	设备名称	String
++ deviceCode	设备编码	String
++ modelName	设备型号名称	String
++ passTime	通行时间（yyyy-MM-dd HH:mm:ss）	String
++ passPhoto	通行照片全路径	String
++ passSnapshotPhoto	通行抓拍头像照片	String
++ linkName	空间名称	String
++ interviewSpace	被访地址空间	String
++ tenantName	企业名称	String

附录

附录A 签名生成

java

@Slf4j
public class OpenApiClientAuth {

    public static final String AUTHORIZATION = "Authorization";
    public static final String CONTENT_TYPE = "Content-Type";
    public static final String DATE = "Date";
    public static final DateTimeFormatter DATE_TIME_FORMATTER = DateTimeFormatter
            .ofPattern("EEE, dd MMM yyyy HH:mm:ss zzz", Locale.ENGLISH);

    /**
     * 构建带签名的请求头
     *
     * @param httpMethod   HTTP 方法（GET/POST/PUT等）
     * @param url          完整请求 URL（含查询参数）
     * @param clientId     客户端 ID
     * @param clientSecret 客户端密钥
     * @param contentType  内容类型，若为 null 则默认为 application/json
     * @return 包含 Authorization、Date、Content-Type 的 Header Map
     */
    @SneakyThrows
    public static Map<String, String> getSignHeaders(final String httpMethod, final String url,
                                                     final String clientId, final String clientSecret, final String contentType) {
        final String pathResource = getPathResource(url);
        log.info("pathResource: {}", pathResource);
        final String contentTypeValue = contentType != null ? contentType : "application/json";
        final String dateValue = DATE_TIME_FORMATTER.format(ZonedDateTime.now(ZoneId.of("GMT")));
        final String sign = calculateSign(httpMethod, contentTypeValue, dateValue, pathResource, clientSecret);
        log.info("sign: {}", sign);
        final String authorizationString = clientId + ":" + sign;
        final Map<String, String> authHeaders = new HashMap<>(4);
        log.warn(
                "method={};contentTypeValue={};dateValue={};canonicalizedResource={};appSecret={}",
                httpMethod, contentTypeValue, dateValue, pathResource,
                clientSecret);
        authHeaders.put(DATE, dateValue);
        authHeaders.put(AUTHORIZATION, authorizationString);
        authHeaders.put(CONTENT_TYPE, contentTypeValue);
        return authHeaders;
    }

    protected static String getPathResource(final String url) {
        final String substring = url.substring(url.indexOf("://") + 3);
        return substring.substring(substring.indexOf('/'));
    }

    public static String calculateSign(final String httpMethodString,
                                       final String contentTypeValue, final String dateValue, final String pathResource,
                                       final String appSecret) throws InvalidKeyException, NoSuchAlgorithmException {
        final String signToString = builderStringToSign(httpMethodString, contentTypeValue, dateValue, pathResource);
        final String base64HashString = HMAC.hmacSha1Encrypt(signToString, appSecret);
        return base64HashString.substring(5, 15);
    }

    protected static String builderStringToSign(final String method,
                                                final String contentTypeValue, final String dateValue, final String pathResource) {
        return method
                + "\n"
                + handleNullString(contentTypeValue)
                + "\n"
                + handleNullString(dateValue)
                + "\n"
                + pathResource;
    }

    protected static String handleNullString(final String str) {
        return !StringUtils.hasText(str) ? "" : str;
    }

    /**
     * 执行带签名的 HTTP 请求
     *
     * @param url          请求地址
     * @param body         请求体（JSON 字符串），GET 请求可传 null
     * @param httpMethod   HTTP 方法
     * @param clientId     客户端 ID
     * @param clientSecret 客户端密钥
     * @return 响应体字符串
     */
    public static String openApiClientExecute(String url, String body, HttpMethod httpMethod, String clientId, String clientSecret) {
        log.info("request url:{},param:{},httpMethod:{},appKey:{},appSecret:{}", url, body, httpMethod, clientId, clientSecret);
        RestTemplate restTemplate = new RestTemplate();
        Map<String, String> signHeaders = getSignHeaders(httpMethod.toString(), url, clientId, clientSecret, MediaType.APPLICATION_JSON.toString());
        final HttpHeaders headers = new HttpHeaders();
        signHeaders.forEach(headers::set);
        log.info("request headers:{}", headers);
        if (!StringUtils.hasText(body)) {
            body = "";
        }
        final HttpEntity<String> httpEntity = new HttpEntity<>(body, headers);
        final ParameterizedTypeReference<String> parameterizedTypeReference = new ParameterizedTypeReference<String>() {
        };
        String r = null;
        try {
            ResponseEntity<String> exchange = restTemplate.exchange(url, httpMethod, httpEntity, parameterizedTypeReference);
            r = exchange.getBody();
        } catch (Exception e) {
            log.error("request error: ", e);
        }
        log.info("request url:{},param:{},httpMethod:{},appKey:{},appSecret:{},result:{} ", url, body, httpMethod, clientId, clientSecret, r);
        return r;
    }

    protected static class HMAC {
        private static final String KEY_MAC_SHA1 = "HmacSHA1";

        private HMAC() {
        }

        public static String hmacSha1Encrypt(final String encryptText, final String encryptKey)
                throws NoSuchAlgorithmException, InvalidKeyException {
            final byte[] text = encryptText.getBytes(StandardCharsets.UTF_8);
            final byte[] keyData = encryptKey.getBytes(StandardCharsets.UTF_8);
            final SecretKeySpec secretKey = new SecretKeySpec(keyData, HMAC.KEY_MAC_SHA1);
            final Mac mac = Mac.getInstance(secretKey.getAlgorithm());
            mac.init(secretKey);
            return new String(Base64.getEncoder().encode(mac.doFinal(text)), StandardCharsets.UTF_8);
        }
    }

    /**
     * 验签
     *
     * @return
     */
    public static boolean validate(ValidateParamVO validateParam, String appSecret) {
        String finalQueryString = validateParam.getQueryString();
        if (!StringUtils.hasText(appSecret)) {
            throw new IllegalArgumentException(
                    "AppId[" + validateParam.getAppKey() + "] 没有被授权，找不到对应的AppSecurity");
        }
        String contentTypeValue = validateParam.getContentType();
        final String dateValue = validateParam.getDate();
        final String pathResource = catUrl(validateParam.getRequestUrl(), finalQueryString);
        if (!StringUtils.hasText(dateValue)) {
            throw new IllegalArgumentException("Header[" + DATE + "]不能为空.");
        }
        try {
            if (!StringUtils.hasText(contentTypeValue)) {
                contentTypeValue = MediaType.APPLICATION_JSON_VALUE;
            }
            if (contentTypeValue.contains(MediaType.MULTIPART_FORM_DATA_VALUE)) {
                contentTypeValue = MediaType.MULTIPART_FORM_DATA_VALUE;
            }
            final String realSign = calculateSign(validateParam.getMethod(),
                    contentTypeValue, dateValue,
                    pathResource,
                    appSecret);
            if (!validateParam.getSign().equals(realSign)) {
                log.warn(
                        "method={};contentTypeValue={};dateValue={};canonicalizedResource={};appSecret={}",
                        validateParam.getMethod(), contentTypeValue, dateValue, pathResource,
                        appSecret);
                log.warn("签名校验没有通过。sign={};realSign={}", validateParam.getSign(), realSign);
                return false;
            }
            return true;
        } catch (final Exception e) {
            final String msg = "鉴权异常" + e.getMessage();
            log.warn(msg, e);
            throw new IllegalArgumentException(msg);
        }
    }

    protected static String catUrl(final String uri, final String queryString) {
        return uri + ("".equals(handleNullString(queryString)) ? ""
                : "?" + queryString);
    }

    public static void main(String[] args) {
        String clientId = "testAppKey";
        String clientSecret = "testAppSecret";
        String postUrl2 = "https://sppams-uat.icloudcity.com/api/api/openApi/invite/v1.0.0/test";
        String format = String.format(postUrl2, clientId);
        System.out.println(format);
        JSONObject body2 = new JSONObject();
        // body2.put("clientId", "sppamsOpenApi");
        String result2 = openApiClientExecute(postUrl2, JSON.toJSONString(body2), HttpMethod.GET, clientId, clientSecret);
        System.out.println("Result: " + result2);
        final String dateValue = DATE_TIME_FORMATTER.format(ZonedDateTime.now(ZoneId.of("GMT")));
        boolean valid = isValid(dateValue);
        System.out.println(valid);
    }

    public static boolean isValid(String dateStr) {
        // 解析客户端时间
        ZonedDateTime requestTime = ZonedDateTime.parse(dateStr, DATE_TIME_FORMATTER);
        // 当前GMT时间
        ZonedDateTime now = ZonedDateTime.now(ZoneId.of("GMT"));
        // 计算时间差（秒）
        long diffSeconds = Math.abs(Duration.between(requestTime, now).getSeconds());
        // 允许5分钟（300秒）
        return diffSeconds <= 300;
    }
}

附录B 返回码说明

错误码	说明	消除建议
200	成功	无需处理
400	业务异常	根据返回错误消息查看请求参数是否异常
40000	业务异常	根据返回错误消息查看请求参数是否异常
20003	图片检测异常	检查参数中是否携带图片
100	检测人脸异常	检查人脸图片是否正常

附录C 数据字典

附录C1 来访事由

参数	含义
1	拜访
2	快递/外卖
3	其他
4	商务
5	面试
6	私人

附录C2 访客单审批状态

参数	含义
1	已审核（通过）
2	已审核（不通过）
3	未审核
4	已取消
5	已过期
6	审核中
11	免审核（通过）

附录C3 访客来访状态

参数	含义
1	已到访（有效中）
2	已到访（失效）
3	未来访

附录C4 访客来源

参数	含义
1	访客自助登记卡号
2	前台登记
3	访客邀请
4	企微办公申请
5	美团自助登记
6	饿了么自助登记
7	企微临时到访
8	顺丰速递自助登记
9	京东自助登记
10	顺丰同城自助登记
11	京东秒送自助登记

人行系统OpenApi接口文档 v1.0 ​

1.概述 ​

2.前置准备 ​

2.1 申请应用接入权限 ​

2.2 统一认证机制 ​

2.3 签名机制 ​

3.名词解释 ​

系统交互流程 ​

4.1 创建访客邀请 ​

4.2 访客自助登记 ​

通行组模块 ​

5.1 通行组员工列表 ​

企业模块 ​

6.1 员工企业列表 ​

6.2 员工楼层列表 ​

访客管理模块 ​

7.1 创建访客邀请 ​

7.2 访客单列表查询 ​

7.3 上传人脸图片 ​

7.4 上传访客人脸图片 ​

7.5 查询访客单详情 ​

7.6 查询被访人是否公司员工 ​

7.7 访客自助登记 ​

7.8 取消访客邀请 ​

7.9 访客二维码详情 ​

黑名单模块 ​

8.1 新增访客黑名单 ​

8.2 查询访客黑名单列表 ​

8.3 删除访客黑名单 ​

门禁模块 ​

9.1 通行记录列表 ​

附录 ​

附录A 签名生成 ​

附录B 返回码说明 ​

附录C 数据字典 ​

附录C1 来访事由 ​

附录C2 访客单审批状态 ​

附录C3 访客来访状态 ​

附录C4 访客来源 ​

人行系统OpenApi接口文档 v1.0

1.概述

2.前置准备

2.1 申请应用接入权限

2.2 统一认证机制

2.3 签名机制

3.名词解释

系统交互流程

4.1 创建访客邀请

4.2 访客自助登记

通行组模块

5.1 通行组员工列表

企业模块

6.1 员工企业列表

6.2 员工楼层列表

访客管理模块

7.1 创建访客邀请

7.2 访客单列表查询

7.3 上传人脸图片

7.4 上传访客人脸图片

7.5 查询访客单详情

7.6 查询被访人是否公司员工

7.7 访客自助登记

7.8 取消访客邀请

7.9 访客二维码详情

黑名单模块

8.1 新增访客黑名单

8.2 查询访客黑名单列表

8.3 删除访客黑名单

门禁模块

9.1 通行记录列表

附录

附录A 签名生成

附录B 返回码说明

附录C 数据字典

附录C1 来访事由

附录C2 访客单审批状态

附录C3 访客来访状态

附录C4 访客来源