幽冥大陆(七十三) 宇泛(Uni-Ubi) API闸机门禁对接

宇泛（Uni-Ubi）V2.1 人员管理 API 与闸机门禁对接指南（手机端适配）

一、品牌 + 型号：宇泛（Uni-Ubi）V2.1 人员管理 API

宇泛（Uni-Ubi）作为专注于生物识别与智能门禁的品牌，其 V2.1 版本人员管理 API（对应文档地址：https://api.uni-ubi.com/wo/apis/V2.1/wo/base/person.html）是支撑刷脸闸机 / 门禁 “本地白名单 + API 交互判定” 功能的核心接口集合，可实现人员信息创建、更新、删除，以及人脸、指纹注册等关键操作，适配宇泛全系列刷脸闸机（如宇泛 F1 系列人脸闸机、宇泛 A2 系列门禁终端），满足 “设备存人脸→刷脸传 ID→API 判权限→语音提醒” 的完整需求。

该 API 的核心能力包括：

支持人员基础信息（姓名、手机号、身份证号等）的全生命周期管理，生成唯一标识admitGuid（人员 GUID），作为 API 判定的核心身份凭证；
提供人脸注册接口，支持通过 Base64 编码或图片 URL 上传人脸，生成faceGuid（人像 GUID），可直接下发至本地设备作为白名单数据；
支持指纹特征上传，适配多模态认证场景，同时提供详细的查询接口，可实时获取人员信息与生物特征状态；
所有接口均需token（身份令牌）与projectGuid（项目 ID）双重认证，保障数据传输安全，适配 HTTPS 协议，符合企业级数据安全要求。

二、实现流程：从 API 对接至刷脸通行全步骤

基于宇泛 V2.1 人员管理 API，结合刷脸闸机 / 门禁的 “本地白名单 + API 交互判定” 需求，完整实现流程分为 5 步，适配手机端操作与开发调试：

1. 前期准备：获取 API 认证信息

登录宇泛 WO 控制台，创建项目并获取projectGuid（项目唯一标识）；
通过宇泛开发者平台申请token（身份令牌），后续所有 API 请求需在 Header 中携带token与projectGuid，格式如下：
- Header 参数：token: 你的令牌值、projectGuid: 你的项目ID

2. 本地白名单初始化：人员创建与人脸注册

创建人员主体：调用/v2/admit/create接口（POST 方式），传入人员姓名（必选）、手机号、身份证号等信息，示例参数：
json
```
{ "name": "张三", "phone": "138XXXX1234", "tag": "公司员工", "idCardNo": "440XXXXXX19900101XXXX" }
```
接口返回admitGuid（如89C74595FD524C29A68AD8FEC16F0E2B），作为该人员的唯一身份 ID，后续需关联人脸与权限。
上传人脸至本地设备：调用/v2/face/register接口（POST 方式），传入admitGuid（关联人员）与人脸信息（Base64 或图片 URL 二选一），示例参数：
json
```
{ "admitGuid": "89C74595FD524C29A68AD8FEC16F0E2B", "url": "https://xxx.oss-cn-hangzhou.aliyuncs.com/face/zhangsan.jpg", "faceTag": "正面照" }
```
接口返回faceGuid（人像唯一标识），同时自动将人脸特征下发至关联的宇泛闸机 / 门禁设备，完成本地白名单录入。

3. 刷脸认证：设备上传身份 ID

当用户在宇泛闸机 / 门禁前刷脸时，设备会先通过本地白名单比对人脸，确认匹配后，自动通过 API 将人员admitGuid（身份 ID）与比对结果（如 “人脸匹配成功”）推送至你的后端软件。

4. API 权限判定：返回结果与拒绝原因

你的后端软件接收admitGuid后，可结合业务逻辑（如人员权限有效期、通行时段、授权区域等）判定是否允许通行，再通过宇泛 API 或设备控制接口返回结果：

