Platform

← 返回客户后台 · English

网站与 API 集成指南

BrandGuard · 将本次标签验证显示在您的网站,或连接业务系统。

先按目标选择

目标入口
在 BrandGuard 查看结果单件选择 BrandGuard;无需网站接入
验证后打开普通网页单件选择网页目标;无需为此安装组件
在自己的网站显示官方面板下方 WordPress / 其他网站路线
标签先打开自己网站,由服务器验证实时 NFC API;需要网站工程师开发入口与结果页
同步单件及查询历史验证业务数据 API;独立且按需使用

官网服务器使用验真服务器令牌提交 NFC 碰卡。ERP 或仓储系统使用业务数据令牌读取或同步单件。

官方面板显示此次访问的验真结果。需要查询历史记录时,业务服务器可以调用业务系统 API。

WordPress / WooCommerce

  1. 账户管理员在「集成」的「WordPress 验真插件」启动 WordPress 安装。输入最终 HTTPS 网站地址;若 WordPress 安装在子目录中,请包含子目录。
  2. 选择已有产品和实际产品页面路径。核对网址与实物的跳转目标是否一致,再保存。
  3. 下载该网站专属的插件 ZIP,在 WordPress 的「插件 → 安装插件 → 上传插件」中安装并启用。安装授权有效期为 15 分钟;过期请重新下载。新下载会替换先前未使用的授权。
  4. 打开 WordPress「设置 → BrandGuard」。插件尝试关联下载时选择的账号和网站,自动验证网站所有权并获取配置;确认连接成功后,回到 BrandGuard 的「WordPress 验真插件」,刷新状态并点击「开启在官网显示结果」,再回到插件设置点击「刷新配置」。
  5. 打开对应产品页面查看验证区,再用手机轻触真实标签完成本次访问验证。

自动位置优先使用 WooCommerce 产品位置,并为缺少标准钩子的主题提供备用显示。需要精确安排位置时,可以选择短代码方式,将 [brandguard_proof] 放入对应页面或主题构建器的文本/短代码模块;同一页面只显示一个面板。

多个产品页可以使用同一网站的官方面板登记。修改接入中心的配置后,插件会重新同步;也可在插件设置点击「刷新配置」。缓存和主题设置可能需要刷新。已有手动配置的旧版插件升级后继续保留原设置,连接自助账号后才改用该连接配置。

启用会把品牌默认改为官方面板展示;沿用此默认的相关单件会采用组件方式,明确选择普通网页跳转的单件保持原方式。已有目标网址不变;仍需检查网页并完成实体 NFC 测试。

ZIP 中的短期安装授权只能连接指定网站。不要把它公开下载或转发给其他网站。安装中断或授权过期时重新下载即可;插件使用 ZIP 中的安装授权。

其他网站:官方面板

  1. 在接入中心选择「其他网站」,添加最终 HTTPS 网站地址、产品和目标路径。
  2. 按站点详情提供的路径放置所有权挑战文件,保持公开可访问,随后点击验证。文件位置、内容和检查结果都以该站点详情为准。
  3. 将接入中心生成的官方脚本放在页面 <head> 中,早于分析、广告和会话录制脚本执行;在产品内容中插入指定容器。
  4. 完成网站验证,点击「开启在官网显示结果」,检查产品网址、组件显示和真实 NFC 读取。

脚本处理一次性验证凭据,验证区由 BrandGuard 官方来源提供。不要加 defer、async 或交给延迟执行工具;不要复制凭据到分析系统,也不要将历史记录画成「本次已验证」。

如网站设置 CSP,仅按此网站生成的安装资料开放准确的脚本、frame 和连接来源。当前 Staging 官方脚本为 https://staging-verify.brandguard.co/widget/v1.js;正式环境的来源须从该环境生成的资料取得。不要通过替换域名或关闭浏览器安全机制解决错误。

网站需要自行显示本次验证结果时,可使用实时验证 API:标签先到已批准的网站,网站服务器提交原始扫描 URL。官网服务器使用实时验真连接、匹配的标签编码和验真权限,工厂使用兼容的 Writer;既有官方面板可以继续使用。Customer API 的 scans 仍是历史查询。

