腾讯刷掌服务端API接口文档(v2.3.0)

本文档 Max 与 Standard 两个版本通用，接口内容一致。

版本更新记录

版本号	发布日期	更新内容
v2.3.0	2026-07-13	新增接口 • 新增DescribeUserAccessScope（查询用户通行范围）、DescribeUserAccessScopeSummary（查询用户通行范围摘要）接口 • 新增DescribeUserTagTree（查询用户标签树形结构）接口接口开放 • SendPalmMaSmsCode（发送短信验证码）、LoginPalmMaSmsCode（短信验证码登录）接口从内部改为对外开放，新增"PalmMa 登录相关接口"分类 • CreateQrCodeScanSession（创建扫码录掌会话）、DescribeQrCodeScanSession（查询扫码录掌会话状态）接口从内部改为对外开放接口参数变更 • LoginPalmMaSmsCode接口新增PhoneNo（手机号校验）、GrantType（授权类型）参数；SmsCode、SessionId改为非必填 • DescribeQrCodeScanSession接口响应新增PhoneNo（手机号）字段 • DescribeQrCodeScanUser接口响应新增PhoneNo（手机号）字段 • DescribeUserTag接口响应新增ParentTagId（父标签ID）、Level（层级深度）、ChildrenCount（直接子标签数量）、UserCount（标签关联用户数量）、PathNodes（层级链路）字段 • DescribeUserTagList接口响应UserTagItem新增ParentTagId、Level、ChildrenCount、PathNodes字段新增枚举与数据结构 • 新增GrantType枚举（授权类型：client_credential_user/client_credential） • 新增UserTagNode公共数据结构（标签层级路径节点） • 新增UserTag公共数据结构（用户标签信息，含PathNodes层级链路） • 新增UserTagTreeNode公共数据结构（标签树节点） • 新增AccessScopeItem、AccessScopeSummary、VerifyRuleInfo公共数据结构 • 新增错误码FailedOperation.PhoneNoAlreadyExists（1113，手机号已存在） • DeviceStatus枚举序列化方式从字符串调整为整数（int32）
v2.2.0	2026-06-17	版本号升级，接口无变动
v2.1.0	2026-05-07	新增接口 • 新增6个列表查询接口：DescribeUserList（查询用户信息列表）、DescribeUserTagList（查询用户标签列表）、DescribeDeviceList（查询设备列表）、DescribeSceneList（查询场景列表）、DescribeSceneGroupList（查询场景组列表）、DescribeVerifyRuleList（查询核验规则列表）接口参数变更 • CreateUser、ModifyUser接口新增CustomFieldValue参数（自定义加验字段值） • DescribeUser接口响应新增CustomFieldValue字段 • DescribeUserList接口新增PhoneNo、PhysicalCardNo、UserTagId筛选参数，响应新增CreatedTime、UpdatedTime字段 • DescribeDeviceList接口对外开放，新增Status、SceneId、DeviceType筛选参数，响应新增Status、SceneId、SceneName、CreatedTime、UpdatedTime字段 • DescribeVerificationRecordList接口新增SceneGroupIds、SceneGroupName、OrderBy参数，响应新增SceneGroupId、SceneGroupName字段 • NotifyQrCodeScanEvent接口新增EventType参数（扫码事件类型） • Verify接口VerifyResult参数类型由Integer调整为枚举VerifyResult（取值：1:成功 2:失败），明确合法取值范围（语义未变更，历史调用方传1/2完全兼容）新增枚举与数据结构 • 新增DeviceStatus枚举（设备状态：online/offline） • 新增AdditionalVerifyMethod枚举（加验方式：phone_no/custom_field/qr_code） • 新增VerificationRecordOrderField枚举（核验记录排序字段） • 新增SortOrder枚举（排序方向：asc/desc） • 新增QrCodeScanEventType枚举（扫码事件类型，作为NotifyQrCodeScanEvent.EventType取值） • 新增VerifyResult枚举（加验结果，作为Verify接口VerifyResult参数取值） • 新增OrderBy公共数据结构（排序条件）
v2.0.0	2026-04-03	• 新增掌纹管理相关接口（8个接口：CreatePalm、BindPalm、SearchMobilePalm、Verify、DeletePalm、DescribePalm、SynchronizePalmFeature、DescribeVersionList） • 新增鉴权管理接口DescribePalmLicense（查询授权信息） • DescribeUser接口输出参数新增UserState（用户状态）字段 • DescribeUserPalm接口输出参数新增UserName（用户名称）、UserState（用户状态）、PalmDirection（主掌方向）、LeftPalm（左掌录掌信息）、RightPalm（右掌录掌信息）字段 • DescribeQrCodeScanUser接口输出参数新增UserName（用户名称）、UserState（用户状态）、PalmDirection（主掌方向）、LeftPalm（左掌录掌信息）、RightPalm（右掌录掌信息）字段 • PalmState枚举新增abnormal（异常）枚举值 • 新增UserState枚举类型 • 新增Image、Pointf、Feature、VerifyInfo、PalmFeatureDetail、ProductVersionInfo公共业务数据结构 • 新增ImageType、PalmPaasPalmDirection、FeatureType、PalmStatus、PalmPaasOperation、HasMoreType、AlgorithmStrategy、VerifyType枚举类型
v1.8.1	2026-03-05	• DescribeUser接口输出参数新增PalmDirection（掌方向）、LeftPalm（左掌录掌信息）、RightPalm（右掌录掌信息）、CreateTime（用户创建时间）字段 • 新增PalmInfo公共业务数据结构（单掌录掌信息）
v1.8.0	2026-02-02	• 场景管理新增DescribeScene（查询场景详情）接口 • 设备管理新增DescribeDevice（查询设备详情）接口 • CreateScene接口新增SceneId（可选）和ScenarioStrategy（必填）参数 • ModifyScene接口新增ScenarioStrategy（必填）参数 • 新增ScenarioStrategy、RegisterType、PalmDirection枚举类型 • 新增5个业务错误码（InvalidUserId、RegisterTypeNotAllowed、Member相关错误码）
v1.7.1	2026-01-20	• CreateVerifyRule接口EnableWebhookRule参数改为可选，不传默认为true
v1.7.0	2026-01-05	• 新增用户标签管理功能（4个接口：CreateUserTag、ModifyUserTag、DeleteUserTag、DescribeUserTag） • 用户管理接口支持标签绑定和部分失败机制（CreateUser、ModifyUser支持UserTagIdList和PartialFailure参数） • 新增部分失败机制完整文档说明 • 统一接口命名规范（接口表格使用Action名称） • 新增14个业务错误码（用户标签、分页、会话、租户相关） • 优化4个错误码格式，移除39个已废弃错误码

简介

概述

腾讯刷掌（PalmAI），将腾讯多年来在计算机视觉与生物特征识别技术上的深度积累，以掌纹注册、掌纹识别、掌纹核验三大核心能力，通过腾讯云服务向企业和开发者开放，致力于帮助客户快速搭建安全、便捷、高效的掌纹识别解决方案。

本文档介绍的腾讯刷掌 API 接口均为腾讯云 API 3.0 接口。您可以调用 API 对腾讯刷掌服务进行操作，例如用户管理、掌纹注册与核验、设备管理、场景配置等。腾讯刷掌支持的所有接口信息，请参见 API 概览。

术语表

腾讯刷掌 API 接口的常见术语请参见下表：

术语	说明
AppId	应用唯一标识，是腾讯云后台用来区分不同Palm应用的唯一标识，在Palm控制台创建租户时自动生成。不同AppId之间的数据不互通
RGB	彩色图。
IR	红外图。
三点	图片检测配准后输出的数据。
特征值	图片输入到识别模型后输出的数据。
掌纹检索热库	指加载在 GPU 显存或内存中，为提升检索匹配效率而构建的高性能数据结构。系统中的数据分为存储在 GPU 显存或内存中的检索热库数据，以及一般性的存储数据（包括普通数据库、对象存储、文件存储等）。
设备类型	刷掌设备的型号标识，目前取值范围：M3、M3B、M4、O1、O2。
模组类型	刷掌设备所使用的识别模组型号标识，目前取值范围：A3、A3B。

API 概览

Palm API 遵循腾讯云 API3.0 规范，提供鉴权、掌纹管理、用户、用户手掌、设备、场景、核验记录、核验规则、扫码录掌等管理能力。

功能分类

鉴权管理相关接口
用户管理相关接口
用户标签管理相关接口
用户手掌管理相关接口
设备管理相关接口
场景管理相关接口
核验记录相关接口
核验规则相关接口
扫码录掌相关接口
PalmMa 登录相关接口
掌纹管理相关接口（刷掌算法平台）

鉴权管理相关接口

接口名称	接口功能	频率限制(次/秒/AppId)
CreateAccessToken	获取访问凭证	20
DescribePalmLicense	查询授权信息	20

用户管理相关接口

接口名称	接口功能	频率限制(次/秒/AppId)
CreateUser	创建用户	20
ModifyUser	修改用户	20
DeleteUser	删除用户	20
DescribeUser	查询用户	20
DescribeUserList	查询用户信息列表	20
DescribeUserAccessScope	查询用户通行范围	20
DescribeUserAccessScopeSummary	查询用户通行范围摘要	20

用户标签管理相关接口

接口名称	接口功能	频率限制(次/秒/AppId)
CreateUserTag	创建用户标签	20
ModifyUserTag	修改用户标签	20
DeleteUserTag	删除用户标签	20
DescribeUserTag	查询用户标签	20
DescribeUserTagList	查询用户标签列表	20
DescribeUserTagTree	查询用户标签树形结构	20

用户手掌管理相关接口

接口名称	接口功能	频率限制(次/秒/AppId)
DeleteUserPalm	删除用户手掌信息	20
DescribeUserPalm	查询用户手掌信息	20

设备管理相关接口

接口名称	接口功能	频率限制(次/秒/AppId)
CreateDevice	创建设备	20
ModifyDevice	修改设备	20
DeleteDevice	删除设备	20
DescribeDevice	查询设备详情	20
DescribeDeviceList	查询设备列表	20

场景管理相关接口

接口名称	接口功能	频率限制(次/秒/AppId)
CreateScene	创建场景	20
ModifyScene	修改场景	20
DeleteScene	删除场景	20
DescribeScene	查询场景详情	20
DescribeSceneList	查询场景列表	20
CreateSceneGroup	创建场景组	20
ModifySceneGroup	修改场景组	20
DeleteSceneGroup	删除场景组	20
DescribeSceneGroupList	查询场景组列表	20

核验记录相关接口

接口名称	接口功能	频率限制(次/秒/AppId)
CreateVerificationRecord	创建核验记录	20
DescribeVerificationRecordList	查询核验记录列表	20
DescribeVerificationRecord	查询核验记录（推送专用）	20

核验规则相关接口

接口名称	接口功能	频率限制(次/秒/AppId)
CreateVerifyRule	创建核验规则	20
ModifyVerifyRule	修改核验规则	20
DeleteVerifyRule	删除核验规则	20
DescribeVerifyRule	查询核验规则	20
DescribeVerifyRuleList	查询核验规则列表	20
CheckAccessPermission	校验访问权限（回调专用）	20

扫码录掌相关接口

接口名称	接口功能	频率限制(次/秒/AppId)
CreateQrCodeScanSession	创建扫码录掌会话	20
NotifyQrCodeScanEvent	用户扫码事件通知	20
BindQrCodeScanPalm	扫码绑定掌纹	20
DescribeQrCodeScanSession	查询扫码录掌会话状态	20
DescribeQrCodeScanUser	查询扫码录掌用户信息	20

PalmMa 登录相关接口

接口名称	接口功能	频率限制(次/秒/AppId)
SendPalmMaSmsCode	发送短信验证码	20
LoginPalmMaSmsCode	短信验证码登录	20

掌纹管理相关接口（刷掌算法平台）

接口名称	接口功能	频率限制(次/秒/AppId)
CreatePalm	创建掌纹	20
BindPalm	绑定掌纹	20
SearchMobilePalm	空中开掌检索	20
Verify	用户加验	20
DeletePalm	删除掌纹	20
DescribePalm	查询掌纹	20
SynchronizePalmFeature	同步掌纹特征	20
DescribeVersionList	查询产品版本列表	20

调用方式

调用基本流程

以下流程图说明了调用 Palm API 的基本步骤：

两种认证方式说明：

认证方式	适用场景	请求头
签名 + Token	大部分管理类接口（用户、设备、场景、掌纹等）	`Authorization` + `X-Palm-Openapi-Token`
仅 Token	扫码录掌类接口（NotifyQrCodeScanEvent、BindQrCodeScanPalm、DescribeQrCodeScanSession、DescribeQrCodeScanUser）	仅 `X-Palm-Openapi-Token`，无需 `Authorization`

说明：

所有接口调用前均需先通过 CreateAccessToken 获取 AccessToken（该接口本身使用签名认证）。

签名认证接口在请求头中同时携带 Authorization（签名）和 X-Palm-Openapi-Token（Token）。

仅 Token 认证接口只需携带 X-Palm-Openapi-Token，无需计算签名。

请求结构

Palm API 的请求结构如下：

1. 服务地址

API 支持就近地域接入，推荐使用如下域名：

默认接入域名（推荐）：open.intl.palm.tencent.com（仅为示例，实际接入域名请以分配为准，支持私有化部署场景）
指定地域接入（如有多地域部署，可扩展）：如 open.intl.palm.tencent.com（仅为示例，实际接入域名请以分配为准）

注意：域名是 API 的接入点，并不代表产品或接口实际提供服务的地域。后续如有多地域部署，将在文档中补充。

2. 通信协议

Palm API 所有接口均通过 HTTPS 进行通信，提供高安全性的通信通道。

3. 请求方法

推荐使用 POST 方法。
支持的 Content-Type 类型：
- application/json（推荐，必须使用签名方法 v3/TC3-HMAC-SHA256）
POST 方法使用签名方法 v3 时，支持最大 10MB 的请求包。

4. 字符编码

所有请求和响应均使用 UTF-8 编码。

公共参数

公共参数用于标识用户身份、接口签名和请求上下文。使用签名方法 v3（TC3-HMAC-SHA256）时，所有公共参数需放在 HTTP Header 请求头部。

参数名称	类型	必选	描述
X-TC-Action	String	是	操作的接口名称。例如：CreateUser。
X-TC-Timestamp	Integer	是	当前 UNIX 时间戳，单位为秒。例如：1704067200。与服务器时间相差超过5分钟会引起签名过期错误。
X-TC-Version	String	是	API 版本号，目前固定为：2025-07-15。
Authorization	String	是	签名信息，格式：TC3-HMAC-SHA256 Credential=AKIDxxx/Date/service/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx。详见签名方法章节。
X-TC-Nonce	String	是	随机字符串，一般用于防重放使用，建议每次请求都生成新的唯一的随机字符串。
Content-Type	String	是	请求内容类型，推荐 application/json; charset=utf-8。
Host	String	是	服务地址，固定为 open.intl.palm.tencent.com。
X-Palm-AppId	String	是	应用ID，申请安全凭证时获得。客户需向腾讯申请AppId、SecretId和SecretKey。请妥善保管以上信息，并根据业务需要在接口请求中传递
X-Palm-Openapi-Token	String	是	临时安全凭证Token。调用腾讯接口前，需首先通过【获取访问凭证】接口（Action: CreateAccessToken）获取访问凭证。请注意，访问凭证具有时效性，过期后需重新申请。

请求头示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateUser
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

签名方法

Palm API 采用腾讯云 API3.0 签名方法 v3（TC3-HMAC-SHA256）进行身份鉴权。

为什么要进行签名

验证请求者身份，确保请求来自持有有效密钥的用户。
保护传输中的数据，防止请求被篡改。

申请安全凭证

本文使用的安全凭证为密钥，密钥包括 SecretId 和 SecretKey。

SecretId：用于标识 API 调用者身份，可以简单类比为用户名。
SecretKey：用于验证 API 调用者的身份，可以简单类比为密码。

用户必须严格保管安全凭证，避免泄露，否则将危及财产安全。如已泄露，请立刻禁用该安全凭证。

申请安全凭证的具体步骤如下：

登录腾讯云刷掌服务控制台。
前往系统管理|租户管理的控制台页面。
在租户管理页面，选择当前租户，单击【详情】查询一对密钥。

签名过程（v3）

API 目前只支持 POST 请求。对于 POST 方法，目前只支持 Content-Type: application/json，请求体内容是以 JSON 格式传递的数据。

下面以绑定用户掌纹为例，分步骤介绍签名的计算过程。

