准备首次真实请求
先运行 node reference/node-server.mjs,打开终端显示的本机网址,选择合成碰卡并切换语言。无需 Token 或标签。下方网址和回执都是合成示例,不要把这些样例提交真实验真服务。
完整流程建议使用 Node.js 22.12 或更新版本及 npm(本包以 24.16 验证)。Node 20 仅支持无依赖模拟与 npm test;锁定原生工具要求 Node 22,Wrangler 要求 22.12。npm test 为无依赖离线测试;npm run test:full 在 Windows 或 POSIX 安装锁定的原生工具并运行真实 workerd/SQLite、Node 和 DOM 检查。首次需要连接软件包仓库,报告默认保存在解压包内 test-output/。
网站批准与旧证明文件
先请管理员在目标环境、目标租户中检查准确 HTTPS 来源的批准状态。主域名和子域名须分别登记并核验,例如 website.example 和 verify.website.example。同一站点的不同路径共用该站点的归属核验。同一处已经批准的来源可由新连接复用,凭据仍按连接绑定。仅增加 SKU 不要求新的归属文件、Token 或兼容编码。
更换环境或租户后,必须在目标处检查。若已列为批准,可使用该状态;否则由管理员提供当前登记的公开证明及准确 URL。普通网站通常发布指定 .well-known 文件;WordPress 可能使用后台给出的证明端点。不要猜文件名或改动内容。
每次核验比对当前登记的 installationId 与 challenge。校正登记或重新登记可能换发 challenge。活跃登记、再核验或安装仍依赖文件时保留;旧登记已经退役且没有其他用途时,才可删该旧文件。删除文件不会撤销已经保存的 API 批准。
配置表中的术语
- NFC 首跳
- 实体标签最先打开的准确网站路径。后续重定向不能改变实际写入的地址。
- Writer
- 获授权的写卡和读回工具。新的精确入口可能需要新的不可变编码。
- SDM
- Secure Dynamic Messaging,芯片在标签网址中生成动态认证数据。
- encodingVersionId
- 管理员提供的不可变编码标识,对应获准的芯片与网址模板。
- SKU 模式
- 官网用可信回执的完整 SKU 精确匹配自己的产品目录。
- 路径模式
- 使用回执中已确认的同源产品或单件专属路径。
- 按芯片 UID 查找记录
- 由获授权的人员或后台将已验真的芯片 UID 关联到您系统中的记录。访客请求和重放不能建立关联。
- Item ID
- 平台对一件实物的身份标识,在可信回执中取得,开始接入前无需预置清单。
配置入口与多语言页面
从 config/site.example.json 的单入口开始:一个已批准 /v entryPath、一个分配的 encodingVersionId,以及一个服务器秘密 BRANDGUARD_VERIFICATION_TOKEN。复制为已忽略的 config/site.local.json,再替换非秘密占位符。encodingVersionId 为 1–32 个可见 ASCII 字符,不限定固定长度或 GUID。Token 以 bgci_ 开头,只进入服务器秘密存储,不填入此配置、浏览器代码或配置表。
仅进阶场景使用 config/advanced-multi-entry.example.json 的 entrypoints 及 wrangler.advanced.toml:/v 与 /scan/verify 分别对应命名 secret。entrypoints 不与单入口字段混用。在知道 SKU 之前,精确路径已经选定唯一编码和凭据,不轮试备选。兼容的多个 SKU 可共用入口和编码;不同编码可使用另一个已批准的精确入口。重复、含歧义、保留或跨站入口会被预检拒绝。
首落页按 Accept-Language 权重选择已登记语言。已验明商品的整组页面随本次操作冻结,切换语言保留 __bg_receipt。单件专属路径及路径模式优先,旧字符串路径仍可用。其他商品或后改的映射不能读取本次回执。
{
"packageVersion": "1.3.3",
"httpApiVersion": "v1",
"apiOrigin": "https://ASSIGNED-API-ORIGIN.example",
"websiteOrigin": "https://website.example",
"mode": "sku",
"catalog": {
"MODEL-A": {
"defaultLanguage": "en",
"pages": {
"en": "/en/products/model-a.html",
"zh": "/zh/products/model-a.html",
"ja": "/ja/products/model-a.html",
"ko": "/ko/products/model-a.html"
}
},
"MODEL-B/R2": {
"defaultLanguage": "en",
"pages": {
"en": "/en/products/model-b.html",
"zh": "/zh/products/model-b.html",
"ja": "/ja/products/model-b.html",
"ko": "/ko/products/model-b.html"
}
}
},
"associations": {},
"regionEnabled": false,
"timeZone": "UTC",
"language": "en",
"defaultLanguage": "en",
"entryPath": "/v",
"encodingVersionId": "REPLACE_FROM_NON_SECRET_HANDOFF"
}可执行 Cloudflare 配置与部署步骤 · 普通 DNA 五种完整样例
匿名连通性探测
把 api.example.invalid 替换为管理员分配的准确来源,不带 Token 发送空 JSON。预期为 HTTP 401 和 JSON not_authorized。这只证明匿名请求到达认证层,不代表编码、Token、标签或封签有效。网关返回 HTML、重定向或 400 时,先定位入口再测实卡。
curl
API_ORIGIN='https://api.example.invalid'
curl -i --request POST "$API_ORIGIN/api/customer/v1/verifications" \
--header 'Content-Type: application/json' --data '{}'PowerShell
$apiOrigin = 'https://api.example.invalid'
try {
$r = Invoke-WebRequest -UseBasicParsing -Uri ($apiOrigin + '/api/customer/v1/verifications') -Method Post -ContentType 'application/json' -Body '{}'
$r.StatusCode; $r.Content
} catch {
$response = $_.Exception.Response
if (-not $response) { throw }
[int]$response.StatusCode
if ($_.ErrorDetails.Message) { $_.ErrorDetails.Message }
elseif ($response.PSObject.Methods.Name -contains 'GetResponseStream') {
$reader = New-Object IO.StreamReader($response.GetResponseStream())
try { $reader.ReadToEnd() } finally { $reader.Dispose() }
}
}一笔完整的合成请求与应答
下方为无电子封签的普通 NTAG 424 DNA:seal.supported=false、seal.state=null。samples/ordinary-dna.json 包含 valid、replay、invalid_signature、unknown_tag、policy_rejected 五种判定各自的完整合成请求与应答。下方标签网址、请求头和正文直接取自该文件。真实标签网址应在自己已批准的首跳捕获,保持参数顺序、大小写和百分号编码。实际参数与服务端秘密另行交付。acceptedAt 与 decidedAt 是独立的有效时间,不要求文本相等。
标签网址
https://website.example/v?h=00000000-0000-4000-8000-000000000001&e=11111111111111111111111111111111&c=0000000000000001
请求
POST https://api.example.invalid/api/customer/v1/verifications
Authorization: Bearer bgci_SYNTHETIC_EXAMPLE_ONLY
Content-Type: application/json
Idempotency-Key: synthetic-ordinary-valid
{
"encodingVersionId": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"tapUrl": "https://website.example/v?h=00000000-0000-4000-8000-000000000001&e=11111111111111111111111111111111&c=0000000000000001"
}应答
HTTP/1.1 200 OK
Content-Type: application/json
{
"receipt": {
"verificationId": "a0000000000000000000000000000000",
"result": "valid",
"decidedAt": "2026-11-16T03:15:45Z",
"acceptedAt": "2026-11-16T03:15:45Z",
"uid": "04AABBCCDDEE01",
"itemId": "BG-SYNTH-000001",
"counter": 12,
"acceptedVerificationCount": 1,
"seal": {
"supported": false,
"state": null
},
"encodingVersionId": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"clientRequestId": null,
"sku": "MODEL-A"
},
"recovered": false,
"currentEligibility": {
"eligible": true,
"checkedAt": "2026-11-16T03:15:45Z"
}
}诊断与升级处理
完整 HTTP 200 的必要内容不合格时,本次终态为未确认,不自动重验。响应体传输中断则不同:完整回执尚未收到,可恢复同一操作。可选路由资料不合格时保留有效判定并转通用结果。
参考服务提供 httpStatus、diagnosticCode 与 correlationId。401 表示凭据被拒,应核对缺失、错误环境、过期或撤销;403 核对连接、来源和权限;409 是操作冲突。bgci_ 前缀不合格或 secret 绑定缺失属于发送前配置错误。可分享生成的支持关联号,不分享 Token 值、完整碰卡网址、IP 或上游私密正文。
从 1.3 / 1.3.1 升级时,修改在 401/403 后保留原请求的队列:1.3.3 清除敏感未决资料并结束该次提交。修正配置后重新碰实体标签。网络不确定、202、429、503 仍按原键、正文和环境恢复。本包的测试结果不能替代客户网站或实卡验收。