客户网站首跳实时验证

账户管理员验证网站所有权,建立实时验真连接并配置标签编码;网站工程师用准确交接参数实现已保存的准确标签首跳路径、可信结果、恢复及产品映射,再对齐工厂写入和实体测试。 完整实施步骤与样例

业务系统 API:按需接入客户服务器

客户的 ERP、仓库或其他业务系统需要同步单件、读取历史验证活动时,才需要此 API。后台手工操作、Writer 写卡及 Live NFC 验证本身不要求额外开通 Business API。它不能写实体标签、改 UID/密钥、建立产品目录、提交工厂任务、登记质检/发货,或执行一次新鲜碰标签验证。

  1. 账户管理员进入 Integrations → Business system API → Create business data token,只勾选该服务器需要的权限并设置期限。原文仅显示一次,保存在服务器秘密配置中。
  2. 从产品/规格页或已绑定目录的单件响应取得现有 productCode 与 variantSKU。此 API 没有产品目录列表/新建接口,产品显示名称不能代替目录身份。
  3. 先在 Staging 读取记录,完成分页、环境/租户作业隔离、版本处理及持久化恢复,再导入已批准测试数据。
  4. 保存对账回执;轮换时先配置同租户的新 Token,确认可用后再撤销旧凭据。
权限用途
items:read读取单件列表/详情及已提交的导入回执。
items:write按目录、版本与生命周期规则导入或修改允许的数据;不包含回执查询,需要恢复查询时同时勾选 items:read。
scans:read读取历史验证活动,包含拒绝记录;不能当作本次碰标签证明。

Staging:https://staging-console.brandguard.co/api/customer/v1
正式环境:从已批准的正式环境后台取得准确的 API URL。使用 Authorization: Bearer YOUR_SERVER_TOKEN;两环境的凭据与记录独立。Business 权限不能替代 Live 的 verifications:execute/verifications:read。

接口权限与行为
GET /items?page=1&pageSize=100items:read;可按 q 搜索,每页最多 200。按 total/pageSize 翻页;分页不是冻结的数据快照。
GET /items/{itemId}items:read;对路径 ID 做 URL 编码。返回 mutationRevision、routeRevision 及目录/编码标识。
POST /items/importitems:write;规范目录绑定导入/更新,要求已有 ProductCode + VariantSKU;每行最多 1,000 件,总展开最多 10,000 件。
GET /items/imports/{receiptKey}items:read;查询同租户已提交回执,包含新建 Item ID,不是标签认证证明。
PUT /items/{itemId}items:write;旧式兼容 upsert。路径 ID 不存在时可建立未绑定目录的 LegacySnapshot,新记录优先用规范导入。修改已有历史身份/生产字段需当前 expectedRevision + reason,并通过生命周期检查;已绑定、锁定、发货记录仍受保护。
POST /items/bulk-upsertitems:write;最多 500 个兼容 upsert,同样受限制;拒绝时整批回滚,没有外部幂等保证。
GET /scans?page=1&pageSize=100scans:read;可按 itemId 筛选。历史总数可能包含失败,并非消费者页的接受验证次数。

规范导入只支持 OpenAPI 列出的字段,不是后台所有功能的镜像。不支持的逐件属性/Live 编码选择仍用后台。符合资格的路由修改应把 GET Item 的 routeRevision 填为 expectedRouteRevision;生产修改把 mutationRevision 填为 expectedMutationRevision,并提供 changeReason。读取版本不等于获得修改锁定记录的许可。

规范导入与结果不明时的恢复

POST /api/customer/v1/items/import
Idempotency-Key: your-durable-job-unique-key
Content-Type: application/json

{"rows":[{"productCode":"EXISTING_PRODUCT_CODE","variantSKU":"EXISTING_SKU","quantity":1,"factoryIntent":"NonFactory"}]}