假设用户的 SecretId 和 SecretKey 分别是：AKID******************************** 和 ********************************。

请求如下：

curl -X POST https://open.intl.palm.tencent.com \
-H "Authorization: TC3-HMAC-SHA256 Credential=AKID********************************/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp, Signature=f4b012d34bd468efb5cb90cb6c326ed42ec0f7de22accb38350606d95fa6b5db" \
-H "Content-Type: application/json" \
-H "Host: open.intl.palm.tencent.com" \
-H "X-TC-Action: BindPalm" \
-H "X-TC-Timestamp: 1752587686" \
-H "X-TC-Version: 2025-07-15" \
-H "X-Palm-AppId: 223" \
-H "X-TC-Nonce: c68bf577-60f1-45d8-a9ef-7a0a8c59690f" \
-H "X-Palm-Openapi-Token: **************************************" \
-d '{"PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47","UserId": "Alice","IsForce": true}'

下面详细解释签名计算过程。

拼接规范请求串

按如下伪代码格式拼接规范请求串（CanonicalRequest）：

CanonicalRequest =
    HTTPRequestMethod + '\n' +
    CanonicalURI + '\n' +
    CanonicalQueryString + '\n' +
    CanonicalHeaders + '\n' +
    SignedHeaders + '\n' +
    HashedRequestPayload

字段	说明
HTTPRequestMethod	HTTP 请求方法（GET、POST）。此示例取值为 `POST`。
CanonicalURI	URI 参数，API 3.0 固定为正斜杠（`/`）。
CanonicalQueryString	发起 HTTP 请求 URL 中的查询字符串，对于 POST 请求固定为空字符串 `""`，对于 GET 请求则为 URL 中问号（?）后面的字符串内容，例如：`Limit=10&Offset=0`。注意：CanonicalQueryString 需要参考 RFC3986 进行 URLEncode，字符集 UTF-8，推荐使用编程语言标准库，所有特殊字符均需编码，大写形式。
CanonicalHeaders	参与签名的头部信息，至少包含 host 和 content-type 两个头部，也可加入自定义的头部参与签名以提高自身请求的唯一性和安全性。拼接规则：1）头部 key 和 value 统一转成小写，并去掉首尾空格，按照 `key:value\n` 格式拼接；2）多个头部，按照头部 key（小写）的 ASCII 升序进行拼接。此示例计算结果为：`content-type:application/json\nhost:open.intl.palm.tencent.com\nx-palm-appid:223\nx-tc-nonce:c68bf577-60f1-45d8-a9ef-7a0a8c59690f\nx-tc-timestamp:1752587686\n`。注意：content-type 必须和实际发送的相符合，有些编程语言网络库即使未指定也会自动添加 charset 值，如果签名时和发送时不一致，服务器会返回签名校验失败。
SignedHeaders	参与签名的头部信息，说明此次请求有哪些头部参与了签名，和 CanonicalHeaders 包含的头部内容一一对应。content-type 和 host 为必选头部。拼接规则：1）头部 key 统一转成小写；2）多个头部 key（小写）按照 ASCII 升序进行拼接，并且以分号（;）分隔。此示例为：`content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp`
HashedRequestPayload	请求正文（Payload，即 Body）的哈希值，计算伪代码为 `Lowercase(HexEncode(Hash.SHA256(RequestPayload)))`，即对 HTTP 请求正文做 SHA256 哈希，然后十六进制编码，最后编码串转换成小写字母。注意：对于 GET 请求，RequestPayload 固定为空字符串；对于 POST 请求，RequestPayload 即为请求正文 Payload。

根据以上规则，示例中得到的规范请求串如下（为了展示清晰，\n 换行符以实际换行表示）：

POST
/

content-type:application/json
host:open.intl.palm.tencent.com
x-palm-appid:223
x-tc-nonce:c68bf577-60f1-45d8-a9ef-7a0a8c59690f
x-tc-timestamp:1752587686

content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp
b199b12c8af15dd7543ede5b6343d1abedd85f166b99b8b4b06599f10822b3a2

拼接待签名字符串

按如下伪代码格式拼接待签名字符串：

StringToSign =
    Algorithm + "\n" +
    RequestTimestamp + "\n" +
    CredentialScope + "\n" +
    HashedCanonicalRequest

字段	说明
Algorithm	签名算法，目前固定为 `TC3-HMAC-SHA256`。
RequestTimestamp	请求时间戳，即请求头部的公共参数 X-TC-Timestamp 取值，取当前时间 UNIX 时间戳，精确到秒。此示例取值为 `1752587686`。
CredentialScope	凭证范围，格式为 `Date/service/tc3_request`，包含日期、所请求的服务和终止字符串（tc3_request）。Date 为 UTC 标准时间的日期，取值需要和公共参数 X-TC-Timestamp 换算的 UTC 标准时间日期一致；service 为产品名，必须与调用的产品域名一致，此处为 `palm`。此示例计算结果为：`2025-07-15/palm/tc3_request`。
HashedCanonicalRequest	前述步骤拼接所得规范请求串的哈希值，计算伪代码为 `Lowercase(HexEncode(Hash.SHA256(CanonicalRequest)))`。此示例计算结果是 3044b1650deaa09d3d1e93d63c15fd76c7c764254b3a1cba9c6b321eda191774。

⚠️ 注意：

Date 必须从时间戳 X-TC-Timestamp 计算得到，且时区为 UTC+0。如果加入系统本地时区信息（例如东八区），将导致白天和晚上调用成功，但是凌晨时调用必定失败。假设时间戳为 1551113065，在东八区的时间是 2019-02-26 00:44:25，但是计算得到的 Date 取 UTC+0 的日期应为 2019-02-25，而不是 2019-02-26。

Timestamp 必须是当前系统时间，且需确保系统时间和标准时间是同步的，如果相差超过五分钟则必定失败。如果长时间不和标准时间同步，可能运行一段时间后，请求失败，返回签名过期错误。

根据以上规则，示例中得到的待签名字符串如下：

TC3-HMAC-SHA256
1752587686
2025-07-15/palm/tc3_request
3044b1650deaa09d3d1e93d63c15fd76c7c764254b3a1cba9c6b321eda191774

计算签名

1）计算派生签名密钥，伪代码如下：

SecretKey = "********************************"
SecretDate = HMAC_SHA256("TC3" + SecretKey, Date)
SecretService = HMAC_SHA256(SecretDate, Service)
SecretSigning = HMAC_SHA256(SecretService, "tc3_request")

派生出的密钥 SecretDate、SecretService 和 SecretSigning 是二进制的数据，可能包含不可打印字符，将其转为十六进制字符串打印的输出分别为：
2fbd1f93d8d1aae5c0a4e2df255519752e1e4be521b9edae832930379544679c，
45589385000e5972fe3fb6ca9f07339289dee6e33e0b5bb9022308d69eb15fc9，
a116ccc06739ebac6c1c54514ace4229c98847c5f1ee5abc395eafab262b0246。
请注意，不同的编程语言，HMAC 库函数中参数顺序可能不一样，请以实际情况为准。此处的伪代码密钥参数 key 在前，消息参数 data 在后。通常标准库函数会提供二进制格式的返回值，也可能会提供打印友好的十六进制格式的返回值，此处使用的是二进制格式。

字段	说明
SecretKey	原始的 SecretKey，即 `********************************`。
Date	即 Credential 中的 Date 字段信息。此示例取值为 `2025-07-15`。
Service	即 Credential 中的 Service 字段信息。此示例取值为 `palm`。

2）计算签名，伪代码如下：

Signature = HexEncode(HMAC_SHA256(SecretSigning, StringToSign))

此示例计算结果是 f4b012d34bd468efb5cb90cb6c326ed42ec0f7de22accb38350606d95fa6b5db。

拼接 Authorization

按如下格式拼接 Authorization：

Authorization =
    Algorithm + ' ' +
    'Credential=' + SecretId + '/' + CredentialScope + ', ' +
    'SignedHeaders=' + SignedHeaders + ', ' +
    'Signature=' + Signature

字段	说明
Algorithm	签名方法，固定为 `TC3-HMAC-SHA256`
SecretId	密钥对中的 SecretId，即 AKID********************************
CredentialScope	凭证范围，见上文，此示例为 `2025-07-15/palm/tc3_request`
SignedHeaders	参与签名的头部信息，此示例取值为 `content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp`
Signature	签名值。此示例计算结果是 f4b012d34bd468efb5cb90cb6c326ed42ec0f7de22accb38350606d95fa6b5db

根据以上规则，示例中得到的值为：

Authorization: TC3-HMAC-SHA256 Credential=AKID********************************/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp, Signature=f4b012d34bd468efb5cb90cb6c326ed42ec0f7de22accb38350606d95fa6b5db

最终完整的调用信息如下：

POST https://open.intl.palm.tencent.com/
Authorization: TC3-HMAC-SHA256 Credential=AKID********************************/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp, Signature=f4b012d34bd468efb5cb90cb6c326ed42ec0f7de22accb38350606d95fa6b5db
Content-Type: application/json
Host: open.intl.palm.tencent.com
X-Palm-AppId: 223
X-TC-Action: BindPalm
X-TC-Timestamp: 1752587686
X-TC-Version: 2025-07-15
X-TC-Nonce: c68bf577-60f1-45d8-a9ef-7a0a8c59690f
X-Palm-Openapi-Token: **************************************
{"PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47","UserId": "Alice","IsForce": true}

⚠️ 注意：请求发送时的 HTTP 头部（Header）和请求体（Payload）必须和签名计算过程中的内容完全一致，否则会返回签名不一致错误。可以通过打印实际请求内容、网络抓包等方式对比排查。

签名演示（Python）

以下为使用 Python 语言实现的完整签名过程演示代码：

