Smart-ID API：RP API v3 开发者指南
面向开发者的 Smart-ID API（RP API v3）：端点、设备链接与通知流程、响应验证、演示环境测试、您获得的内容、保证级别、反洗钱规则和价格。
要点
Smart-ID API 是 SK ID Solutions 发布的依赖方（RP）API，用于通过 Smart-ID 应用让用户登录和收集签名。版本 3 在推送通知之外新增了二维码和同设备链接。[12]
- 爱沙尼亚、拉脱维亚和立陶宛共有 3,853,329 人使用 Smart-ID（计数器数据，2026年10月5日）。[1]
- 该 API 返回一份已签名的证书，包含用户姓名和带国家前缀的个人识别码。不含地址，不含肖像照。[15][5]
本文是以代码为主的 Smart-ID API 指南，涵盖端点、会话、响应校验、演示环境测试和法律地位。如需了解各国的合同和反洗钱规则，请阅读我们的Smart-ID 集成指南。
Smart-ID 概览
Smart-ID 是 SK ID Solutions AS 推出的移动应用。服务方通过 SK 的依赖方 API 使用它让用户登录或收集签名。[13] 每个密钥的一部分存放在 SK 的服务器上，爱沙尼亚信息系统管理局（RIA）称之为“Smart-ID 密钥管理服务器服务”。[4]
Smart-ID
波罗的海国家和比利时基于应用的电子身份
普及情况：用户与交易
根据 smart-id.com 在2026年10月5日的实时计数器，立陶宛是 Smart-ID 最大的市场，用户为 1,857,471 人，其次是拉脱维亚 1,198,463 人和爱沙尼亚 797,395 人。[1] SK 称其“每月交易近 100 百万笔”。[2]
据 ERR News 报道，在爱沙尼亚，Smart-ID 在身份验证中“市场份额接近 60%”。计数器只提供总数；没有任何一手来源给出 Smart-ID 在各国成年人中的占比（2026年10月5日）。
用户看到的界面
RP API v3 通过三种方式触达应用：跨设备的动态二维码、同一部手机上的 Web2App 或 App2App 链接，或推送通知。[12] SK 将二维码和应用间跳转体验以 Smart-ID+ 的名义推广，称其“不再依赖在网站上输入个人身份识别码”。[8]
使用 Smart-ID 登录
使用 Smart-ID 应用扫描该二维码。
1网站显示一个动态二维码，每秒重新生成一次。[18]
扫码登录
将摄像头对准屏幕上的二维码。
2该应用只能扫描 Smart-ID 登录二维码，且仅在用户发起登录时才能扫描。[9]
您的服务
登录您的服务。仅在您本人发起此操作时继续。
继续
3该应用始终会将您的服务名称与请求文本一并显示。[36]与此二维码流程不同，通知流程还会在输入 PIN 之前显示一个四位数代码，或提供三个代码供用户选择。[17][10]
输入 PIN1
确认登录您的服务。
确认
4此后用户才输入 PIN1，且是在应用内输入，绝不在您的网站上输入。[8]
您已登录
- 全名已共享
- 个人代码已共享
- 地址未共享
- 人像照片未共享
5您的后端从证书中读取姓名和个人代码。[15]
视频待上线：flow-app-code
使用比对代码的应用登录全过程。
Smart-ID API v3 的工作原理
该 API 采用基于 HTTPS 的 REST 架构，使用 UTF-8 编码的 JSON。[19]四类 POST 端点用于开启会话并返回 sessionID；一个 GET 端点用于返回结果。[13]
| 端点类别 | 功能 |
|---|---|
POST v3/authentication/device-link/anonymous | 通过二维码或同设备链接登录，无需输入个人识别码 |
POST v3/authentication/notification/etsi/{id} | 向以个人识别码识别的用户推送登录请求 |
POST v3/signature/... | 对文档摘要进行签名（ASiC-E 或 PAdES） |
POST v3/signature/certificate/{document-number} 和 certificate-choice | 先获取签名证书 |
GET v3/session/{sessionID} | 读取状态和结果 |
RP API v3 的端点类别，摘自 SK 的概览。[13]
用户输入 PIN1
使用设备链接进行跨设备登录的简化流程。[12][18]
常见问题：
- 每个 v3 初始请求都带有一个由您生成的随机
rpChallenge。它取代了 v2 中用于防范重放攻击的nonce。[20] sessionSecret绝不能传到您的前端。一个流程只发起一次会话请求，即使您同时显示二维码和链接也是如此。[18]- 在通知流程中，您需要根据
rpChallenge的 SHA-256 计算四位数验证码。[17] - SK 通过来源 IP 加
relyingPartyUUID对您进行认证，并要求使用 HTTPS 密钥固定。[19] - SK 的文档称，没有账户的用户会收到 HTTP 404。为防范枚举攻击，SK 要求您对所有错误情况显示同一条提示信息。[19]
企业从 Smart-ID API 获得的信息
已完成的会话返回 state、result.endResult、cert 中的用户证书以及一个 signature 对象。主体的 serialNumber 包含身份识别码，例如 PNOEE-30001010004，其前缀表示国家。[15]
| 属性 | 返回情况（会话 COMPLETE，结果 OK） | 位置 |
|---|---|---|
| 带国家前缀的个人识别码 | 是 | 证书主体 serialNumber[15] |
| 名和姓 | 在证书主体中 | 依据 SK 的证书配置文件 中列出的主体字段 |
| 证书级别 | 是 | cert.certificateLevel，例如 ADVANCED 或 QUALIFIED[15] |
| 对您的挑战值或摘要的签名 | 是；如被拒绝或超时则无 | signature 对象[15] |
| 出生日期 | 取决于识别码 | 爱沙尼亚识别码有文档说明；拉脱维亚测试账户既有带日期字段的，也有不带日期字段的[5][16] |
| 地址、国籍、肖像照 | 从不 | 证书和响应中均不包含[5] |
SK 的响应验证要求您：[15]
- 检查
state为COMPLETE，endResult为OK，协议为ACSP_V2（登录）或RAW_DIGEST_SIGNATURE。 - 仅依据 SK 的 CA 验证证书链，并使用 OCSP 或 CRL。
- 要求包含每一个 Smart-ID 策略标识符，使其他 SK 证书无法通过。
- 将
certificateLevel与您要求的级别进行比较。 - 重建被签名的载荷并验证签名。
- 在同设备流程中验证回调 URL 的值。
保证级别与法律地位
Smart-ID 不在欧盟已通报 eID 方案清单上；爱沙尼亚的已通报方案（高级别，2018年11月7日）涵盖身份证和 Mobile-ID。[6]
| 国家 | 评估 | 来源 |
|---|---|---|
| 爱沙尼亚 | 对持有爱沙尼亚个人识别码的人员为“高”级（RIA 专家组） | RIA[4] |
| 拉脱维亚 | 合格电子身份提供者，自 2023 年 5 月起获得本地合格地位 | 国防部，SK[25][26] |
| 立陶宛 | 高保证级别（SK 2024 年 12 月 19 日新闻） | SK，援引 RRT[27] |
| 比利时 | “已按高保证级别正式评估” | SK[2] |
注意：电子居民“与居民无法区分”。[5]
爱沙尼亚反洗钱客户尽职调查
爱沙尼亚《防止洗钱和恐怖主义融资法》（RahaPTS）在 § 31(3) 中规定了远程途径。[23]
§ 31(3)RahaPTS（爱沙尼亚）
"1) e-identimise süsteemi, millest on teatatud ... (EL) nr 910/2014 ... artikli 9 kohaselt ja mis vastab ... artikli 8 lõike 2 punktis b või c sätestatud usaldusväärsuse tasemele" 或 "2) kvalifitseeritud usaldusteenust"
来源：Riigi Teataja, RahaPTS[23]
中文含义：已通报且达到“实质”或“高”保证级别的电子身份方案，或合格信任服务。途径 1 不适用；截至 2026 年 10 月 5 日，Smart-ID 的合格证书是否符合途径 2 尚无官方说明，请咨询 Finantsinspektsioon 或法律顾问。立陶宛反洗钱法（第 11 条）和拉脱维亚内阁第 392 号条例（第 7.1 点）将合格或安全电子签名列为若干远程途径之一。[28][29]
自 2027 年起：AMLR 第 22(6) 条
《反洗钱条例》（AMLR）自 2027 年 7 月 10 日起适用；第 22(6)(b) 条接受“符合条例 (EU) No 910/2014 关于‘实质’或‘高’保证级别要求的电子识别手段以及相关合格信任服务”。[30]反洗钱局（AMLA）2026 年 9 月 30 日的最终标准草案尚非法律，该草案接受达到实质或高保证级别的电子身份，“无论其是否已根据第 9 条通报”。[31]我们的EUDI 钱包页面介绍了 eIDAS 2 的时间表。
企业如何接入：直接签订 RP 合同或通过经纪商
SK 的流程：无需签订协议即可免费测试，选择安全措施，发送您的 IP 地址和服务名称，签约，获取 RP UUID，“在首次咨询后数日内”上线。[21]经认证的经纪商也转售 Smart-ID，爱沙尼亚公共机构可使用 RIA 的 TARA 网关。[5]
直接接入
与 SK 签订 RP 合同
- 由您调用 RP API
- IP 允许列表、RP UUID
- 由您构建验证流程
公开价目表
通过中介服务商
聚合商或 eID 中心
- 一个 API，多种 eID
- 合同由中介服务商签署
- 验证由他人代为完成
价格未在一处统一公布
公共部门
TARA（爱沙尼亚）
- 基于 OpenID Connect，由 RIA 运营
- 先注册，再接入演示环境，然后上线
- 私营企业：仅限跨境
国家机构
接入 Smart-ID 的三种方式。[21][5]
SK 的价目表（自2026年6月1日起）对每次“Smart-ID 认证或签名请求”计费：单价 €0.109，每月最低消费 €60；在 3 million 套餐下降至 €0.0106；超过 5 million 次则单独签订协议。[11] SK 表示，对现有 RP 而言，Smart-ID+ “不产生额外费用”。[7]
在演示环境中进行测试
演示环境：https://sid.demo.sk.ee/smart-id-rp/v3/，relyingPartyUUID 为 00000000-0000-4000-8000-000000000000，名称为 DEMO。生产环境：https://rp-api.smart-id.com/v3/。[14] 按结果分类的测试账户：[16]
| 最终结果 | 示例证件号码（爱沙尼亚） | 测试内容 |
|---|---|---|
OK | PNOEE-40504040001-DEM2-Q | 成功 |
USER_REFUSED | PNOEE-30403039917-MOCK-Q | 用户取消 |
WRONG_VC | PNOEE-30403039972-MOCK-Q | 选择了错误的验证码 |
TIMEOUT | PNOEE-30403039983-MOCK-Q | 无应答 |
使用场景与行业规则
- KYC 和 AML 开户。经签名的姓名和个人识别码；AML 适用性因国家而异。[23][28][29]
- 博彩与年龄。爱沙尼亚《博彩法》禁止未满21岁者参与机会游戏（§ 34(2)），并要求远程运营商核验每位玩家并登记其个人识别码（§ 53(1)）。[24]我们未在该 API 中发现仅含年龄的声明。
- 签名。合格账户通过
v3/signature签名；“2025年，每10个立陶宛人中有4人使用了合格电子签名”。[13][33] - 电信。没有任何波罗的海国家的规则指定 Smart-ID 用于 SIM 卡登记（2026年10月5日）。
限制与备用方案
“在爱沙尼亚和拉脱维亚，Smart-ID 目前仅限持有爱沙尼亚或拉脱维亚国家身份号码的人使用”；立陶宛非居民可在两家银行获取 Smart-ID Basic。[22]Smart-ID 本身没有年龄限制，但注册途径有年龄限制（拉脱维亚身份证14岁起可申领），且未满18岁者的账户需要父母授权。[32]
截至2026年10月5日，我们未发现有记录的服务中断；主要风险是网络钓鱼。据ERR News报道，2025年，PIN诈骗从爱沙尼亚银行账户中窃取了近€23 million。自2026年4月29日起，爱沙尼亚的注册流程通过NFC读取身份证，不再使用读卡器。[34]
1优先提供 Smart-ID
波罗的海国家个人识别码持有人。
会话以 COMPLETE 结束，结果为 OK
验证并存储结果
所有检查均通过。
切换至证件核验
NFC 芯片读取、活体检测和人脸比对。
2筛查并决策
先进行 AML 筛查，再由您作出决定。
优先使用 eID，以证件核验作为备用方案；记录每次启用备用方案的原因。[31]
Smart-ID API 实施检查清单
先基于 SK 的免费演示环境开发，这样在代码可用之前无需签订合同。[21]响应验证是这项工作的核心。[15]
- 基于演示 URL 和已公布的测试账户进行开发。[14][16]
- 优先采用设备链接流程；仅在已知设备上允许使用通知流程。[13]
- 每次登录都生成新的随机
rpChallenge。[20] - 固定 SK 的 HTTPS 密钥，并将
sessionSecret保留在服务器端。[19][18] - 执行 SK 响应验证的每一个步骤。[15]
- 将您的 IP 和服务名称发送给 SK，然后签约。[21]
- 书面记录您在每个国家将其用于 AML 的法律依据。[23]
- 为没有 Smart-ID 的用户增加证件验证路径。
Didit 如何帮助您接入 Smart-ID
Smart-ID 已在 Didit 上线，用于爱沙尼亚、拉脱维亚、立陶宛和比利时的eID 验证。Didit 持有与 SK 的连接，因此您无需签订 RP 合同，无需配置 IP 白名单，也无需编写证书代码。
在控制台中，依次进入 Workflows、ID Verification 步骤、Countries，选择国家，并在“Wallets accepted”下勾选 Smart-ID。通过 API 接入时，设置 methods.EST.wallet，创建会话，然后读取 GET /v3/session/{id}/decision/ 或 webhook：根据数字身份钱包文档，verification_method 为 "wallet"，并附带一个 wallet_verification 对象。[35]用户在 Smart-ID 应用中确认比对码。Didit 从不索取 PIN。
截图待补：hosted-flow-wallet-chooser
Didit 托管流程中的验证方式选择界面。
截图待补：hosted-flow-smartid-code
用户在 Smart-ID 应用中核对的比对码。
截图待补：console-wallets-accepted
在 Didit 控制台中启用 Smart-ID。
您将获得全名、出生日期、波罗的海个人身份代码、保证级别（标记为 High）以及签名校验；不包含地址，也不包含人像照片。没有 Smart-ID 的用户改用证件验证，配合NFC 芯片读取（$0.15）、活体检测和人脸比对；完整 KYC 为 $0.33，AML 筛查为 $0.20。仅对已完成的 eID 登录计费；一次完成的 Smart-ID 验证费用为 $0.20（定价页面），所有 eID 见数字身份钱包页面。
Didit 提供
- Smart-ID 连接与签名校验
- 证件验证路径
- AML 筛查及每项检查的证据
由您负责
- 风险评估与 AML 解读
- 开户决定
- 每次转入备用路径的原因
要点
- Smart-ID API（RP API v3）通过
POST创建会话，通过GET读取会话。 - 相比推送通知，SK 更推荐设备链接流程（二维码或同设备链接）。
- 您获得的是包含姓名和个人识别码的证书，不含地址或人像照片。
- 在国家层面评级为高，但未经欧盟通报：其是否满足 AML 要求因国家而异。
常见问题
是否有公开的 Smart-ID API？
有。SK 公开发布 Relying Party API 文档；当前版本为 3.2.3。[20]正式调用需要签订协议，并具备 RP UUID 和已获准的 IP 地址。[21][19]
Smart-ID API 的费用是多少？
SK 自 2026年6月1日起执行的价目表为每次请求 €0.109 起，每月最低消费 €60，在 3 百万次套餐中降至 €0.0106。[11]代理商的价格没有在同一处统一公布。在 Didit 上，一次完成的 Smart-ID 验证费用为 $0.20。
Smart-ID API 返回哪些数据？
一份已签名的证书，包含用户的姓名和个人代码（例如 PNOEE-30001010004），以及一个签名。[15] 不包含地址、国籍或人像照片。[5]
如何测试 Smart-ID API？
使用演示环境和 SK 公开的演示 RP UUID。该环境免费，无需签订协议。[14][21] 爱沙尼亚、拉脱维亚、立陶宛和比利时的测试账户会返回成功、拒绝、代码错误或超时等结果。[16]
Smart-ID RP API v3 有哪些变化？
版本 3 在推送通知之外新增了设备链接流程（QR、Web2App 和 App2App），并配有各自的端点。[13][20] 该版本还要求每个初始请求必须包含随机的 rpChallenge，取代 v2 的 nonce，用于防范重放攻击。[20] 版本 3.2 同时支持 HTTP/1.1 和 HTTP/2，并按 RFC 9457 格式返回错误详情。[20]
应该使用设备链接流程还是通知流程？
全部使用设备链接可提供最强的防钓鱼保护。在跨设备场景中，新设备使用设备链接、已知设备使用推送通知的组合同样是推荐做法。仅使用推送通知则不推荐。[12]
Smart-ID 的保证级别是什么？
在爱沙尼亚、拉脱维亚和立陶宛的国家评估中为高级。[4][25][27] 它不在欧盟已通报 eID 方案清单上。[6]
在爱沙尼亚，Smart-ID 是否足以满足反洗钱客户尽职调查要求？
RahaPTS § 31(3) 允许使用实质级或高级的已通报 eID，或使用合格信任服务。[23] 目前没有官方声明说明 Smart-ID 是否属于后者（2026年10月5日）。请咨询 Finantsinspektsioon 或法律顾问。
外国人可以使用 Smart-ID 吗？
在爱沙尼亚和拉脱维亚，只有持有当地个人代码的人才能注册。在立陶宛，非居民可以在两家银行办理 Smart-ID Basic。居留许可持有人和电子居民的注册方式与公民相同。[22]
未成年人可以使用 Smart-ID 吗？
Smart-ID 本身没有年龄限制，年龄要求由注册途径决定，例如在爱沙尼亚持护照注册的最低年龄为 6 岁。[32] 未满 18 岁的账户需要父母授权，SK 的测试账户中也包含未成年人账户。[32][16]
Smart-ID API 集成需要多长时间？
SK 称"在您首次咨询后的数天内"即可完成。[21] 所需的开发工作量没有公布。
来源
- Smart-ID 主页，实时用户计数器，SK ID Solutions，2026年10月5日查阅。
- 2025：推动数字信任跨越国界，SK ID Solutions，2026年1月19日。
- 欧洲数字身份领域的信任与竞争，e-Estonia，2026。
- 电子身份（eID），信息系统管理局（RIA）。
- TARA 技术规范，RIA。
- eIDAS 下预通报和已通报 eID 方案概览，欧盟委员会，2026年10月5日查阅。
- Smart-ID+，SK ID Solutions。
- 新版 Smart-ID 如何保护我免受欺诈，Smart-ID 常见问题。
- 爱沙尼亚政府采用 Smart-ID+ 以加强安全，SK ID Solutions，2026年1月28日。
- 为什么有时显示一个确认码，有时显示三个，Smart-ID 常见问题。
- 价目表，SK ID Solutions，自2026年6月1日起生效。
- 依赖方 API：简介，SK ID Solutions，版本 3.2.3。
- 依赖方 API：API 端点概览，SK ID Solutions。
- 环境技术参数，SK ID Solutions。
- 依赖方 API：响应验证，SK ID Solutions。
- 用于自动化测试的测试账户，SK ID Solutions。
- 依赖方 API：基于通知的流程，SK ID Solutions。
- 依赖方 API：设备链接流程，SK ID Solutions。
- 依赖方 API：API 技术说明，SK ID Solutions。
- 依赖方 API：变更日志，SK ID Solutions。
- 电子服务提供商的集成流程，Smart-ID。
- 外国人和非居民能否使用 Smart-ID，Smart-ID 常见问题。
- Rahapesu ja terrorismi rahastamise tõkestamise seadus (RahaPTS), § 31，Riigi Teataja。
- Hasartmänguseadus（《赌博法》），Riigi Teataja。
- Elektroniskā identifikācija，拉脱维亚国防部。
- Smart-ID 在拉脱维亚获得本地合格认证地位，SK ID Solutions，2023年5月29日。
- Smart-ID 和 Mobile-ID 在立陶宛被认可为国家批准的工具，SK ID Solutions，2024年12月19日。
- 《防止洗钱和恐怖主义融资法》第11条，立陶宛，INFOLEX 合并文本。
- 内阁条例第392号，拉脱维亚，likumi.lv。
- 条例 (EU) 2024/1624 (AMLR)，EUR-Lex，2024年6月19日《欧盟官方公报》。
- 最终报告：AMLR 第28(1)条下的 RTS 草案，AMLA，2026年9月30日。
- 使用 Smart-ID 的年龄限制，Smart-ID 常见问题。
- SK ID Solutions 于2025年在立陶宛签发近三百万张证书，SK ID Solutions，2026年5月7日。
- 现可通过 NFC 使用爱沙尼亚身份证注册 Smart-ID，Smart-ID，2026年4月29日。
- 数字身份钱包，Didit 文档。
- 依赖方 API：交互，SK ID Solutions。
Smart-ID 是 Didit eID 验证中已上线的五种 eID 之一。另请参阅什么是 eID 验证以及BankID 瑞典 API 指南。