若允许通行：返回成功指令（如code: WO_SUS1000，msg: 允许通行），设备接收后执行开闸，并语音播报 “欢迎通行”；
若拒绝通行：返回具体拒绝原因（如 “权限过期”“非授权时段”），示例返回参数：
json
```
{ "result": 0, "code": "WO_ERR2001", "msg": "权限已过期，请联系管理员", "success": false }
```
设备接收后不执行开闸，同时语音播报msg中的拒绝原因。

5. 后续管理：人员信息更新与删除

若需修改人员信息（如手机号、备注）：调用/v2/admit/update接口，传入admitGuid与更新字段；
若需删除人员（移除白名单）：调用/v2/admit/delete接口，传入admitGuid（支持批量，用逗号分隔，最多 100 个）；
若需查询人员详情（如人脸状态、创建时间）：调用/v2/admit/detail接口，传入admitGuid即可获取完整信息。

三、价格：宇泛 API 与设备参考价

宇泛相关产品价格分为 “API 授权费” 与 “闸机 / 门禁硬件费” 两部分，参考市场行情如下：

1. API 授权费用

宇泛 V2.1 人员管理 API 本身不单独收费，但其使用需基于宇泛 WO 平台或开发者账号，账号授权费用根据企业规模分为：
- 小微企业版：免费（支持≤500 个人员管理，适合小型办公场景）；
- 企业标准版：约 3000-5000 元 / 年（支持≤5000 个人员管理，含技术支持）；
- 定制版：按需求报价（支持无限人员管理，含接口定制、专属售后）。

2. 配套刷脸闸机 / 门禁硬件价格

设备型号	设备类型	参考价（元）	核心功能
宇泛 F1 人脸闸机	摆闸 / 翼闸	3500-5000	本地白名单存储、活体检测、语音播报
宇泛 A2 门禁终端	壁挂式门禁机	800-1500	支持人脸 + 密码双认证，适配单门门禁
宇泛 S3 全高闸	全高闸（防尾随）	8000-12000	适合高安全场景（如园区、厂区）

注：以上价格为电商平台（如京东、宇泛官网）参考价，批量采购（≥10 台）可享 8-9 折优惠，部分套餐含安装服务。

四、补充：宇泛 V2.1 API 关键接口速查（手机端适配）

接口名称	请求 URL	核心作用	必传参数（JSON）
人员创建	/v2/admit/create	生成人员`admitGuid`	name（姓名）、token、projectGuid
人员更新	/v2/admit/update	修改人员信息	admitGuid、name（必选）
人员删除	/v2/admit/delete	移除本地白名单	admitGuids（多个用逗号分隔）
人脸注册	/v2/face/register	上传人脸至设备	admitGuid、base64/url（二选一）
人员详情查询	/v2/admit/detail	获取人员 + 人脸信息	admitGuid
指纹注册	/v2/fingerprint/create	上传指纹特征（多模态认证）	admitGuid、imageBase64、featureVersion

所有接口返回格式统一为 JSON，成功状态码均为WO_SUS1000，错误码可通过宇泛 WO 控制台查询对应原因，便于快速调试。

阿雪技术观

在科技发展浪潮中，我们不妨积极投身技术共享。不满足于做受益者，更要主动担当贡献者。无论是分享代码、撰写技术博客，还是参与开源项目维护改进，每一个微小举动都可能蕴含推动技术进步的巨大能量。东方仙盟是汇聚力量的天地，我们携手在此探索硅基生命，为科技进步添砖加瓦。

Hey folks, in this wild tech - driven world, why not dive headfirst into the whole tech - sharing scene? Don't just be the one reaping all the benefits; step up and be a contributor too. Whether you're tossing out your code snippets, hammering out some tech blogs, or getting your hands dirty with maintaining and sprucing up open - source projects, every little thing you do might just end up being a massive force that pushes tech forward. And guess what? The Eastern FairyAlliance is this awesome place where we all come together. We're gonna team up and explore the whole silicon - based life thing, and in the process, we'll be fueling the growth of technology