官网 NFC 验真 API
标签打开官网。官网服务器把当次碰卡的完整地址提交给 BrandGuard,读取判定,然后在官网显示结果。
从官网登记到手机验收
先运行离线模拟
下载完整的 SDK 1.3.3,解压后打开 START_HERE.html。包内有官网适配器、模拟器、测试用例和部署步骤。完整流程使用 Node.js 22.12 或以上版本和 npm。
中文 SDK 1.3.3English SDK 1.3.3SHA-256 校验值
在解压后的目录运行 node reference/node-server.mjs。打开终端显示的本机地址,选择一次合成碰卡。模拟使用本地样例,无需令牌或实体标签。
配置这条连接
- 请管理员提供环境、API 地址、已批准的官网来源、标签打开的地址和
encodingVersionId。将同一连接的参数保存在一起。管理员另行交付服务器令牌,其完整值存入官网服务器秘密管理器。 - 在标签打开的地址部署 HTTPS 服务。捕获该次请求的完整网址,保留路径、查询参数顺序、大小写和百分号编码。关闭该路由记录完整网址的日志。
- 第一次发送前,先把原始请求体、API 来源和此次操作的新幂等键保存在受保护的持久存储中。在指定 API 来源下向
/api/customer/v1/verifications发起 POST,发送Content-Type: application/json、Authorization: Bearer加服务器令牌,以及Idempotency-Key。请求体包含encodingVersionId和完整tapUrl。
POST 需要 verifications:execute 权限。回查回执使用 GET /api/customer/v1/verifications/{verificationId},并使用同一租户、连接与环境下有 verifications:read 权限的服务器令牌。
在官网显示结果
读取 receipt.result 与 currentEligibility.eligible。有效且当前仍符合资格的新碰卡可打开已确认匹配的产品页。尚无匹配页时,在验真结果页显示当次判定。刷新保留原回执的时间和次数。重放时提示重新碰卡;签名无效、未登记标签和策略拒绝分别显示对应判定。仅支持电子封签的标签显示封签信息。
按响应排查错误
| 响应或现象 | 先检查什么 |
|---|---|
| 无响应 | 检查 DNS、TLS、出站网络、准确的 API 主机和超时;恢复时保留同一 API 地址、请求体和幂等键。 |
400 · invalid_encoding_version / invalid_tap_url | 将编码 ID、标签打开的精确地址和捕获的完整查询参数与本连接配置逐项核对。 |
401 · not_authorized | 检查服务器秘密和 Bearer 请求头,确认令牌是否已过期或撤销。匿名 POST 得到此响应说明请求到达了身份验证环节。 |
403 · not_authorized / integration_not_authorized | 核对令牌所属租户、执行权限、连接和环境,并确认连接已启用。 |
409 · idempotency_conflict | 找出此幂等键最初对应的请求,核对编码 ID 和碰卡网址。结束冲突提交,并核对原操作的状态。 |
| 202 / 429 / 503 或未收到响应 | 保留原幂等键、API 来源和请求体。若收到 Retry-After,等待指定时间,再按原操作恢复。 |
排错时记录 UTC 时间、HTTP 状态、已识别的错误码和请求编号。日志和支持消息均省略完整碰卡网址及令牌。
在 Staging 测试官网服务器
- 打开专用测试连接的工程师交接资料。确认连接已启用,选择对应编码,再选适合服务器的 Bash 或 PowerShell 示例。
- 先运行匿名请求。HTTP 401 表示此接口要求身份验证。再从服务器环境提供该连接具有执行权限的令牌,运行第二个请求。使用未登记的合成标签标识,此请求会在测试连接留下一条诊断判定。
- 预期为 HTTP 200。对照响应中的结果字段:
{"receipt":{"result":"unknown_tag"}}以上仅摘录结果字段,完整响应还包含验真编号。新测试或更改碰卡网址时使用新幂等键。若响应丢失,在同一 API 地址使用原幂等键、编码和原始请求体恢复。沿用旧键提交不同内容可能收到 HTTP 409。
用手机核对实卡与产品页
用手机轻触已登记且已写入的测试单件,核对回执中的 verificationId、itemId 以及手机实际打开的产品或规格页。再分别直接打开页面和刷新上次访问,检查两者显示的状态。