ACCUZ® Brand Guard™ / SDK 1.3.3 / HTTP API v1

首次接入与完整请求

从这里开始

准备首次真实请求

先运行 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 仍按原键、正文和环境恢复。本包的测试结果不能替代客户网站或实卡验收。