新建必须指定 factoryIntent:非工厂样品用 NonFactory;生产准备用 PrepareForFactory 并提供 batch。后者只准备记录,不会自动提交工厂任务。此操作会创建业务数据。

  1. 首次发送前,把租户、环境、唯一 key 及完整请求内容保存到受保护的持久化存储。key 为 1–128 个 ASCII 字母、数字或 ._:-,不含空格。每次新导入使用独立 key。
  2. 通过 Idempotency-Key 发送。提交回执包含 receiptKey(与 key 相同)、idempotencyGuaranteed:true、数量、committedAt 及 items[] 的 rowNumber、customerItemId、itemId、disposition。保存回执并逐件对账;计划数据行号从 2 开始。
  3. 超时、断线或收到不可解析响应时,保留原 key/内容。遵守 Retry-After 后,按原 key 查询回执。找到即按回执对账;404 仅表示此刻没有查到已提交回执,另一请求可能仍在执行。可用原 key/原内容重新发送 POST,不能换新 key。同租户替换 Token 后仍可恢复。
  4. 同 key、同规范内容返回已有回执(replayed:true);改内容会返回 409 IdempotencyConflict。先核清旧作业,再把修正内容作为经确认的新作业使用新 key,不能修改未决重试内容。

为兼容旧客户端,此 header 仍是可选。省略后每次调用都可能新建 Item,返回 idempotencyGuaranteed:false 及明确 warning;服务器虽生成 receiptKey,但丢失响应时客户不知道该 key。无 key 导入或旧式 PUT/bulk 结果不明时,不可盲目重发,应先核对已有记录。已提交回执不会自动过期。

错误与工程示例

400 表示输入/计划被拒绝;未知 JSON 字段返回 HTTP 校验问题,不会默默保存。CatalogBindingRequired(缺产品/规格/行)与 ImportPlanRejected 均包含 errors:[{rowNumber,field,code,messageKey,args}],应显示行/字段并逐项修正。401 为 Token 无效/过期/撤销或租户停用;403 为缺权限;409 为幂等、版本或生命周期冲突。这些错误不能盲目重试。网关响应可能不是 JSON。读取遇网络、429/5xx 可按等待时间重试;写入结果不明必须按上方恢复流程处理。

OpenAPI 提供精确请求/响应结构。读取 CLI 会翻完全部页并按 ID 去重,期间并发变化仍需对账。两个 Node 文件须下载到同一服务器目录:读取 CLI 会引用客户端模块。导入模块提供 prepareImport、submitPreparedImport、recoverImport,仅引入模块不会发送请求;客户程序仍需实现受保护的持久化存储与重试调度。

切换到正式环境

正式账户、网站批准、接入、Token、编码与单件需分别配置核验;WordPress 需正式网站专属 ZIP,通用组件使用正式生成代码,Live API 需正式编码与匹配标签。不能仅替换 API base 或域名,Staging 参数与已写标签不会自动迁移。保留旧记录,再做正式环境授权范围内的实体验收。

接入检查与下一步

状态含义与处理
等待网站验证检查最终域名、HTTPS、安装路径、挑战文件及防火墙。验证请求不会跟随重定向。
安装授权过期 / 已使用重新下载该站点安装包,或按插件提示导入新的连接授权。
配置已同步表示插件已拿到站点配置;仍需检查产品页面是否显示组件。
产品网址不匹配检查产品和实物的实际跳转目标;已写实物保留原网址,保存网站配置不会自动重写它。
普通访问 / No live verification直接打开产品页应显示中性状态。用手机重新轻触标签,在同一浏览器中继续跳转;不要复制旧验证链接。
组件没有显示检查目标路径、位置和缓存。自动位置不适合主题时,使用短代码模块并预览。
环境尚未开放网站已配置与平台允许投放是不同状态;客户设置不能开启平台尚未开放的正式环境。
管理员已停用网站批准联系管理员复核。客户重新启用或重新安装插件不能绕过管理员停用。
官方面板登记已撤销账户管理员可重新授权安装,以恢复配置同步。网站所有权批准单独管理。

最终验收应分别检查:完整封签、已打开封签、普通访问、过期访问。标签验证通过与包装是否开封分别展示;开封不应被伪装成完整包装。

接入:待验证网站可继续原登记,复制或下载原公开 JSON;每个 Live API 接入可重开网站工程师资料,明确选择编码及测试 Item、下载非秘密参数,并按步骤处理 Token 遗失。详见实时验证 API 指南。Items 交接清单显示准确范围与数量。