def get_openapi_request_header(secret_id, secret_key, access_token, appid, action, nonce, data, svr_version = "standard"):
    version = "2025-07-15"
    timestamp = int(time.time())
    host = "open.intl.palm.tencent.com"
    service = "palm"
    algorithm = "TC3-HMAC-SHA256"
    date = datetime.utcfromtimestamp(timestamp).strftime("%Y-%m-%d")
 
    # ************* 步骤 1：拼接规范请求串 *************
    http_request_method = "POST"
    canonical_uri = "/"
    canonical_querystring = ""
    ct = "application/json"
    payload = json.dumps(data)  ##body
    canonical_headers = "content-type:%s\nhost:%s\nx-palm-appid:%s\nx-tc-nonce:%s\nx-tc-timestamp:%s\n" % (ct, host, str(appid), nonce, str(timestamp))
    signed_headers = "content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp"
    hashed_request_payload = hashlib.sha256(payload.encode("utf-8")).hexdigest()
    canonical_request = (http_request_method + "\n" +
                        canonical_uri + "\n" +
                        canonical_querystring + "\n" +
                        canonical_headers + "\n" +
                        signed_headers + "\n" +
                        hashed_request_payload)
    
    # ************* 步骤 2：拼接待签名字符串 *************
    credential_scope = date + "/" + service + "/" + "tc3_request"
    hashed_canonical_request = hashlib.sha256(canonical_request.encode("utf-8")).hexdigest()
    string_to_sign = (algorithm + "\n" +
                    str(timestamp) + "\n" +
                    credential_scope + "\n" +
                    hashed_canonical_request)
 
    # ************* 步骤 3：计算签名 *************
    # 计算签名摘要函数
    def sign(key, msg):
        return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest()
    secret_date = sign(("TC3" + secret_key).encode("utf-8"), date)
    secret_service = sign(secret_date, service)
    secret_signing = sign(secret_service, "tc3_request")
    signature = hmac.new(secret_signing, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
 
    # ************* 步骤 4：拼接 Authorization *************
    authorization = (algorithm + " " +
                    "Credential=" + secret_id + "/" + credential_scope + ", " +
                    "SignedHeaders=" + signed_headers + ", " +
                    "Signature=" + signature)
    print("authorization: {}".format(authorization))
 
    # 公共参数添加到请求头部
    headers = {
        "Authorization": authorization,
        "Host": host,
        "Content-Type": "application/json",
        "X-Palm-AppId": str(appid),
        "X-TC-Action": action,
        "X-TC-Timestamp": str(timestamp),
        "X-TC-Version": version,
        "X-TC-Nonce": nonce,
        "X-Palm-Openapi-Token": access_token
    }
    return headers

签名失败常见错误码

错误码	错误描述
AuthFailure.SignatureExpire	签名过期。Timestamp 与服务器接收到请求的时间相差不得超过五分钟。
AuthFailure.SecretIdNotFound	密钥不存在。请到控制台查看密钥是否被禁用，是否少复制了字符或者多了字符。
AuthFailure.SignatureFailure	签名错误。可能是签名计算错误，或者签名与实际发送的内容不相符合，也有可能是密钥 SecretKey 错误导致的。
AuthFailure.TokenFailure	临时证书 Token 错误。
AuthFailure.InvalidSecretId	密钥非法（不是云 API 密钥类型）。

返回结果

云 API 3.0 接口默认返回 JSON 数据，返回非 JSON 格式的接口会在文档中做出说明。返回 JSON 数据时最大限制为 50 MB，如果返回的数据超过最大限制，请求会失败并返回内部错误。建议根据接口文档中的过滤或分页功能，控制返回数据不要过大。

注意：只要请求被服务端正常处理，响应的 HTTP 状态码均为 200。例如签名失败等错误，HTTP 状态码也是 200，具体错误信息在返回体中体现。

正确返回结果

以用户查询接口为例，调用成功时返回如下：

{
  "Response": {
    "UserId": "user123456",
    "UserName": "张三",
    "PhoneNo": "(+86)13800138000",
    "PhysicalCardNo": "CARD001",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Response 及其内部的 RequestId 是固定字段，无论请求成功与否都会返回。
RequestId 用于唯一标识一次 API 请求，便于问题排查。
其余字段为具体接口定义的业务字段。

错误返回结果

调用失败时返回如下：

{
  "Response": {
    "Error": {
      "Code": "AuthFailure.SignatureFailure",
      "Message": "The provided credentials could not be validated. Please check your signature is correct."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error 字段出现代表请求失败，包含 Code（错误码）和 Message（错误信息）。
RequestId 依然会返回，用于问题排查。
错误码请参考接口文档"公共错误码"章节。

公共错误码

返回结果中如果存在 Error 字段，则表示调用 API 接口失败。Error.Code 字段为错误码，所有业务都可能出现的错误码为公共错误码。完整错误码列表请参考本产品"API 文档"目录下的"错误码"页面。

参数类型

Palm API 3.0 输入参数和输出参数支持如下数据类型：

类型	说明	示例
String	字符串	"user123456"
Integer	整型，上限为无符号64位整数。不同语言建议用最大整型定义。	123456
Boolean	布尔型，true/false	true
Float	浮点型	3.14
Double	双精度浮点型	3.1415926535
Date	字符串，日期格式	"2022-01-01"
Timestamp	字符串，时间格式	"2022-01-01 00:00:00"
Timestamp RFC3339	字符串，时间格式，RFC3339 标准时间格式，建议用标准库解析	"2022-01-01T00:00:20.021Z"
Binary	二进制内容，需以特定协议请求和解析	-

部分失败

部分失败（Partial Failure）是一种特殊的处理机制，允许在批量操作中即使部分操作失败，成功的操作仍然会被执行。这种机制可以提高批量操作的容错性和效率。

什么是部分失败

在批量操作（如批量绑定用户标签等）中，如果不使用部分失败机制：

任何一项操作失败，整个请求都会失败
所有操作都会回滚，即使其中大部分操作是有效的

启用部分失败机制后：

有效的操作会成功执行
失败的操作会在响应中返回详细的错误信息
可以根据返回的错误信息重试失败的操作

如何使用部分失败

支持部分失败的接口会提供 PartialFailure 参数：

请求参数：

参数名称	必选	类型	描述
PartialFailure	否	Boolean	是否允许部分失败。设置为 `true` 时启用部分失败机制，默认为 `false`。

响应字段：

当启用部分失败且存在失败项时，响应中会包含 PartialFailureError 字段，详细说明失败的原因：

参数名称	类型	描述
PartialFailureError	Object	部分失败错误信息，包含失败项的详细信息。

示例场景

场景一：创建用户并批量绑定标签

请求示例：

{
  "UserId": "user001",
  "UserName": "张三",
  "UserTagIdList": ["tag001", "tag002", "tag003"],
  "PartialFailure": true
}

成功响应（无失败项）：

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

部分失败响应（存在失败项）：

{
  "Response": {
    "PartialFailureError": {
      "NotExistUserTagIdList": ["tag003"]
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

在上述示例中：

用户 user001 创建成功
tag001 和 tag002 绑定成功
tag003 不存在，绑定失败

重试说明:如需重试,修正 tag003 后必须传入完整的标签列表 ["tag001", "tag002", "tag003"],而非仅传入 ["tag003"],因为用户标签绑定是覆盖式操作。

最佳实践

批量操作时启用部分失败
- 在批量创建、修改等操作中，建议设置 PartialFailure=true
- 这样可以确保有效数据被处理，无效数据被记录
检查响应中的 PartialFailureError 字段
- 即使正确返回结果，也要检查 PartialFailureError 字段
- PartialFailureError 存在表示有部分操作失败，需要根据返回信息进行处理
记录并重试失败项
- 记录 PartialFailureError 中返回的失败项信息
- 修正失败原因后重新发起请求
- 注意:对于批量绑定用户标签等覆盖式操作,重试时必须传入完整的标签列表(包括之前成功的项),而非仅重试失败的项
幂等性设计
- 确保操作具有幂等性，以便安全地重试失败的操作
- 批量绑定操作必须使用完整数据重试(覆盖式更新)

支持部分失败的接口

以下接口支持部分失败机制：

创建用户：支持批量绑定用户标签时的部分失败
修改用户：支持批量绑定用户标签时的部分失败

注意：并非所有接口都支持部分失败机制。具体支持情况请参考各接口的参数说明。

鉴权管理相关接口

获取访问凭证

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于获取访问凭证（AccessToken），如下调用方式仅限普通服务端调用刷掌业务平台开放接口的场景。

注意： 本接口仅需签名（Authorization），无需传递 X-Palm-Openapi-Token。在接入刷掌业务平台服务前，客户需向腾讯申请AppId、SecretId和SecretKey。请妥善保管以上信息，并根据业务需要在接口请求中传递。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreateAccessToken。
Version	是	String	公共参数，本接口取值：2025-07-15。
AppId	是	Integer	系统分配的产品ID
SecretId	是	String	客户的密钥ID
SecretKeyHash	是	String	客户的密钥hash，计算规则为：hex.EncodeToString(sha256.Sum256(secretKey))
GrantType	是	String	授权类型。调用刷掌业务平台开放接口时，必须使用 `client_credential`。取值枚举： - client_credential_user：适用于第三方平台接入空中开掌 SDK 场景，即： a. 移动端使用 SDK 发起注册或获取活体视频上传地址流程； b. 第三方服务端需根据指定用户申请访问凭证，供 SDK 使用； c. 此时必须同时传入 `UserId` 字段。 - client_credential：适用于普通服务端调用开放接口场景，即： a. 此类型下不绑定具体用户，仅使用应用级密钥获取访问凭证； b. `UserId` 字段无需传入。
UserId	否	String	用户的身份id，grant_type为"client_credential_user"时，必须传递UserId字段

3. 输出参数

参数名称	类型	描述
AccessToken	String	访问凭证，后续可以根据该凭证访问其他接口
ExpiresIn	Integer	AccessToken的有效期，单位为秒，过期后token无效
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateAccessToken
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
   "AppId": 223,
   "SecretId": "this is secretId",
   "SecretKeyHash": "this is secretKey hash",
   "GrantType": "client_credential"
}

输出示例

{
  "Response": {
    "AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "ExpiresIn": 7200,
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询授权信息

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：查询服务端授权信息，包括掌库容量上限、当前使用量和License过期时间。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribePalmLicense。
Version	是	String	公共参数，本接口取值：2025-07-15。
AppId	是	Integer	系统分配的产品ID。

3. 输出参数

参数名称	类型	描述
PalmCapacity	Integer	掌库容量上限，表示当前授权允许注册的最大掌纹数量。
PalmUsage	Integer	当前掌库使用量，表示已注册的掌纹数量。
ExpireTime	Integer	License过期时间，UTC时间戳，单位：秒。过期后将无法继续使用服务。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribePalmLicense
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "AppId": 223
}

输出示例

{
  "Response": {
    "PalmCapacity": 100000,
    "PalmUsage": 5000,
    "ExpireTime": 1756108800,
    "RequestId": "e3b0c442-98fc-1c14-b39f-f75b262b1d0e"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

用户管理相关接口

创建用户

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于创建新用户，支持设置用户基本信息。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreateUser。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	是	String	用户唯一标识。
UserName	是	String	用户名称。
PhoneNo	否	String	手机号（带区号），如“(+86)13530612342”，如未填写地区号，则默认“(+86)”。
PhysicalCardNo	否	String	实体卡号，数字英文组合。
UserTagIdList	否	Array of String	用户标签ID列表。
PartialFailure	否	Boolean	是否允许部分失败。
CustomFieldValue	否	String	自定义加验字段值（纯数字），租户启用custom_field加验方式时建议填写。

3. 输出参数

参数名称	类型	描述
PartialFailureError	CreateUserResponsePartialFailureError	部分失败结果，参见 CreateUserResponsePartialFailureError 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateUser
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user123456",
  "UserName": "张三",
  "PhoneNo": "(+86)13530612342",
  "PhysicalCardNo": "CARD001",
  "UserTagIdList": ["tag001", "tag002"],
  "PartialFailure": true
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

部分失败输出示例

{
  "Response": {
    "PartialFailureError": {
      "NotExistUserTagIdList": [
        "tag003"
      ]
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.UserNameEmpty",
      "Message": "用户名称为空"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

修改用户

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于修改用户信息，支持更新用户的基本信息。

注意： 此接口为全量更新，需要传入用户的所有字段信息。未传入的可选字段将被清空，建议先调用 DescribeUser 获取当前用户信息后再修改。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：ModifyUser。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	是	String	用户唯一标识。
UserName	是	String	用户名称。
PhoneNo	否	String	手机号（带区号），如“(+86)13530612342”，如未填写地区号，则默认“(+86)”。
PhysicalCardNo	否	String	实体卡号，数字英文组合。
UserTagIdList	否	Array of String	用户标签ID列表。
PartialFailure	否	Boolean	是否允许部分失败。
CustomFieldValue	否	String	自定义加验字段值（纯数字），租户启用custom_field加验方式时建议填写。

3. 输出参数

参数名称	类型	描述
PartialFailureError	ModifyUserResponsePartialFailureError	部分失败结果，参见 ModifyUserResponsePartialFailureError 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: ModifyUser
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "UserName": "张三",
  "PhoneNo": "(+86)13800138000",
  "UserTagIdList": ["tag001", "tag002"],
  "PartialFailure": true,
  "CustomFieldValue": "123456"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

部分失败输出示例

{
  "Response": {
    "PartialFailureError": {
      "NotExistUserTagIdList": [
        "tag003"
      ]
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "用户不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

删除用户

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于删除指定用户，删除后用户数据将无法恢复。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DeleteUser。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	是	String	用户唯一标识。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteUser
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "用户不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询用户

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询指定用户的详细信息，包括基本信息和录掌状态。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeUser。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	是	String	用户唯一标识。

3. 输出参数

参数名称	类型	描述
UserId	String	用户唯一标识。
UserName	String	用户名称。
PhoneNo	String	手机号（带区号），如"(+86)13530612342"，如未填写地区号，则默认"(+86)"。
PhysicalCardNo	String	实体卡号，数字英文组合。
UserTagList	Array of DescribeUserResponseUserTag	用户标签列表，参见 DescribeUserResponseUserTag 结构。
PalmDirection	PalmDirection	掌方向，见 PalmDirection 枚举。
LeftPalm	PalmInfo	左掌录掌信息，参见 PalmInfo 结构。
RightPalm	PalmInfo	右掌录掌信息，参见 PalmInfo 结构。
CreateTime	Timestamp	用户创建时间，RFC3339字符串格式，如"2025-07-03T09:30:15.500Z"。
UserState	UserState	用户状态，见 UserState 枚举。
CustomFieldValue	String	自定义加验字段值，未设置时为空。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUser
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001"
}

输出示例

{
  "Response": {
    "UserId": "user001",
    "UserName": "张三",
    "PhoneNo": "(+86)13800138000",
    "PhysicalCardNo": "CARD2024A001",
    "UserTagList": [
      {
        "UserTagId": "tag001",
        "UserTagName": "研发中心"
      },
      {
        "UserTagId": "tag002",
        "UserTagName": "产品中心"
      }
    ],
    "PalmDirection": "right",
    "RightPalm": {
      "PalmState": "registered",
      "RegisterType": "device",
      "PreRegisterTime": "2025-06-01T10:00:00.000Z",
      "RegisterTime": "2025-06-01T10:05:00.000Z",
      "ExpireTime": "2026-06-01T10:05:00.000Z"
    },
    "CreateTime": "2025-05-20T08:30:00.000Z",
    "UserState": "right_valid",
    "CustomFieldValue": "123456",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "未找到该用户信息。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询用户信息列表

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询用户信息列表，支持多条件过滤、分页。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeUserList。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	否	String	用户唯一标识，支持模糊查询。
UserName	否	String	用户名，支持模糊查询。
PhoneNo	否	String	手机号，精确匹配。
PhysicalCardNo	否	String	实体卡号，精确匹配。
PalmState	否	PalmState	主掌录掌状态。
UserState	否	UserState	用户状态。
UserTagId	否	String	用户标签ID，筛选拥有指定标签的用户。
Offset	否	Integer	偏移量，默认0。
Limit	否	Integer	返回数量，默认20，最大100。

3. 输出参数

参数名称	类型	描述
TotalCount	Integer	符合条件的用户数量。
UserList	Array of DescribeUserListResponseUser	用户列表，参见 DescribeUserListResponseUser 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserName": "张",
  "PalmState": "registered",
  "Offset": 0,
  "Limit": 10
}

输出示例

{
  "Response": {
    "TotalCount": 1,
    "UserList": [
      {
        "UserId": "user001",
        "UserName": "张三",
        "PhoneNo": "(+86)13800138000",
        "PhysicalCardNo": "CARD001",
        "UserTagList": [{"UserTagId": "tag001", "UserTagName": "研发中心"}],
        "RegisterType": "device",
        "PalmState": "registered",
        "PalmDirection": "right",
        "PalmRegisterTime": "2025-06-01T10:05:00.000Z",
        "PalmExpireTime": "2026-06-01T10:05:00.000Z",
        "UserState": "right_valid",
        "CreatedTime": "2025-05-20T08:30:00.000Z",
        "UpdatedTime": "2025-06-01T10:05:00.000Z"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询用户通行范围

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：根据用户ID查询该用户可通行的场景、设备、通行时段等详细信息。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeUserAccessScope。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	是	String	用户唯一标识。
Offset	否	Integer	偏移量，默认为0。
Limit	否	Integer	返回数量，默认为20，最大值为100。

3. 输出参数

参数名称	类型	描述
TotalCount	Integer	符合条件的场景总数。
AccessScopeList	Array of AccessScopeItem	通行范围列表（以场景维度聚合）。参见 AccessScopeItem 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserAccessScope
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "Offset": 0,
  "Limit": 20
}

输出示例

{
  "Response": {
    "TotalCount": 1,
    "AccessScopeList": [
      {
        "SceneId": "scene001",
        "SceneName": "大门",
        "SceneGroupId": "group001",
        "SceneGroupName": "总部园区",
        "DeviceSn": "DEV001",
        "DeviceName": "前台设备",
        "VerifyRules": [
          {"VerifyRuleId": "rule001", "VerifyRuleName": "工作日规则"}
        ]
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询用户通行范围摘要

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：根据用户ID统计该用户可通行的场景组数、场景数、设备数。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeUserAccessScopeSummary。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	是	String	用户唯一标识。

3. 输出参数

参数名称	类型	描述
Summary	AccessScopeSummary	通行范围摘要。参见 AccessScopeSummary 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserAccessScopeSummary
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001"
}

输出示例

{
  "Response": {
    "Summary": {
      "SceneGroupCount": 3,
      "SceneCount": 8,
      "DeviceCount": 15
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

用户标签管理相关接口

创建用户标签

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于创建新的用户标签。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreateUserTag。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserTagName	是	String	用户标签名称。

3. 输出参数

参数名称	类型	描述
UserTagId	String	用户标签唯一标识。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateUserTag
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserTagName": "研发中心"
}

输出示例

{
  "Response": {
    "UserTagId": "tag001",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.UserTagNameEmpty",
      "Message": "用户标签名称为空"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

修改用户标签

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于修改用户标签信息。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：ModifyUserTag。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserTagId	是	String	用户标签唯一标识。
UserTagName	是	String	用户标签名称。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: ModifyUserTag
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserTagId": "tag001",
  "UserTagName": "产品中心"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserTagNotExist",
      "Message": "用户标签不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

删除用户标签

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于删除指定用户标签，删除后用户标签数据将无法恢复。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DeleteUserTag。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserTagId	是	String	用户标签唯一标识。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteUserTag
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserTagId": "tag001"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserTagNotExist",
      "Message": "用户标签不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询用户标签

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询指定用户标签的详细信息。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeUserTag。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserTagId	是	String	用户标签唯一标识。

3. 输出参数

参数名称	类型	描述
UserTagId	String	用户标签唯一标识。
UserTagName	String	用户标签名称。
ParentTagId	String	父标签ID，为空表示顶级标签。
Level	Integer	层级深度：0=L1(顶级), 1=L2(二级), 2=L3(三级)。
ChildrenCount	Integer	直接子标签数量。
UserCount	Integer	标签关联的用户数量。
PathNodes	Array of UserTagNode	从根标签到当前标签的完整层级链路，按父到子顺序返回。参见 UserTagNode 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserTag
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserTagId": "tag001"
}

输出示例

{
  "Response": {
    "UserTagId": "tag001",
    "UserTagName": "研发中心",
    "ParentTagId": "",
    "Level": 0,
    "ChildrenCount": 3,
    "UserCount": 50,
    "PathNodes": [
      {
        "UserTagId": "tag001",
        "UserTagName": "研发中心",
        "Level": 0
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserTagNotExist",
      "Message": "未找到该用户标签信息。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询用户标签列表

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询用户标签列表，支持模糊搜索和分页。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeUserTagList。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserTagName	否	String	标签名称，支持模糊搜索。
Offset	否	Integer	偏移量，默认0。
Limit	否	Integer	返回数量，默认20，最大100。

3. 输出参数

参数名称	类型	描述
TotalCount	Integer	符合条件的标签总数。
UserTagList	Array of DescribeUserTagListResponseUserTagItem	标签信息列表，参见 DescribeUserTagListResponseUserTagItem 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserTagList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserTagName": "研发",
  "Offset": 0,
  "Limit": 20
}

输出示例

{
  "Response": {
    "TotalCount": 1,
    "UserTagList": [
      {
        "UserTagId": "tag001",
        "UserTagName": "研发中心",
        "UserCount": 50,
        "ParentTagId": "",
        "Level": 0,
        "ChildrenCount": 3,
        "PathNodes": [
          {
            "UserTagId": "tag001",
            "UserTagName": "研发中心",
            "Level": 0
          }
        ],
        "CreatedTime": "2025-05-01T10:00:00.000Z",
        "UpdatedTime": "2025-06-01T10:00:00.000Z"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询用户标签树形结构

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：查询用户标签树形结构，返回标签层级关系。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeUserTagTree。
Version	是	String	公共参数，本接口取值：2025-07-15。
RootTagId	否	String	根标签ID，为空表示返回完整树。

3. 输出参数

参数名称	类型	描述
Tree	Array of UserTagTreeNode	标签树节点列表。参见 UserTagTreeNode 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserTagTree
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "RootTagId": ""
}

输出示例

{
  "Response": {
    "Tree": [
      {
        "UserTagId": "tag001",
        "UserTagName": "研发部",
        "UserCount": 50,
        "Level": 0,
        "ParentTagId": "",
        "Children": [
          {
            "UserTagId": "tag002",
            "UserTagName": "前端组",
            "UserCount": 20,
            "Level": 1,
            "ParentTagId": "tag001",
            "Children": []
          }
        ]
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

用户手掌管理相关接口

删除用户手掌信息

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于删除指定用户的手掌信息，删除后需要重新录掌。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DeleteUserPalm。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	是	String	用户唯一标识。
PalmDirectionList	否	Array of PalmDirection	手掌方向列表，不传则删除双掌。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteUserPalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "PalmDirectionList": ["left", "right"]
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "用户手掌信息不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询用户手掌信息

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询指定用户的掌纹信息及录掌状态。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeUserPalm。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	是	String	用户唯一标识。

3. 输出参数

参数名称	类型	描述
UserId	String	用户唯一标识。
PalmState	PalmState	主掌录掌状态。
UserName	String	用户名称。
UserState	UserState	用户状态，见 UserState 枚举。
PalmDirection	PalmDirection	主掌方向，见 PalmDirection 枚举。
LeftPalm	PalmInfo	左掌录掌信息，参见 PalmInfo 结构。
RightPalm	PalmInfo	右掌录掌信息，参见 PalmInfo 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserPalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001"
}

输出示例

{
  "Response": {
    "UserId": "user001",
    "PalmState": "registered",
    "UserName": "张三",
    "UserState": "right_valid",
    "PalmDirection": "right",
    "RightPalm": {
      "PalmState": "registered",
      "RegisterType": "device",
      "PreRegisterTime": "2025-06-01T10:00:00.000Z",
      "RegisterTime": "2025-06-01T10:05:00.000Z",
      "ExpireTime": "2026-06-01T10:05:00.000Z"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "未找到该用户手掌信息。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

设备管理相关接口

创建设备

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于创建新设备，支持设置设备基本信息。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreateDevice。
Version	是	String	公共参数，本接口取值：2025-07-15。
DeviceSn	是	String	设备序列号。
DeviceName	是	String	设备名称。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateDevice
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "DeviceSn": "device001",
  "DeviceName": "深圳南山门禁1号"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.DeviceSnEmpty",
      "Message": "设备SN为空"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

修改设备

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于修改设备信息，支持更新设备的基本信息。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：ModifyDevice。
Version	是	String	公共参数，本接口取值：2025-07-15。
DeviceSn	是	String	设备序列号。
DeviceName	是	String	设备名称。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: ModifyDevice
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "DeviceSn": "device001",
  "DeviceName": "深圳南山门禁1号（已更新）"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.DeviceNotExist",
      "Message": "设备不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

删除设备

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于删除指定设备，删除后设备数据将无法恢复。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DeleteDevice。
Version	是	String	公共参数，本接口取值：2025-07-15。
DeviceSn	是	String	设备序列号。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteDevice
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "DeviceSn": "device001"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.DeviceNotExist",
      "Message": "设备不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询设备详情

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询指定设备的详细信息。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeDevice。
Version	是	String	公共参数，本接口取值：2025-07-15。
DeviceSn	是	String	设备序列号。

3. 输出参数

参数名称	类型	描述
DeviceSn	String	设备SN。
DeviceName	String	关联设备名。
DeviceType	String	设备类型。
ModuleType	String	模组类型。
ModuleExpireTime	Timestamp	模组有效期，RFC3339字符串格式，如"2025-07-03T09:30:15.500Z"。
AppVersion	String	应用版本。
ModuleVersion	String	模组版本。
SystemVersion	String	系统版本。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeDevice
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "DeviceSn": "device001"
}

输出示例

{
  "Response": {
    "DeviceSn": "device001",
    "DeviceName": "深圳南山门禁设备",
    "DeviceType": "M4",
    "ModuleType": "A3",
    "ModuleExpireTime": "2027-07-03T09:30:15.500Z",
    "AppVersion": "1.0.0",
    "ModuleVersion": "2.0.0",
    "SystemVersion": "3.0.0",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.DeviceNotExist",
      "Message": "设备不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询设备列表

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询设备列表，支持多条件过滤、分页。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeDeviceList。
Version	是	String	公共参数，本接口取值：2025-07-15。
DeviceSn	否	String	设备序列号，精确匹配。
DeviceName	否	String	设备名称，支持模糊搜索。
Status	否	DeviceStatus	设备状态筛选。
SceneId	否	String	场景ID，筛选绑定到指定场景的设备。
DeviceType	否	String	设备类型，取值见术语表。
Offset	否	Integer	偏移量，默认0。
Limit	否	Integer	返回数量，默认20，最大100。

3. 输出参数

参数名称	类型	描述
TotalCount	Integer	符合条件的设备总数。
DeviceList	Array of DescribeDeviceListResponseDevice	设备列表，参见 DescribeDeviceListResponseDevice 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeDeviceList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "DeviceName": "门禁",
  "Status": "online",
  "Offset": 0,
  "Limit": 10
}

输出示例

{
  "Response": {
    "TotalCount": 1,
    "DeviceList": [
      {
        "DeviceSn": "SN001",
        "DeviceType": "M4",
        "DeviceName": "深圳南山门禁设备",
        "HeartbeatTime": "2025-07-15T09:30:00.000Z",
        "SystemVersion": "1.0.0",
        "AppVersion": "2.0.0",
        "ModuleType": "A3",
        "ModuleVersion": "3.0.0",
        "ModuleExpireTime": "2026-07-15T09:30:00.000Z",
        "Status": "online",
        "SceneId": "scene001",
        "SceneName": "深圳南山门禁1号",
        "CreatedTime": "2025-01-01T00:00:00.000Z",
        "UpdatedTime": "2025-07-15T09:30:00.000Z"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

场景管理相关接口

创建场景

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于创建新场景，支持设置场景基本信息、绑定设备和核验规则。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreateScene。
Version	是	String	公共参数，本接口取值：2025-07-15。
SceneName	是	String	场景名称。
SceneGroupId	是	String	场景组Id。
DeviceSn	否	String	设备序列号。
VerifyRuleIdList	否	Array of String	核验规则Id列表。
SceneId	否	String	场景ID（可选，不传则自动生成）。
ScenarioStrategy	是	ScenarioStrategy	场景策略，见 ScenarioStrategy 枚举。

3. 输出参数

参数名称	类型	描述
SceneId	String	场景唯一标识。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateScene
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneName": "深圳南山门禁1号",
  "SceneGroupId": "scenegroup001",
  "DeviceSn": "device001",
  "VerifyRuleIdList": ["verifyrule001", "verifyrule002"],
  "ScenarioStrategy": "AccessOnDeviceRecognition50k"
}

输出示例

{
  "Response": {
    "SceneId": "scene001",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.SceneNameEmpty",
      "Message": "场景名称不能为空。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

修改场景

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于修改场景信息，支持更新场景的基本信息、绑定设备和核验规则。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：ModifyScene。
Version	是	String	公共参数，本接口取值：2025-07-15。
SceneId	是	String	场景Id。
SceneName	是	String	场景名称。
DeviceSn	否	String	设备序列号。
VerifyRuleIdList	否	Array of String	核验规则Id列表。
ScenarioStrategy	是	ScenarioStrategy	场景策略，见 ScenarioStrategy 枚举。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: ModifyScene
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneId": "scene001",
  "SceneName": "深圳南山门禁1号（已更新）",
  "DeviceSn": "device002",
  "VerifyRuleIdList": ["verifyrule001"],
  "ScenarioStrategy": "AccessOnDeviceRecognition50k"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.SceneNotExist",
      "Message": "场景不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

删除场景

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于删除指定场景，删除后场景数据将无法恢复。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DeleteScene。
Version	是	String	公共参数，本接口取值：2025-07-15。
SceneId	是	String	场景Id。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteScene
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneId": "scene001"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.SceneNotExist",
      "Message": "场景不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询场景详情

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询指定场景的详细信息。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeScene。
Version	是	String	公共参数，本接口取值：2025-07-15。
SceneId	是	String	场景Id。

3. 输出参数

参数名称	类型	描述
SceneId	String	场景ID。
SceneName	String	场景名称。
SceneGroupId	String	场景组ID。
SceneGroupName	String	场景组名称。
DeviceSn	String	关联设备SN。
DeviceName	String	关联设备名。
ScenarioStrategy	ScenarioStrategy	场景策略，见 ScenarioStrategy 枚举。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeScene
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneId": "scene001"
}

输出示例

{
  "Response": {
    "SceneId": "scene001",
    "SceneName": "深圳南山门禁1号",
    "SceneGroupId": "scenegroup001",
    "SceneGroupName": "深圳南山区域",
    "DeviceSn": "device001",
    "DeviceName": "深圳南山门禁设备",
    "ScenarioStrategy": "AccessOnDeviceRecognition50k",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.SceneNotExist",
      "Message": "场景不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

创建场景组

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于创建新场景组，支持设置场景组基本信息和父场景组。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreateSceneGroup。
Version	是	String	公共参数，本接口取值：2025-07-15。
SceneGroupName	是	String	场景组名称。
ParentSceneGroupId	是	String	父场景组Id。

3. 输出参数

参数名称	类型	描述
SceneGroupId	String	场景组唯一标识。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateSceneGroup
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneGroupName": "深圳南山区域",
  "ParentSceneGroupId": "scene_group_root"
}

输出示例

{
  "Response": {
    "SceneGroupId": "scenegroup001",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.SceneGroupNameEmpty",
      "Message": "场景组名称不能为空。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

修改场景组

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于修改场景组信息，支持更新场景组的基本信息。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：ModifySceneGroup。
Version	是	String	公共参数，本接口取值：2025-07-15。
SceneGroupId	是	String	场景组Id。
SceneGroupName	是	String	场景组名称。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: ModifySceneGroup
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneGroupId": "scenegroup001",
  "SceneGroupName": "深圳南山区域（已更新）"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.SceneGroupNotExist",
      "Message": "场景组不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

删除场景组

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于删除指定场景组，删除后场景组数据将无法恢复。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DeleteSceneGroup。
Version	是	String	公共参数，本接口取值：2025-07-15。
SceneGroupId	是	String	场景组Id。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteSceneGroup
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneGroupId": "scenegroup001"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.SceneGroupNotExist",
      "Message": "场景组不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询场景列表

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询场景列表，支持多条件过滤、分页。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeSceneList。
Version	是	String	公共参数，本接口取值：2025-07-15。
SceneIdList	否	Array of String	场景ID列表，精确匹配，支持批量查询。
SceneName	否	String	场景名称，支持模糊搜索。
SceneGroupId	否	String	场景组ID，筛选属于指定场景组的场景。
DeviceSn	否	String	设备序列号，精确匹配。
VerifyRuleId	否	String	核验规则ID，筛选绑定了指定规则的场景。
Offset	否	Integer	偏移量，默认0。
Limit	否	Integer	返回数量，默认20，最大100。

3. 输出参数

参数名称	类型	描述
TotalCount	Integer	符合条件的场景总数。
SceneList	Array of DescribeSceneListResponseSceneItem	场景信息列表，参见 DescribeSceneListResponseSceneItem 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeSceneList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneName": "门禁",
  "Offset": 0,
  "Limit": 20
}

输出示例

{
  "Response": {
    "TotalCount": 1,
    "SceneList": [
      {
        "SceneId": "scene001",
        "SceneName": "深圳南山门禁1号",
        "SceneGroupId": "sg001",
        "SceneGroupName": "深圳南山区域",
        "DeviceSn": "SN001",
        "DeviceName": "深圳南山门禁设备",
        "ScenarioStrategy": "AccessOnDeviceRecognition50k",
        "VerifyRuleIdList": ["vr_001"],
        "CreatedTime": "2025-01-01T00:00:00.000Z",
        "UpdatedTime": "2025-07-15T09:30:00.000Z"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询场景组列表

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询场景组列表，支持多条件过滤、分页。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeSceneGroupList。
Version	是	String	公共参数，本接口取值：2025-07-15。
SceneGroupIdList	否	Array of String	场景组ID列表，精确匹配，支持批量查询。
SceneGroupName	否	String	场景组名称，支持模糊搜索。
ParentSceneGroupId	否	String	父级场景组ID。传入时仅返回该父级下的直属子场景组；不传则返回全部场景组。
Offset	否	Integer	偏移量，默认0。
Limit	否	Integer	返回数量，默认20，最大100。

3. 输出参数

参数名称	类型	描述
TotalCount	Integer	符合条件的场景组总数。
SceneGroupList	Array of DescribeSceneGroupListResponseSceneGroupItem	场景组信息列表，参见 DescribeSceneGroupListResponseSceneGroupItem 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeSceneGroupList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "ParentSceneGroupId": "sg_root",
  "Offset": 0,
  "Limit": 20
}

输出示例

{
  "Response": {
    "TotalCount": 1,
    "SceneGroupList": [
      {
        "SceneGroupId": "sg001",
        "SceneGroupName": "深圳南山区域",
        "ParentSceneGroupId": "sg_root",
        "ParentSceneGroupName": "全部场景组",
        "SceneCount": 3,
        "ChildGroupCount": 1,
        "CreatedTime": "2025-01-01T00:00:00.000Z",
        "UpdatedTime": "2025-07-15T09:30:00.000Z"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

核验记录相关接口

创建核验记录

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于创建核验记录。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreateVerificationRecord。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	是	String	用户ID。
VerificationTime	是	Timestamp	核验时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
VerificationMedium	是	VerificationMedium	核验介质。
DeviceSn	是	String	设备SN。
VerifierId	否	String	核验人ID。
VerifierName	否	String	核验人名。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateVerificationRecord
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "VerificationTime": "2024-07-15T09:30:15.500Z",
  "VerificationMedium": "palm",
  "DeviceSn": "device001",
  "VerifierId": "verifier001",
  "VerifierName": "李四"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.UserIdEmpty",
      "Message": "用户ID不能为空。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询核验记录列表

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询核验记录列表，支持多条件过滤、分页。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeVerificationRecordList。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	否	String	用户ID。
UserName	否	String	用户名。
VerificationMedium	否	VerificationMedium	核验介质。
DeviceSn	否	String	设备SN。
SceneId	否	String	场景ID。
StartTime	否	Timestamp	核验开始时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
EndTime	否	Timestamp	核验结束时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
SceneGroupIds	否	Array of String	场景组ID列表，精确匹配（含子场景组展开）。
SceneGroupName	否	String	场景组名称，模糊搜索。
Offset	否	Integer	偏移量，默认0。
Limit	否	Integer	返回数量，默认20，最大100。
OrderBy	否	OrderBy	排序条件，参见 OrderBy 结构。

3. 输出参数

参数名称	类型	描述
TotalCount	Integer	符合条件的核验记录数量。
VerificationRecordList	Array of DescribeVerificationRecordListResponseVerificationRecord	核验记录列表，参见 DescribeVerificationRecordListResponseVerificationRecord 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeVerificationRecordList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "UserName": "张三",
  "VerificationMedium": "palm",
  "DeviceSn": "device001",
  "StartTime": "2024-06-01T00:00:00+08:00",
  "EndTime": "2024-06-30T23:59:59+08:00",
  "Offset": 0,
  "Limit": 10
}

输出示例

{
  "Response": {
    "TotalCount": 2,
    "VerificationRecordList": [
      {
        "UserId": "user001",
        "UserName": "张三",
        "VerificationTime": "2024-06-10T09:15:00+08:00",
        "VerificationMedium": "palm",
        "DeviceSn": "device001",
        "SceneId": "scene001",
        "SceneName": "深圳南山门禁1号",
        "VerifierId": "verifier001",
        "VerifierName": "李四"
      },
      {
        "UserId": "user001",
        "UserName": "张三",
        "VerificationTime": "2024-06-11T18:30:00+08:00",
        "VerificationMedium": "palm",
        "DeviceSn": "device002",
        "SceneId": "scene002",
        "SceneName": "深圳南山门禁2号",
        "VerifierId": "verifier002",
        "VerifierName": "王五"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.FiltersLimitExceed",
      "Message": "过滤器个数超过限制"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询核验记录推送专用

1. 接口描述

接口推送域名：由客户提供给平台，平台主动推送

接口说明：用于接收开放平台推送的核验记录信息。该接口只支持推送，不支持主动拉取。

推送内容即为核验记录详情（见下表），客户收到推送后返回HTTP 200 OK即可。

2. 推送内容（参数结构）

参数名称	类型	描述
UserId	String	用户ID
UserName	String	用户名
VerificationTime	Timestamp	核验时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
VerificationMedium	VerificationMedium	核验介质
DeviceSn	String	设备SN
SceneId	String	场景ID
SceneName	String	场景名称
VerifierId	String	核验人ID
VerifierName	String	核验人名
RequestId	String	唯一请求ID

3. 推送示例

POST / HTTP/1.1
Host: <客户推送地址域名>
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateVerificationRecord

{
  "UserId": "user001",
  "UserName": "张三",
  "VerificationTime": "2024-07-15T09:30:15.500Z",
  "VerificationMedium": "palm",
  "DeviceSn": "device001",
  "SceneId": "scene001",
  "SceneName": "深圳南山门禁1号",
  "VerifierId": "verifier001",
  "VerifierName": "李四",
  "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
}

客户收到推送后返回HTTP 200 OK即可，无需返回业务数据。

核验规则相关接口

创建核验规则

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于创建核验规则，支持配置时间规则、用户规则，并可绑定多个场景。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreateVerifyRule。
Version	是	String	公共参数，本接口取值：2025-07-15。
VerifyRuleName	是	String	核验规则名称。
EnableTimeRule	是	Boolean	是否启用时间规则，false表示不启用，true表示启用。
TimeRule	否	TimeRule	时间规则，启用时间规则时需配置，参见 TimeRule 结构。
EnableUserRule	是	Boolean	是否启用用户规则，false表示所有用户，true表示指定用户。
UserRule	否	UserRule	用户规则，启用用户规则时需配置，参见 UserRule 结构。
EnableWebhookRule	否	Boolean	是否启用Webhook规则，可选，不传默认为true。
BindSceneIdList	否	Array of String	绑定场景ID列表，可绑定多个场景。

3. 输出参数

参数名称	类型	描述
VerifyRuleId	String	核验规则ID。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateVerifyRule
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "VerifyRuleName": "工作日早晚高峰",
  "EnableTimeRule": true,
  "TimeRule": {
    "AllowDateRange": {
      "StartDate": {"Year": 2025, "Month": 1, "Day": 1},
      "EndDate": {"Year": 2025, "Month": 12, "Day": 31}
    },
    "AllowDayOfWeekList": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"],
    "AllowTimePeriodList": [
      {
        "StartTime": {"Hours": 7, "Minutes": 30, "Seconds": 0},
        "EndTime": {"Hours": 9, "Minutes": 30, "Seconds": 0},
        "MaxVerificationCount": 0
      },
      {
        "StartTime": {"Hours": 17, "Minutes": 30, "Seconds": 0},
        "EndTime": {"Hours": 20, "Minutes": 0, "Seconds": 0},
        "MaxVerificationCount": 0
      }
    ]
  },
  "EnableUserRule": true,
  "UserRule": {
    "UserTags": [
      {"UserTagId": "tag001", "UserTagName": "研发中心"}
    ],
    "UserInfos": [
      {"UserId": "user001", "UserName": "张三"}
    ]
  },
  "EnableWebhookRule": false,
  "BindSceneIdList": ["scene001", "scene002"]
}

输出示例

{
  "Response": {
    "VerifyRuleId": "vr_20250715001",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

修改核验规则

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于修改已有的核验规则信息。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：ModifyVerifyRule。
Version	是	String	公共参数，本接口取值：2025-07-15。
VerifyRuleId	是	String	核验规则全局唯一ID。
VerifyRuleName	是	String	核验规则名称。
EnableTimeRule	是	Boolean	是否启用时间规则。
TimeRule	否	TimeRule	时间规则，参见 TimeRule 结构。
EnableUserRule	是	Boolean	是否启用用户规则。
UserRule	否	UserRule	用户规则，参见 UserRule 结构。
EnableWebhookRule	是	Boolean	是否启用Webhook规则。
BindSceneIdList	否	Array of String	绑定场景ID列表。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: ModifyVerifyRule
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "VerifyRuleId": "vr_20250715001",
  "VerifyRuleName": "工作日高峰与中午",
  "EnableTimeRule": true,
  "TimeRule": {
    "AllowDayOfWeekList": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"],
    "AllowTimePeriodList": [
      {"StartTime": {"Hours": 7, "Minutes": 30, "Seconds": 0}, "EndTime": {"Hours": 9, "Minutes": 30, "Seconds": 0}},
      {"StartTime": {"Hours": 12, "Minutes": 0, "Seconds": 0}, "EndTime": {"Hours": 13, "Minutes": 30, "Seconds": 0}},
      {"StartTime": {"Hours": 17, "Minutes": 30, "Seconds": 0}, "EndTime": {"Hours": 20, "Minutes": 0, "Seconds": 0}}
    ]
  },
  "EnableUserRule": false,
  "EnableWebhookRule": true,
  "BindSceneIdList": ["scene001"]
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

删除核验规则

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于删除指定的核验规则。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DeleteVerifyRule。
Version	是	String	公共参数，本接口取值：2025-07-15。
VerifyRuleId	是	String	核验规则ID。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteVerifyRule
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "VerifyRuleId": "vr_20250715001"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询核验规则

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询指定核验规则的详细配置。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeVerifyRule。
Version	是	String	公共参数，本接口取值：2025-07-15。
VerifyRuleId	是	String	核验规则ID。

3. 输出参数

参数名称	类型	描述
VerifyRuleId	String	核验规则ID。
VerifyRuleName	String	核验规则名称。
EnableTimeRule	Boolean	是否启用时间规则。
TimeRule	TimeRule	时间规则，参见 TimeRule 结构。
EnableUserRule	Boolean	是否启用用户规则。
UserRule	UserRule	用户规则，参见 UserRule 结构。
EnableWebhookRule	Boolean	是否启用Webhook规则。
BindSceneIdList	Array of String	绑定场景ID列表。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeVerifyRule
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "VerifyRuleId": "vr_20250715001"
}

输出示例

{
  "Response": {
    "VerifyRuleId": "vr_20250715001",
    "VerifyRuleName": "工作日早晚高峰",
    "EnableTimeRule": true,
    "TimeRule": {
      "AllowDateRange": {
        "StartDate": {
          "Year": 2025,
          "Month": 1,
          "Day": 1
        },
        "EndDate": {
          "Year": 2025,
          "Month": 12,
          "Day": 31
        }
      },
      "DisallowDateList": [
        {
          "Year": 2025,
          "Month": 5,
          "Day": 1
        }
      ],
      "AllowDayOfWeekList": [
        "MONDAY",
        "TUESDAY",
        "WEDNESDAY",
        "THURSDAY",
        "FRIDAY"
      ],
      "AllowTimePeriodList": [
        {
          "StartTime": {
            "Hours": 7,
            "Minutes": 30,
            "Seconds": 0
          },
          "EndTime": {
            "Hours": 9,
            "Minutes": 30,
            "Seconds": 0
          },
          "MaxVerificationCount": 0
        },
        {
          "StartTime": {
            "Hours": 17,
            "Minutes": 30,
            "Seconds": 0
          },
          "EndTime": {
            "Hours": 20,
            "Minutes": 0,
            "Seconds": 0
          },
          "MaxVerificationCount": 0
        }
      ]
    },
    "EnableUserRule": true,
    "UserRule": {
      "UserTags": [
        {
          "UserTagId": "tag001",
          "UserTagName": "研发中心"
        }
      ],
      "UserInfos": [
        {
          "UserId": "user001",
          "UserName": "张三"
        }
      ]
    },
    "EnableWebhookRule": false,
    "BindSceneIdList": [
      "scene001",
      "scene002"
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询核验规则列表

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询核验规则列表，支持多条件过滤、分页。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeVerifyRuleList。
Version	是	String	公共参数，本接口取值：2025-07-15。
VerifyRuleIdList	否	Array of String	核验规则ID列表，精确匹配，支持批量查询。
VerifyRuleName	否	String	核验规则名称，支持模糊搜索。
Offset	否	Integer	偏移量，默认0。
Limit	否	Integer	返回数量，默认20，最大100。

3. 输出参数

参数名称	类型	描述
TotalCount	Integer	符合条件的核验规则总数。
VerifyRuleList	Array of DescribeVerifyRuleListResponseVerifyRuleItem	核验规则列表，参见 DescribeVerifyRuleListResponseVerifyRuleItem 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeVerifyRuleList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "VerifyRuleName": "工作日",
  "Offset": 0,
  "Limit": 20
}

输出示例

{
  "Response": {
    "TotalCount": 1,
    "VerifyRuleList": [
      {
        "VerifyRuleId": "vr_20250715001",
        "VerifyRuleName": "工作日早晚高峰",
        "EnableTimeRule": true,
        "TimeRule": {
          "AllowDayOfWeekList": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"],
          "AllowTimePeriodList": [
            {"StartTime": {"Hours": 7, "Minutes": 30, "Seconds": 0}, "EndTime": {"Hours": 9, "Minutes": 30, "Seconds": 0}, "MaxVerificationCount": 0}
          ]
        },
        "EnableUserRule": false,
        "EnableWebhookRule": true,
        "BindSceneIdList": ["scene001"],
        "CreatedTime": "2025-01-01T00:00:00.000Z",
        "UpdatedTime": "2025-07-15T09:30:00.000Z"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

校验访问权限

1. 接口描述

接口回调域名：由客户提供给平台，平台主动调用

接口说明：用于检查用户的访问权限。该接口只支持回调，不支持主动拉取 ，需提前将回调地址提供给平台，由平台主动调用。平台发送访问权限校验请求，客户根据自有规则判断后返回是否允许通行及原因。

2. 输入参数

参数名称	类型	描述
UserId	String	用户ID
UserName	String	用户名
VerificationTime	Timestamp	核验时间，RFC3339字符串格式，如"2025-07-03T09:30:15.500Z"
VerificationMedium	VerificationMedium	核验介质
DeviceSn	String	设备SN
SceneId	String	场景ID
SceneName	String	场景名称

3. 输出参数

参数名称	类型	描述
Allowed	Boolean	是否允许通行
Reason	String	通行原因描述，如"命中核验规则：访客预约通行"
RequestId	String	唯一请求ID。每次请求都会返回RequestId。

4. 请求和响应示例

请求示例

POST / HTTP/1.1
Host: <客户回调地址域名>
Content-Type: application/json; charset=utf-8
X-TC-Action: CheckAccessPermission

{
  "UserId": "user001",
  "UserName": "张三",
  "VerificationTime": "2025-07-15T09:30:15.500Z",
  "VerificationMedium": "palm",
  "DeviceSn": "device001",
  "SceneId": "scene001",
  "SceneName": "深圳南山门禁1号"
}

响应示例（允许通行）

{
  "Response": {
    "Allowed": true,
    "Reason": "命中核验规则：访客预约通行",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

响应示例（拒绝通行）

{
  "Response": {
    "Allowed": false,
    "Reason": "用户未在允许时间范围内",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

扫码录掌相关接口

扫码录掌服务，适合开放用户注册场景。

二维码由刷掌设备生成，用户录掌后，刷掌设备会展示二维码，二维码会携带用户信息，用户扫码后，会通知给应用服务器，应用服务器根据用户信息进行用户注册。二维码扫码获得的URL示例：https://app.intl.palm.tencent.com/local_h5/brushAuth?ocode=***&session_id=***&session_key=***&app_id=***&access_token=***

扫码事件通知

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于通知服务端用户扫码事件。本接口仅验证Token，不验证签名，HTTP头部不需要Authorization字段。

默认接口请求频率限制：20次/秒/AppId。

注意：本接口需要在HTTP请求头中提供X-Palm-Appid字段和X-Palm-Openapi-Token字段，来源于扫码URL中的app_id/access_token参数，可重复使用，直至令牌过期。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：NotifyQrCodeScanEvent。
Version	是	String	公共参数，本接口取值：2025-07-15。
SessionId	是	String	会话ID
EventType	否	NotifyQrCodeScanEventRequestQrCodeScanEventType	事件类型，参见 NotifyQrCodeScanEventRequestQrCodeScanEventType 枚举，不传时等同于 scanned。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求ID。每次请求都会返回RequestId。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: NotifyQrCodeScanEvent
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: app_001
X-Palm-Openapi-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "SessionId": "session_001"
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

扫码绑定掌纹

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于扫码绑定掌纹。本接口仅验证Token，不验证签名，HTTP头部不需要Authorization字段。

默认接口请求频率限制：20次/秒/AppId。

注意：本接口需要在HTTP请求头中提供X-Palm-Appid字段和X-Palm-Openapi-Token字段，来源于扫码URL中的app_id/access_token参数，可重复使用，直至令牌过期。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：BindQrCodeScanPalm。
Version	是	String	公共参数，本接口取值：2025-07-15。
SessionId	是	String	会话ID
UserId	是	String	用户唯一标识
UserName	是	String	用户名称
ReplacePalm	否	Boolean	是否替换手掌

3. 输出参数

参数名称	类型	描述
UserSessionId	String	用户会话ID
RequestId	String	唯一请求ID。每次请求都会返回RequestId。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: BindQrCodeScanPalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: app_001
X-Palm-Openapi-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "SessionId": "session_001",
  "UserId": "user001",
  "UserName": "张三",
  "ReplacePalm": false
}

输出示例

{
  "Response": {
    "UserSessionId": "user_session_001",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询扫码录掌用户信息

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询扫码录掌用户信息。本接口仅验证Token，不验证签名，HTTP头部不需要Authorization字段。

默认接口请求频率限制：20次/秒/AppId。

注意：本接口需要在HTTP请求头中提供X-Palm-Appid字段和X-Palm-Openapi-Token字段，来源于扫码URL中的app_id/access_token参数，可重复使用，直至令牌过期。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeQrCodeScanUser。
Version	是	String	公共参数，本接口取值：2025-07-15。
SessionId	是	String	会话ID
UserId	是	String	用户唯一标识

3. 输出参数

参数名称	类型	描述
UserId	String	用户唯一标识
PalmState	PalmState	主掌录掌状态
UserName	String	用户名称
UserState	UserState	用户状态，见 UserState 枚举。
PalmDirection	PalmDirection	主掌方向，见 PalmDirection 枚举。
LeftPalm	PalmInfo	左掌录掌信息，参见 PalmInfo 结构。
RightPalm	PalmInfo	右掌录掌信息，参见 PalmInfo 结构。
PhoneNo	String	手机号（带区号）。
RequestId	String	唯一请求ID。每次请求都会返回RequestId。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeQrCodeScanUser
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: app_001
X-Palm-Openapi-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "SessionId": "session_001",
  "UserId": "user001"
}

输出示例

{
  "Response": {
    "UserId": "user001",
    "PalmState": "registered",
    "UserName": "张三",
    "UserState": "right_valid",
    "PalmDirection": "right",
    "RightPalm": {
      "PalmState": "registered",
      "RegisterType": "device",
      "PreRegisterTime": "2025-06-01T10:00:00.000Z",
      "RegisterTime": "2025-06-01T10:05:00.000Z",
      "ExpireTime": "2026-06-01T10:05:00.000Z"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

创建扫码录掌会话

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：创建一个扫码录掌会话，用于生成用于用户扫码录掌的二维码或 URL。支持扫码录掌（scan_register）、滴码录掌（tap_register）、滴码加验（tap_verify）三种会话用途。本接口仅验证Token，不验证签名，HTTP头部不需要Authorization字段。

默认接口请求频率限制：20次/秒/AppId。

注意：本接口需要在HTTP请求头中提供X-Palm-Appid字段和X-Palm-Openapi-Token字段，来源于扫码URL中的app_id/access_token参数，可重复使用，直至令牌过期。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreateQrCodeScanSession。
Version	是	String	公共参数，本接口取值：2025-07-15。
Ttl	否	String	会话期望生命周期。scan_register/tap_register 场景生效，tap_verify 场景由租户配置决定（此字段不生效）。不指定时 scan_register 默认 1 小时，tap_register 默认 15 分钟。最长 24 小时。字符串格式，如"3600s"。
ResponseFormat	否	ResponseFormat	响应数据格式，可选 metadata（默认、返回元数据）、url（返回二维码 URL）、image（返回二维码图片）。
PalmDirection	否	PalmDirection	掌方向，指定本次录掌的手掌方向。
QrCodeSessionType	否	QrCodeSessionType	会话用途。不传或传 scan_register 时为扫码录掌（默认行为）；tap_register 为滴码录掌；tap_verify 为滴码加验。
UserId	否	String	用户ID，tap_register/tap_verify 场景必填。
UserName	否	String	用户名，tap_register 场景必填，tap_verify 场景可选。
PhoneNo	否	String	手机号，滴码录掌场景可选，传入时会校验与后台用户手机号是否一致。

3. 输出参数

参数名称	类型	描述
SessionId	String	会话ID。
ExpireTime	Timestamp	会话过期时间，RFC3339字符串格式，如"2025-07-03T09:30:15.500Z"。
AppId	String	应用ID，后续该会话的扫码录掌请求需在HTTP请求头"X-Palm-Appid"中携带。
AccessToken	String	访问令牌，后续该会话的扫码录掌请求需在HTTP请求头"X-Palm-Openapi-Token"中携带。
AccessTokenExpireTime	Timestamp	令牌过期时间，RFC3339字符串格式，如"2025-07-03T09:30:15.500Z"。
SessionUrl	String	会话 URL。scan_register 场景为完整 H5 链接；tap_register/tap_verify 场景为会话标识。仅当 ResponseFormat=url 时返回。
SessionImage	String	会话二维码图片（base64编码的二进制数据），仅当 ResponseFormat=image 时返回。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateQrCodeScanSession
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************

{
  "Ttl": "3600s",
  "ResponseFormat": "metadata",
  "PalmDirection": "right",
  "QrCodeSessionType": "scan_register"
}

输出示例

{
  "Response": {
    "SessionId": "session_001",
    "ExpireTime": "2025-07-03T10:30:15.500Z",
    "AppId": "app_001",
    "AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "AccessTokenExpireTime": "2025-07-03T10:30:15.500Z",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询扫码录掌会话状态

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于查询扫码录掌会话状态。本接口仅验证Token，不验证签名，HTTP头部不需要Authorization字段。

默认接口请求频率限制：20次/秒/AppId。

注意：本接口需要在HTTP请求头中提供X-Palm-Appid字段和X-Palm-Openapi-Token字段，来源于扫码URL中的app_id/access_token参数，可重复使用，直至令牌过期。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeQrCodeScanSession。
Version	是	String	公共参数，本接口取值：2025-07-15。
SessionId	是	String	会话ID。

3. 输出参数

参数名称	类型	描述
QrCodeScanState	QrCodeScanState	二维码扫码状态。
UserId	String	用户唯一标识。
UserName	String	用户名称。
ReplacePalm	Boolean	是否替换手掌。
PalmDirection	PalmDirection	掌方向。
QrCodeSessionType	QrCodeSessionType	会话用途，设备端根据此字段区分是扫码录掌、滴码录掌还是滴码加验场景。
PhoneNo	String	手机号（带区号）。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeQrCodeScanSession
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: app_001
X-Palm-Openapi-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "SessionId": "session_001"
}

输出示例

{
  "Response": {
    "QrCodeScanState": "scanned",
    "UserId": "user001",
    "UserName": "张三",
    "ReplacePalm": false,
    "PalmDirection": "right",
    "QrCodeSessionType": "scan_register",
    "PhoneNo": "+8613800138000",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

PalmMa 登录相关接口

发送短信验证码

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于向指定手机号发送短信验证码。本接口为开放接口，不验证Token，不验证签名，HTTP头部不需要Authorization、X-Palm-Openapi-Token字段。

默认接口请求频率限制：20次/秒/AppId。

注意：本接口需要在HTTP请求头中提供X-Palm-Appid字段。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：SendPalmMaSmsCode。
Version	是	String	公共参数，本接口取值：2025-07-15。
PhoneNo	是	String	手机号（带区号）。

3. 输出参数

参数名称	类型	描述
SessionId	String	会话ID，用于后续验证码校验。
ExpireTime	Timestamp	会话过期时间，RFC3339字符串格式，如"2025-07-03T09:30:15.500Z"。
ResendInterval	String	会话验证码重发间隔，如"60s"。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: SendPalmMaSmsCode
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223

{
  "PhoneNo": "+8613800138000"
}

输出示例

{
  "Response": {
    "SessionId": "sess_1234567890abcdef",
    "ExpireTime": "2025-07-03T09:40:15.500Z",
    "ResendInterval": "60s",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

短信验证码登录

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：用于通过短信验证码进行用户登录，登录成功后返回访问令牌和刷新令牌。本接口为开放接口，不验证Token，不验证签名，HTTP头部不需要Authorization、X-Palm-Openapi-Token字段。

默认接口请求频率限制：20次/秒/AppId。

注意：本接口需要在HTTP请求头中提供X-Palm-Appid字段。验证码只能使用一次，SessionId验证成功后立即失效。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：LoginPalmMaSmsCode。
Version	是	String	公共参数，本接口取值：2025-07-15。
SmsCode	否	String	短信验证码（每次都需要验证，验证码只能使用一次）。若部署时未配置短信能力，则无需传入该字段。
SessionId	否	String	发送验证码时返回的SessionId（一次性使用，验证成功后立即失效）。若部署时未配置短信能力，则无需传入该字段。
UserId	是	String	用户ID。
PhoneNo	否	String	手机号（带区号），用于与后台用户绑定的手机号校验，不传则跳过校验。
GrantType	否	GrantType	授权类型。调用刷掌业务平台开放接口时，必须使用 `client_credential`。取值枚举： - client_credential_user：适用于第三方平台接入空中开掌 SDK 场景，即： a. 移动端使用 SDK 发起注册或获取活体视频上传地址流程； b. 第三方服务端需根据指定用户申请访问凭证，供 SDK 使用； c. 此时必须同时传入 `UserId` 字段。 - client_credential：适用于普通服务端调用开放接口场景，即： a. 此类型下不绑定具体用户，仅使用应用级密钥获取访问凭证； b. `UserId` 字段无需传入。默认不传为 `client_credential_user` 类型。见 GrantType 枚举。

3. 输出参数

参数名称	类型	描述
AccessToken	String	访问令牌（短期有效，如2小时），当前会话后续请求需要在HTTP请求头"X-Palm-Openapi-Token"中携带该令牌。
AccessTokenExpireTime	Timestamp	访问令牌过期时间，RFC3339字符串格式，如"2025-07-03T09:30:15.500Z"。
RefreshToken	String	刷新令牌（长期有效，如30天），用于刷新访问令牌。
RefreshTokenExpireTime	Timestamp	刷新令牌过期时间，RFC3339字符串格式，如"2025-07-03T09:30:15.500Z"。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: LoginPalmMaSmsCode
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223

{
  "SmsCode": "123456",
  "SessionId": "sess_1234567890abcdef",
  "UserId": "user001",
  "GrantType": "client_credential"
}

输出示例

{
  "Response": {
    "AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "AccessTokenExpireTime": "2025-07-03T11:30:15.500Z",
    "RefreshToken": "refresh_token_xxx",
    "RefreshTokenExpireTime": "2025-08-02T09:30:15.500Z",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

掌纹管理相关接口（刷掌算法平台）

创建掌纹

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：上传掌图创建掌纹并返回掌纹Id，双因子认证。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreatePalm。
Version	是	String	公共参数，本接口取值：2025-07-15。
RgbImage	是	Image	Rgb图片数据，参见 Image 结构。
IrImage	是	Image	红外图片数据，参见 Image 结构。
PalmDirection	是	PalmPaasPalmDirection	手掌方向，参见 PalmPaasPalmDirection 枚举。1:左手 2:右手。

3. 输出参数

参数名称	类型	描述
PalmId	String	掌纹Id。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreatePalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "RgbImage": {
    "Data": "... 特征数据，需要base64",
    "ThreePointList": [
      {"PointX": 279.19387799999998, "PointY": 283.87393200000002},
      {"PointX": 355.835083, "PointY": 282.88299599999999},
      {"PointX": 429.38259900000003, "PointY": 321.33651700000001}
    ],
    "ImageType": 1
  },
  "IrImage": {
    "Data": "... 特征数据，需要base64",
    "ThreePointList": [
      {"PointX": 279.19387799999998, "PointY": 283.87393200000002},
      {"PointX": 355.835083, "PointY": 282.88299599999999},
      {"PointX": 429.38259900000003, "PointY": 321.33651700000001}
    ],
    "ImageType": 2
  },
  "PalmDirection": 1
}

输出示例

{
  "Response": {
    "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.PalmIdEmpty",
      "Message": "掌纹ID为空"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

绑定掌纹

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：将已创建的掌纹Id绑定到指定用户，双因子认证。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：BindPalm。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	是	String	用户唯一标识。
PalmId	是	String	掌纹Id。
IsForce	否	Boolean	是否强制换绑。
AlgorithmStrategy	否	AlgorithmStrategy	算法策略类型，参见 AlgorithmStrategy 枚举。

3. 输出参数

参数名称	类型	描述
PalmId	String	用户的掌纹Id。若用户已绑定掌纹信息，系统将自动更新现有掌纹数据（原掌纹Id保持不变），并返回该用户已注册的掌纹Id。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: BindPalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
  "IsForce": true,
  "AlgorithmStrategy": 2
}

输出示例

{
  "Response": {
    "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "用户不存在"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

空中开掌检索

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：上传RGB+IR掌图并1:N检索用户，并返回加验信息。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：SearchMobilePalm。
Version	是	String	公共参数，本接口取值：2025-07-15。
ProductVersion	否	String	刷掌产品算法版本，由对接产品提供，例如v20250715。
RgbImage	是	Image	Rgb图片数据，参见 Image 结构。
IrImage	否	Image	红外图片数据，用于后续的加验通过后补充到掌库，参见 Image 结构。
PalmDirection	是	PalmPaasPalmDirection	手掌方向，参见 PalmPaasPalmDirection 枚举。1:左手 2:右手。

3. 输出参数

参数名称	类型	描述
VerifyInfo	VerifyInfo	加验信息，参见 VerifyInfo 结构。
PalmId	String	掌纹Id。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: SearchMobilePalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "ProductVersion": "v20250715",
  "RgbImage": {
    "Data": "base64encodedRgbImageData...",
    "ImageType": 1,
    "ThreePointList": [
      {"PointX": 279.19387799999998, "PointY": 283.87393200000002},
      {"PointX": 355.835083, "PointY": 282.88299599999999},
      {"PointX": 429.38259900000003, "PointY": 321.33651700000001}
    ]
  },
  "IrImage": {
    "Data": "base64encodedIrImageData...",
    "ImageType": 2,
    "ThreePointList": [
      {"PointX": 279.19387799999998, "PointY": 283.87393200000002},
      {"PointX": 355.835083, "PointY": 282.88299599999999},
      {"PointX": 429.38259900000003, "PointY": 321.33651700000001}
    ]
  },
  "PalmDirection": 1
}

输出示例

{
  "Response": {
    "VerifyInfo": {
      "NeedVerify": true,
      "UserId": "user001",
      "VerifyId": "a1b2c3d4-5678-9abc-def0-1234567890ab",
      "VerifyType": 3,
      "HighSimilarityUserIdList": []
    },
    "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InternalError",
      "Message": "内部错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

用户加验

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：完成用户身份加验并绑定掌纹。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：Verify。
Version	是	String	公共参数，本接口取值：2025-07-15。
VerifyId	是	String	加验Id，来源：SearchMobilePalm返回的VerifyInfo.VerifyId。
UserId	是	String	加验的用户唯一标识。
VerifyResult	是	VerifyResult	加验结果，参见 VerifyResult 枚举。
AlgorithmStrategy	否	AlgorithmStrategy	算法策略类型，参见 AlgorithmStrategy 枚举。

3. 输出参数

参数名称	类型	描述
VerifyInfo	VerifyInfo	加验信息，当需要继续加验时返回，参见 VerifyInfo 结构。
PalmId	String	加验成功时返回该用户的掌纹Id。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: Verify
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "VerifyId": "a1b2c3d4-5678-9abc-def0-1234567890ab",
  "UserId": "user001",
  "VerifyResult": 1,
  "AlgorithmStrategy": 2
}

输出示例

{
  "Response": {
    "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

需要继续加验输出示例

{
  "Response": {
    "VerifyInfo": {
      "NeedVerify": true,
      "UserId": "user002",
      "VerifyId": "b2c3d4e5-6789-abcd-ef01-234567890abc",
      "VerifyType": 1,
      "HighSimilarityUserIdList": ["user003", "user004"]
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.UserIdEmpty",
      "Message": "用户ID为空"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

删除掌纹

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：删除指定用户的掌纹信息。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DeletePalm。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	是	String	用户唯一标识。
PalmDirectionList	是	Array of PalmPaasPalmDirection	掌纹方向的列表。可以同时传入左手和右手，或者单独的左手或者右手。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeletePalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "PalmDirectionList": [1, 2]
}

输出示例

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "用户不存在"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询掌纹

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：查询指定用户的掌纹信息。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribePalm。
Version	是	String	公共参数，本接口取值：2025-07-15。
UserId	是	String	用户唯一标识。
UserToken	否	String	用户Token，客户端Sdk通过Token查询。

3. 输出参数

参数名称	类型	描述
LeftPalm	PalmPaasPalmInfo	左手掌纹信息，参见 PalmPaasPalmInfo 结构。
RightPalm	PalmPaasPalmInfo	右手掌纹信息，参见 PalmPaasPalmInfo 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribePalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001"
}

输出示例

{
  "Response": {
    "LeftPalm": {
      "PalmState": 3,
      "PalmDirection": 1,
      "RegisterTime": 1700000000,
      "RegisterType": 1
    },
    "RightPalm": {
      "PalmState": 3,
      "PalmDirection": 2,
      "RegisterTime": 1700000100,
      "RegisterType": 1
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "用户不存在"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

同步掌纹特征

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：同步掌纹特征。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：SynchronizePalmFeature。
Version	是	String	公共参数，本接口取值：2025-07-15。
ProductVersion	是	String	需要同步的产品版本，比如v20250715，该版本号需要和设备上的版本号匹配。
QueryPosition	是	String	当前同步的位置。首次填空字符串，下一次使用响应里面的QueryPosition数据。
DeviceId	是	String	设备Id。目前的作用仅仅用于排查问题。
DisableFeature	否	Boolean	禁止返回feature值，默认为false返回，为true不返回。
Operations	否	Array of PalmPaasOperation	按操作类型过滤，为空时不过滤返回所有状态，例如传[1]则只返回新增特征事件。参见 PalmPaasOperation 枚举。

3. 输出参数

参数名称	类型	描述
PalmFeatureDetailList	Array of PalmFeatureDetail	掌纹特征详情列表，参见 PalmFeatureDetail 结构。
HasMore	HasMoreType	是否有更多数据，参见 HasMoreType 枚举。1:没有数据了 2:还有数据，可以继续同步；未来可能还有别的状态，如果新增，文档会同步更新。
QueryPosition	String	当前同步的位置。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: SynchronizePalmFeature
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "ProductVersion": "v1.0",
  "QueryPosition": "",
  "DeviceId": "X8AZ112D4646978SKAP3ZX3",
  "DisableFeature": false
}

输出示例

{
  "Response": {
    "PalmFeatureDetailList": [
      {
        "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
        "Status": 1,
        "ImageType": 1,
        "Feature": {
          "FeatureValue": "... 特征数据，需要base64",
          "FeatureType": 1,
          "FeatureDigest": "md5hash",
          "FeatureDimension": 128
        },
        "PalmDirection": 1,
        "PalmDataVersion": 100,
        "UserId": "user001",
        "Operation": 1
      }
    ],
    "HasMore": 2,
    "QueryPosition": "position_abc",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

查询产品版本列表

1. 接口描述

接口请求域名：open.intl.palm.tencent.com

接口说明：查询产品版本列表。

默认接口请求频率限制：20次/秒/AppId。

2. 输入参数

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeVersionList。
Version	是	String	公共参数，本接口取值：2025-07-15。
ProductName	是	String	产品名，标准版固定填：standard。

3. 输出参数

参数名称	类型	描述
VersionList	Array of ProductVersionInfo	版本信息列表，参见 ProductVersionInfo 结构。
RequestId	String	唯一请求 ID，每次请求都会返回。

4. 示例

输入示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeVersionList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "ProductName": "standard"
}

输出示例

{
  "Response": {
    "VersionList": [
      {
        "ProductVersion": "v20250715",
        "ProductVersionCreateTime": 1700000000,
        "Status": 1,
        "OldProductName": ""
      },
      {
        "ProductVersion": "v20250801",
        "ProductVersionCreateTime": 1700100000,
        "Status": 2,
        "OldProductName": "standard_v1"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

错误输出示例

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

数据结构

公共业务结构

PalmInfo

单掌录掌信息。

名称	类型	描述
PalmState	PalmState	手掌状态。
RegisterType	RegisterType	注册方式。
PreRegisterTime	Timestamp	空中录掌时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
RegisterTime	Timestamp	完成录掌时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
ExpireTime	Timestamp	掌纹过期时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。

TimeRule

名称	类型	描述
AllowDateRange	DateRange	可核验日期范围，空表示不限制
DisallowDateList	Date[]	不可核验日期列表
AllowDayOfWeekList	DayOfWeek[]	每周有效日
AllowTimePeriodList	TimePeriod[]	每日允许通行时间段

DateRange

名称	类型	描述
StartDate	Date	开始日期
EndDate	Date	结束日期

Date

名称	类型	描述
Year	Integer	年
Month	Integer	月
Day	Integer	日

TimeOfDay

名称	类型	描述
Hours	Integer	小时
Minutes	Integer	分钟
Seconds	Integer	秒

TimePeriod

名称	类型	描述
StartTime	TimeOfDay	开始时间
EndTime	TimeOfDay	结束时间
MaxVerificationCount	Integer	可核验次数，0表示不限制

UserRule

名称	类型	描述
UserTags	UserTagInfo[]	用户标签列表
UserInfos	UserInfo[]	用户信息列表

UserTagInfo

名称	类型	描述
UserTagId	String	用户标签唯一标识
UserTagName	String	用户标签名称

UserInfo

名称	类型	描述
UserId	String	用户唯一标识
UserName	String	用户名称

OrderBy

排序条件。

名称	类型	描述
Field	VerificationRecordOrderField	排序字段
Order	SortOrder	排序方向

Image

图片。

名称	类型	描述
Data	String	图片的数据，需要base64。
ThreePointList	Array of Pointf	三点数据。
ImageType	ImageType	图片类型，参见 ImageType 枚举。
DataDigest	String	针对图片数据计算Md5。

Pointf

点。

名称	类型	描述
PointX	Float	X轴坐标。
PointY	Float	Y轴坐标。

Feature

特征。

名称	类型	描述
FeatureValue	String	特征值。
FeatureType	FeatureType	特征类型，参见 FeatureType 枚举。
FeatureDigest	String	特征签名。
FeatureDimension	Integer	特征值的维度。

VerifyInfo

加验信息。

名称	类型	描述
NeedVerify	Boolean	是否需要加验。只有此处返回true，VerifyInfo信息才有意义。
UserId	String	加验的用户Id。
VerifyId	String	加验Id。
VerifyType	VerifyType	加验类型，参见 VerifyType 枚举。
HighSimilarityUserIdList	Array of String	加验类型为高相似加验时返回，表示需要加验的高相似用户Id列表。

PalmFeatureDetail

掌纹特征详情。

名称	类型	描述
PalmId	String	掌纹Id。
Status	PalmStatus	掌纹状态，参见 PalmStatus 枚举。
ImageType	ImageType	图片类型，参见 ImageType 枚举。
Feature	Feature	特征，参见 Feature 结构。
PalmDirection	PalmPaasPalmDirection	掌纹方向，参见 PalmPaasPalmDirection 枚举。
PalmDataVersion	Integer	数据版本。每条数据记录都包含一个版本号字段，采用单调递增的整数版本标识。当数据内容发生变更时，其版本号会自动递增。在数据同步过程中，系统采用版本比对机制：仅当本地存储的版本号严格大于同步获取的版本号时，才需要覆盖本地的数据。
UserId	String	用户Id。
Operation	PalmPaasOperation	操作类型，参见 PalmPaasOperation 枚举。

ProductVersionInfo

产品版本信息。

名称	类型	描述
ProductVersion	String	刷掌产品算法版本，由对接产品提供，例如v20250715。
ProductVersionCreateTime	Integer	产品版本创建时间。
Status	Integer	刷掌产品算法版本类型。1:表示是当前使用版本；2:表示是待升级版本。
OldProductName	String	原产品名称。

接口专属结构

掌纹管理接口

PalmPaasPalmInfo

查询掌纹接口（DescribePalm）返回的单掌录掌信息。

注意：此结构仅用于掌纹管理类接口，与用户管理类接口使用的 PalmInfo 字段集不同（无 PreRegisterTime，多了 PalmDirection / MobileRegisterTime）。

名称	类型	描述
PalmState	PalmPaasPalmState	手掌状态，参见 PalmPaasPalmState 枚举。
PalmDirection	PalmPaasPalmDirection	手掌方向，参见 PalmPaasPalmDirection 枚举。
RegisterTime	Integer	注册时间，Unix秒级时间戳。
ExpireTime	Integer	掌纹过期时间，Unix秒级时间戳。仅当用户掌纹处于空中开掌预录掌阶段（PalmState=2，待激活）时返回，其他状态下不返回。
MobileRegisterTime	Integer	空中开掌注册时间。
RegisterType	PalmPaasRegisterType	注册类型，参见 PalmPaasRegisterType 枚举。

用户管理接口

CreateUserResponsePartialFailureError

创建用户接口的部分失败错误信息。

名称	类型	描述
NotExistUserTagIdList	Array of String	不存在的用户标签ID列表

ModifyUserResponsePartialFailureError

修改用户接口的部分失败错误信息。

名称	类型	描述
NotExistUserTagIdList	Array of String	不存在的用户标签ID列表

DescribeUserResponseUserTag

查询用户（DescribeUser）接口输出参数 UserTagList 的元素结构。

字段名	类型	描述
UserTagId	String	用户标签ID
UserTagName	String	用户标签名称

DescribeUserListResponseUser

查询用户信息列表（DescribeUserList）接口输出参数 UserList 的元素结构。

字段名	类型	描述
UserId	String	用户唯一标识
UserName	String	用户名
PhoneNo	String	手机号（带区号）
PhysicalCardNo	String	实体卡号
UserTagList	Array of DescribeUserListResponseUserTag	用户标签列表，参见 DescribeUserListResponseUserTag 结构
RegisterType	RegisterType	主掌录掌类型
PalmState	PalmState	主掌录掌状态
PalmDirection	PalmDirection	主掌方向
PalmPreRegisterTime	Timestamp	主掌预录掌时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
PalmRegisterTime	Timestamp	主掌录掌时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
PalmExpireTime	Timestamp	主掌特征过期时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
UserState	UserState	用户状态
CreatedTime	Timestamp	用户创建时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
UpdatedTime	Timestamp	用户最后更新时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。

DescribeUserListResponseUserTag

查询用户信息列表（DescribeUserList）接口输出参数 UserList[i].UserTagList 的元素结构。

字段名	类型	描述
UserTagId	String	用户标签ID
UserTagName	String	用户标签名称

用户标签管理接口

DescribeUserTagListResponseUserTagItem

查询用户标签列表（DescribeUserTagList）接口输出参数 UserTagList 的元素结构。

字段名	类型	描述
UserTagId	String	标签ID
UserTagName	String	标签名称
UserCount	Integer	标签关联的用户数量
ParentTagId	String	父标签ID，为空表示顶级标签
Level	Integer	层级深度：0=L1(顶级), 1=L2(二级), 2=L3(三级)
ChildrenCount	Integer	直接子标签数量
PathNodes	Array of UserTagNode	从根标签到当前标签的完整层级链路，按父到子顺序返回。参见 UserTagNode 结构。
CreatedTime	Timestamp	创建时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
UpdatedTime	Timestamp	最后更新时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。

UserTagNode

用户标签层级路径节点结构，用于表示从根标签到当前标签的完整层级链路。

字段名	类型	描述
UserTagId	String	用户标签ID
UserTagName	String	用户标签名称
Level	Integer	标签层级：0=L1(顶级), 1=L2(二级), 2=L3(三级)

UserTag

用户标签信息结构。

字段名	类型	描述
UserTagId	String	用户标签ID
UserTagName	String	用户标签名称
PathNodes	Array of UserTagNode	从根标签到当前标签的完整层级链路，按父到子顺序返回。

UserTagTreeNode

标签树节点结构，用于查询用户标签树（DescribeUserTagTree）接口输出。

字段名	类型	描述
UserTagId	String	标签ID
UserTagName	String	标签名称
UserCount	Integer	标签关联的用户数量
Level	Integer	层级深度：0=L1, 1=L2, 2=L3
ParentTagId	String	父标签ID，顶级标签为空
Children	Array of UserTagTreeNode	子标签节点

用户通行范围

AccessScopeItem

查询用户通行范围（DescribeUserAccessScope）接口输出参数 AccessScopeList 的元素结构。

字段名	类型	描述
SceneId	String	场景ID
SceneName	String	场景名称
SceneGroupId	String	场景组ID
SceneGroupName	String	场景组名称
DeviceSn	String	设备SN（未绑定设备时为空）
DeviceName	String	设备名称（未绑定设备时为空）
VerifyRules	Array of VerifyRuleInfo	绑定的核验规则列表（未绑定规则时为空数组）

VerifyRuleInfo

核验规则信息结构。

字段名	类型	描述
VerifyRuleId	String	核验规则ID
VerifyRuleName	String	核验规则名称

AccessScopeSummary

查询用户通行范围摘要（DescribeUserAccessScopeSummary）接口输出参数 Summary 的结构。

字段名	类型	描述
SceneGroupCount	Integer	可通行场景组数量
SceneCount	Integer	可通行场景数量
DeviceCount	Integer	可通行设备数量

设备管理接口

DescribeDeviceListResponseDevice

查询设备列表（DescribeDeviceList）接口输出参数 DeviceList 的元素结构。

字段名	类型	描述
DeviceSn	String	设备序列号
DeviceType	String	设备类型
DeviceName	String	设备名称
HeartbeatTime	Timestamp	设备心跳时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
ModuleHeartbeatTime	Timestamp	模组心跳时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
SystemVersion	String	系统版本
AppVersion	String	应用版本
ModuleType	String	模组类型
ModuleVersion	String	模组版本
ModuleExpireTime	Timestamp	模组过期时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
Status	DeviceStatus	设备实时状态
SceneId	String	绑定场景ID
SceneName	String	绑定场景名称
CreatedTime	Timestamp	设备创建时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
UpdatedTime	Timestamp	最后更新时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。

场景管理接口

DescribeSceneListResponseSceneItem

查询场景列表（DescribeSceneList）接口输出参数 SceneList 的元素结构。

字段名	类型	描述
SceneId	String	场景ID
SceneName	String	场景名称
SceneGroupId	String	所属场景组ID
SceneGroupName	String	所属场景组名称
DeviceSn	String	绑定设备序列号
DeviceName	String	绑定设备名称
ScenarioStrategy	ScenarioStrategy	场景策略
VerifyRuleIdList	Array of String	关联的核验规则ID列表
CreatedTime	Timestamp	创建时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
UpdatedTime	Timestamp	最后更新时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。

DescribeSceneGroupListResponseSceneGroupItem

查询场景组列表（DescribeSceneGroupList）接口输出参数 SceneGroupList 的元素结构。

字段名	类型	描述
SceneGroupId	String	场景组ID
SceneGroupName	String	场景组名称
ParentSceneGroupId	String	父级场景组ID，顶级场景组该值为"0"
ParentSceneGroupName	String	父级场景组名称，顶级场景组该值为空
SceneCount	Integer	直属子场景数量
ChildGroupCount	Integer	直属子场景组数量
CreatedTime	Timestamp	创建时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
UpdatedTime	Timestamp	最后更新时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。

核验记录接口

DescribeVerificationRecordListResponseVerificationRecord

查询核验记录列表（DescribeVerificationRecordList）接口输出参数 VerificationRecordList 的元素结构。

字段名	类型	描述
UserId	String	用户ID
UserName	String	用户名
VerificationTime	Timestamp	核验时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
VerificationMedium	VerificationMedium	核验介质
DeviceSn	String	设备SN
SceneId	String	场景ID
SceneName	String	场景名称
VerifierId	String	核验人ID
VerifierName	String	核验人名
SceneGroupId	String	场景组ID
SceneGroupName	String	场景组名称

核验规则接口

DescribeVerifyRuleListResponseVerifyRuleItem

查询核验规则列表（DescribeVerifyRuleList）接口输出参数 VerifyRuleList 的元素结构。

字段名	类型	描述
VerifyRuleId	String	核验规则全局唯一ID
VerifyRuleName	String	核验规则名称
EnableTimeRule	Boolean	是否启用时间规则
TimeRule	TimeRule	时间规则，参见 TimeRule 结构
EnableUserRule	Boolean	是否启用用户规则
UserRule	UserRule	用户规则，参见 UserRule 结构
EnableWebhookRule	Boolean	是否启用Webhook规则
BindSceneIdList	Array of String	绑定场景ID列表
CreatedTime	Timestamp	创建时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。
UpdatedTime	Timestamp	最后更新时间，RFC3339格式，如"2025-07-03T09:30:15.500Z"。

枚举类型

PalmState

手掌状态。

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
unregistered	未录掌
pre_registered	预录入
registered	已录掌
abnormal	异常

UserState

返回类型：字符串，取值为下表枚举值名称。
用户状态表示用户两只手掌分别的状态，不区分预录掌。

枚举值	描述
user_state_unspecified	未指定
both_unregistered	未注册(Unregistered): 双掌均未注册过
not_activated	未激活(Not Activated): 空开录掌后，无激活的手掌
user_state_abnormal	异常(Abnormal): 用户状态异常（至少一掌异常，且无激活掌）
left_valid	左掌可用(Left Valid): 右掌非激活状态下左掌激活
right_valid	右掌可用(Right Valid): 左掌非激活状态下右掌激活
both_valid	双掌可用(Both Valid): 双掌都是激活状态

VerificationMedium

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
verification_medium_unspecified	未指定介质
palm	刷掌
card	刷卡
code	刷码

NotifyQrCodeScanEventRequestQrCodeScanEventType

扫码事件类型。扫码事件通知（NotifyQrCodeScanEvent）接口输入参数 EventType 的取值。

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
qrcode_scan_event_type_unspecified	事件类型未指定，等同于 scanned
scanned	用户已扫码

DayOfWeek

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
NONE	未指定
MONDAY	周一
TUESDAY	周二
WEDNESDAY	周三
THURSDAY	周四
FRIDAY	周五
SATURDAY	周六
SUNDAY	周日

ScenarioStrategy

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
Default	默认
DemoOnDeviceRecognition100	演示端侧识别百人 100 User Demo On-device Recognition
AccessOnDeviceRecognition50k	门禁端侧识别五万人 50k User Access Control On-device Recognition
EKYCCloudRecognition1M	核身纯云端识别百万人 1M User eKYC Cloud Recognition
EKYCHybridRecognition1M	核身端云识别百万人 1M User eKYC Hybrid Recognition

RegisterType

注册类型。

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
register_type_unspecified	注册类型未指定
device	设备注册
mobile	手机注册

PalmDirection

掌纹方向。

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
palm_direction_unspecified	掌纹方向未指定
left	左手
right	右手

AdditionalVerifyMethod

加验方式。

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
additional_verify_method_unspecified	未指定，兜底走手机号后四位
phone_no	手机号后四位
custom_field	自定义字段数字验证
qr_code	二维码滴码验证

DeviceStatus

设备状态。

返回类型：整数，取值为下表枚举值。

枚举值	描述
0	设备状态未指定
1	在线
2	离线

VerificationRecordOrderField

核验记录排序字段。

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
verification_record_order_field_unspecified	未指定
verification_time	核验时间

SortOrder

排序方向。

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
sort_order_unspecified	未指定
asc	升序
desc	降序

ImageType

图片类型。

返回类型：整数，取值为下表枚举值。

枚举值	描述
1	Rgb
2	Ir

PalmPaasPalmDirection

手掌方向。

返回类型：整数，取值为下表枚举值。

枚举值	描述
1	左手
2	右手

FeatureType

特征类型。

返回类型：整数，取值为下表枚举值。

枚举值	描述
1	float32
2	int8
3	int7

PalmStatus

掌纹数据状态。

返回类型：整数，取值为下表枚举值。

枚举值	描述
1	正常
2	已删除

PalmPaasOperation

操作类型。

返回类型：整数，取值为下表枚举值。

枚举值	描述
1	创建
2	更新
3	删除

PalmPaasPalmState

手掌状态。

返回类型：整数，取值为下表枚举值。

枚举值	描述
1	待采集，用户存在但未录掌状态
2	待激活，用户开通了空中开掌但还未绑定手掌
3	已激活，用户已经通过线下设备绑定了手掌
100	首次注册，等待加验
101	高相似状态
102	用户发生了误绑
103	用户开启了空中开掌，但其他用户绑掌时在空中开掌搜到了该用户

PalmPaasRegisterType

注册类型。

返回类型：整数，取值为下表枚举值。

枚举值	描述
0	未指定
1	设备注册
2	手机注册

HasMoreType

是否有更多数据。

返回类型：整数，取值为下表枚举值。

枚举值	描述
1	没有更多数据
2	还有更多数据

AlgorithmStrategy

算法策略类型。Standard版支持策略A、B；Max版支持策略A、B、C、D。

返回类型：整数，取值为下表枚举值。

枚举值	描述
0	未指定，默认值
1	策略A：演示体验端侧识别百人
2	策略B：门禁考勤端侧识别万人
3	策略C：核身纯云端识别百万人
4	策略D：核身端云识别百万人

VerifyType

加验类型。

返回类型：整数，取值为下表枚举值。

枚举值	描述
0	未指定，默认值
1	高相似加验
2	不满足第一级阈值，但满足第二级阈值，且辅助底图比对阈值不通过
3	空中开掌加验
4	新注册类型加验

VerifyResult

加验结果。用户加验（Verify）接口输入参数 VerifyResult 的取值。

返回类型：整数，取值为下表枚举值。

枚举值	描述
0	未指定，默认值
1	成功
2	失败

GrantType

授权类型。

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
grant_type_unspecified	未指定，默认等同于 client_credential_user
client_credential_user	适用于第三方平台接入空中开掌SDK场景，此时必须同时传入UserId字段
client_credential	适用于普通服务端调用开放接口场景，UserId字段无需传入。调用刷掌业务平台开放接口时必须使用此类型

QrCodeScanState

二维码扫码状态。

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
pending	等待扫码
scanned	已扫码，等待填写信息
success	扫码录掌成功
failed	扫码录掌失败
expired	扫码录掌二维码会话过期

ResponseFormat

响应数据格式。

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
metadata	返回元数据（默认、推荐），返回除 SessionUrl 和 SessionImage 之外的其他字段
url	返回二维码URL，返回 SessionId、ExpireTime 和 SessionUrl
image	返回二维码图片（PNG），返回 SessionId、ExpireTime 和 SessionImage

QrCodeSessionType

二维码会话用途。

返回类型：字符串，取值为下表枚举值名称。

枚举值	描述
scan_register	扫码录掌：设备生成二维码 → 用户扫码 → 录掌绑定
tap_register	滴码录掌：APP生成二维码（携带用户信息）→ 设备扫码 → 录掌绑定
tap_verify	滴码加验：APP生成二维码（携带用户信息）→ 设备扫码 → 身份验证

通用结构

Error

名称	类型	描述
Code	String	错误码
Message	String	错误信息

错误码

功能说明

如果返回结果中存在 Error 字段，则表示调用 API 接口失败。例如：

{
   "Response": {
      "Error": {
         "Code": "AuthFailure.SignatureFailure",
         "Message": "The provided credentials could not be validated. Please check your signature is correct."
      },
      "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
   }
}

Error 中的 Code 表示错误码，Message 表示该错误的具体信息。

公共错误码

错误码	说明
InvalidParameter	参数错误（包括参数格式、类型等错误）
InvalidParameterValue	参数取值错误
MissingParameter	缺少参数错误，必传参数没填
UnknownParameter	未知参数错误，用户多传未定义的参数会导致错误
AuthFailure	CAM签名/鉴权错误
InternalError	内部错误。业务必须统一采用InternalError或者InternalError.xxx形式表示内部错误
InvalidAction	接口不存在
UnauthorizedOperation	未授权操作
RequestLimitExceeded	请求的次数超过了频率限制
NoSuchVersion	接口版本不存在
UnsupportedRegion	接口不支持所传地域
UnsupportedOperation	操作不支持
ResourceNotFound	资源不存在
LimitExceeded	超过配额限制
ResourceUnavailable	资源不可用
ResourceInsufficient	资源不足
ResourceExhausted	资源配额不足或达到速率限制
FailedOperation	操作失败
ResourceInUse	资源被占用
DryRunOperation	DryRun操作，代表请求将会是成功的，只是多传了DryRun参数
ResourcesSoldOut	资源售罄
OperationDenied	操作被拒绝

业务错误码

错误码	说明
InvalidParameterValue.FiltersLimitExceed	Filters数量超过限制
InvalidParameterValue.PageLimitExceed	分页参数超过限制
InvalidParameterValue.PageTokenExpired	分页令牌已过期
InvalidParameterValue.PageTokenSignatureFailure	分页令牌签名验证失败
InvalidParameterValue.PageTokenQueryMismatch	分页令牌查询条件不匹配
ResourceNotFound.TenantNotFound	指定的租户不存在，或您无权访问该租户
InvalidParameterValue.UserIdEmpty	用户ID为空
InvalidParameterValue.UserIdLengthNotAllowed	用户ID长度不满足限制
InvalidParameterValue.UserIdShouldOnlyContainLettersAndDigits	用户ID只能包含字母和数字
InvalidParameterValue.UserIdShouldOnlyContainGraphicsAscii	用户ID只能包含ASCII图形字符（ASCII范围：33-126）
InvalidParameterValue.UserNameEmpty	用户名称为空
InvalidParameterValue.UserNameLengthNotAllowed	用户名称长度不满足限制
InvalidParameterValue.UserNameOrPasswordEmpty	用户名称或密码为空
InvalidParameterValue.PhoneNoEmpty	手机号为空
InvalidParameterValue.PhoneNoLengthNotAllowed	手机号长度不满足限制
InvalidParameterValue.InvalidPhoneNo	手机号格式不正确
InvalidParameterValue.PhysicalCardNoLengthNotAllowed	物理卡号长度不满足限制
InvalidParameterValue.PhysicalCardNoShouldOnlyContainLettersAndDigits	物理卡号只能包含字母和数字
InvalidParameterValue.PalmIdEmpty	掌纹ID为空
InvalidParameterValue.SessionIdEmpty	会话ID为空
InvalidParameterValue.SessionIdLengthNotAllowed	会话ID长度不满足限制
InvalidParameterValue.SessionNotExist	会话不存在
InvalidParameterValue.InvalidUserId	用户ID格式不正确，只能包含数字字母和连字符
InvalidParameterValue.RegisterTypeNotAllowed	注册类型不满足限制
InvalidParameterValue.UserTagIdEmpty	用户标签ID为空
InvalidParameterValue.UserTagIdLengthNotAllowed	用户标签ID长度不满足限制
InvalidParameterValue.InvalidUserTagId	用户标签ID格式不正确
InvalidParameterValue.UserTagNameEmpty	用户标签名称为空
InvalidParameterValue.UserTagNameLengthNotAllowed	用户标签名称长度不满足限制
InvalidParameterValue.DeviceSnEmpty	设备SN为空
InvalidParameterValue.DeviceSnLengthNotAllowed	设备SN长度不满足限制
InvalidParameterValue.DeviceSnShouldOnlyContainLettersAndDigits	设备SN只能包含字母和数字
InvalidParameterValue.InvalidDeviceSn	设备SN格式不正确
InvalidParameterValue.DeviceNameEmpty	设备名称为空
InvalidParameterValue.DeviceNameLengthNotAllowed	设备名称长度不满足限制
InvalidParameterValue.ErrDeviceNameInvalid	设备名称格式不正确
InvalidParameterValue.SceneIdEmpty	场景ID为空
InvalidParameterValue.SceneIdLengthNotAllowed	场景ID长度不满足限制
InvalidParameterValue.SceneIdShouldOnlyContainLettersAndDigits	场景ID只能包含字母和数字
InvalidParameterValue.InvalidSceneId	场景ID格式不正确
InvalidParameterValue.SceneNameEmpty	场景名称为空
InvalidParameterValue.SceneNameLengthNotAllowed	场景名称长度不满足限制
InvalidParameterValue.SceneGroupIdEmpty	场景组ID为空
InvalidParameterValue.SceneGroupIdLengthNotAllowed	场景组ID长度不满足限制
InvalidParameterValue.SceneGroupIdShouldOnlyContainLettersAndDigits	场景组ID只能包含字母和数字
InvalidParameterValue.InvalidSceneGroupId	场景组ID格式不正确
InvalidParameterValue.SceneGroupNameEmpty	场景组名称为空
InvalidParameterValue.SceneGroupNameLengthNotAllowed	场景组名称长度不满足限制
InvalidParameterValue.VerifierIdEmpty	核验人ID为空
InvalidParameterValue.VerifierIdLengthNotAllowed	核验人ID长度不满足限制
InvalidParameterValue.VerifierIdShouldOnlyContainLettersAndDigits	核验人ID只能包含字母和数字
InvalidParameterValue.InvalidVerifierId	核验人ID格式不正确
InvalidParameterValue.VerifierNameEmpty	核验人名称为空
InvalidParameterValue.VerifierNameLengthNotAllowed	核验人名称长度不满足限制
InvalidParameterValue.QrCodeScanSessionIdEmpty	扫码录掌会话ID为空
InvalidParameterValue.QrCodeScanSessionTtlNotAllowed	扫码录掌会话期望生命周期不满足限制
FailedOperation.UserNotExist	用户不存在
FailedOperation.UserAlreadyExists	用户已存在
FailedOperation.UserIdAlreadyExists	用户ID已存在
FailedOperation.PhoneNoAlreadyExists	手机号已存在
FailedOperation.UserPalmAlreadyBound	用户手掌已绑定
FailedOperation.SceneNotExist	场景不存在
FailedOperation.SceneAlreadyExists	场景已存在
FailedOperation.SceneGroupNotExist	场景组不存在
FailedOperation.SceneGroupAlreadyExists	场景组已存在
FailedOperation.DuplicateSceneNameInSceneGroup	场景组内场景名称重复
FailedOperation.DuplicateSceneGroupNameInSceneGroup	场景组内场景组名称重复
FailedOperation.DeviceSceneBindingLimitExceeded	设备场景绑定超过限制
FailedOperation.QrCodeExpired	扫描录掌二维码已过期
FailedOperation.QrCodeFinished	扫描录掌二维码已被使用
FailedOperation.QrCodeStatusInvalid	扫描录掌二维码状态无效
FailedOperation.BindPalmUserIdAndUserNameNotMatch	绑定掌纹用户ID与用户名不匹配
FailedOperation.VerifyRuleAlreadyExist	核验规则已存在
FailedOperation.VerifyRuleNotExist	核验规则不存在
FailedOperation.DeviceNotExist	设备不存在
FailedOperation.DeviceAlreadyExists	设备已存在
FailedOperation.DeviceCannotBeDeletedWhenBindWithScene	设备绑定场景时不允许删除
FailedOperation.DeviceNotBoundWithScene	设备未绑定场景
FailedOperation.UserTagNotExist	用户标签不存在
FailedOperation.UserTagAlreadyExists	用户标签已存在
FailedOperation.UserTagNameAlreadyExists	用户标签名称已存在
InternalError.GetPaaSChannelFailed	获取PaaS渠道失败
InternalError.UpdateUserPalmFailed	更新用户手掌失败
InternalError.CreateUserTokenFailed	创建用户Token失败
InternalError.BindUserPalmByPaaSChannelFailed	通过PaaS渠道绑定用户手掌失败
InternalError.DeleteUserPalmByPaaSChannelFailed	通过PaaS渠道删除用户手掌失败
InternalError.DescribeUserPalmByPaaSChannelFailed	通过PaaS渠道查询用户手掌失败
InternalError.CreateAccessTokenFailed	创建开放接口访问令牌失败
InternalError.CreateDeviceAccessTokenFailed	创建开放接口设备访问令牌失败
InternalError.DescribeSecretKeyFailed	查询开放接口访问密钥失败
FailedOperation.MemberNotExist	成员不存在
FailedOperation.MemberAlreadyExists	成员已存在
FailedOperation.MemberLoginExpired	成员登录已过期
FailedOperation.NoAvailableVersion	没有可用的版本
FailedOperation.UnknownImageType	未知的图片类型
FailedOperation.PicInconsistent	图片MD5不一致
FailedOperation.LivenessCheckNoPass	活体检测失败
FailedOperation.QualityCheckNoPass	质量检测失败
FailedOperation.LivenessWithVideoCheckNoPass	活体视频检测失败
FailedOperation.PalmIdNoExistInCache	palmID不存在
FailedOperation.AlreadyBind	已经绑定
FailedOperation.ThirdAuthFail	鉴权失败
FailedOperation.NoFoundDataInDb	数据库未查询到数据
FailedOperation.NoSearchUser	在掌纹检索热库中未找到匹配用户
FailedOperation.UnknownVerifyType	未知的验证类型
FailedOperation.TableCapacityFull	系统容量不足
FailedOperation.VerifyUserIdNoMatch	验证用户ID不匹配
FailedOperation.VerifyIdExpire	验证ID过期
FailedOperation.PalmIdAlreadyExist	palmID已经存在
FailedOperation.HighSimilarity	存在高相似的手掌
FailedOperation.PalmCapacityFull	用户的掌纹检索热库容量已达上限
FailedOperation.LiveImageAlreadyExist	图片已存在
FailedOperation.QrCodeUserIdNotMatchSession	扫码录掌用户ID与会话不匹配
LimitExceeded.VerifyRuleUserTagsExceedLimit	核验规则关联标签数超过限制
LimitExceeded.VerifyRuleUsersExceedLimit	核验规则关联用户数超过限制
FailedOperation.MemberDisabled	成员已被禁用
OperationDenied.TenantDisabled	租户已被禁用，无法登录
InvalidParameterValue.SmsCodeEmpty	短信验证码为空
InvalidParameterValue.RefreshTokenEmpty	刷新令牌为空
InvalidParameterValue.SmsCodeNotMatch	短信验证码错误
InvalidParameterValue.PhoneNoNotMatch	手机号与验证码会话不匹配
ResourceNotFound.SmsSessionNotExist	验证码会话不存在或已过期
ResourceNotFound.RefreshTokenNotExist	刷新令牌不存在或已过期
ResourceExhausted.SmsResendTooFrequent	短信验证码发送过于频繁
ResourceExhausted.SmsMaxVerifyAttempts	验证码尝试次数过多
FailedOperation.SmsSendFailed	短信发送失败

版本更新记录​

简介​

概述​

术语表​

API 概览​

功能分类​

鉴权管理相关接口​

用户管理相关接口​

用户标签管理相关接口​

用户手掌管理相关接口​

设备管理相关接口​

场景管理相关接口​

核验记录相关接口​

核验规则相关接口​

扫码录掌相关接口​

PalmMa 登录相关接口​

掌纹管理相关接口（刷掌算法平台）​

调用方式​

调用基本流程​

请求结构​

1. 服务地址​

2. 通信协议​

3. 请求方法​

4. 字符编码​

公共参数​

请求头示例​

签名方法​

为什么要进行签名​

申请安全凭证​

签名过程（v3）​

签名演示（Python）​

签名失败常见错误码​

返回结果​

正确返回结果​

错误返回结果​

公共错误码​

参数类型​

部分失败​

什么是部分失败​

如何使用部分失败​

示例场景​

场景一：创建用户并批量绑定标签​

最佳实践​

支持部分失败的接口​

鉴权管理相关接口​

获取访问凭证​

1. 接口描述​

2. 输入参数​

3. 输出参数​

4. 示例​

输入示例​

输出示例​

错误输出示例​

查询授权信息​

1. 接口描述​

2. 输入参数​

3. 输出参数​

4. 示例​

输入示例​

输出示例​

错误输出示例​

用户管理相关接口​

创建用户​

1. 接口描述​

2. 输入参数​

3. 输出参数​

4. 示例​

输入示例​

输出示例​

部分失败输出示例​

错误输出示例​

修改用户​

1. 接口描述​

2. 输入参数​

3. 输出参数​

4. 示例​

输入示例​

输出示例​

部分失败输出示例​

错误输出示例​

版本更新记录

简介

概述

术语表

API 概览

功能分类

鉴权管理相关接口

用户管理相关接口

用户标签管理相关接口

用户手掌管理相关接口

设备管理相关接口

场景管理相关接口

核验记录相关接口

核验规则相关接口

扫码录掌相关接口

PalmMa 登录相关接口

掌纹管理相关接口（刷掌算法平台）

调用方式

调用基本流程

请求结构

1. 服务地址

2. 通信协议

3. 请求方法

4. 字符编码

公共参数

请求头示例

签名方法

为什么要进行签名

申请安全凭证

签名过程（v3）

签名演示（Python）

签名失败常见错误码

返回结果

正确返回结果

错误返回结果

公共错误码

参数类型

部分失败

什么是部分失败

如何使用部分失败

示例场景

场景一：创建用户并批量绑定标签

最佳实践

支持部分失败的接口

鉴权管理相关接口

获取访问凭证

1. 接口描述

2. 输入参数

3. 输出参数

4. 示例

输入示例

输出示例

错误输出示例

查询授权信息

1. 接口描述

2. 输入参数

3. 输出参数

4. 示例

输入示例

输出示例

错误输出示例

用户管理相关接口

创建用户

1. 接口描述

2. 输入参数

3. 输出参数

4. 示例

输入示例

输出示例

部分失败输出示例

错误输出示例

修改用户

1. 接口描述

2. 输入参数

3. 输出参数

4. 示例

输入示例

输出示例

部分失败输出示例

错误输出示例