 宇泛(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
- Header 参数：
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
