Platform
← 返回客户后台 · English网站与 API 集成指南
BrandGuard · 将本次标签验证显示在您的网站,或连接业务系统。
先按目标选择
| 目标 | 入口 |
|---|---|
| 在 BrandGuard 查看结果 | 单件选择 BrandGuard;无需网站接入 |
| 验证后打开普通网页 | 单件选择网页目标;无需为此安装组件 |
| 在自己的网站显示官方面板 | 下方 WordPress / 其他网站路线 |
| 标签先打开自己网站,由服务器验证 | 实时 NFC API;需要网站工程师开发入口与结果页 |
| 同步单件及查询历史验证 | 业务数据 API;独立且按需使用 |
官网服务器使用验真服务器令牌提交 NFC 碰卡。ERP 或仓储系统使用业务数据令牌读取或同步单件。
官方面板显示此次访问的验真结果。需要查询历史记录时,业务服务器可以调用业务系统 API。
WordPress / WooCommerce
- 账户管理员在「集成」的「WordPress 验真插件」启动 WordPress 安装。输入最终 HTTPS 网站地址;若 WordPress 安装在子目录中,请包含子目录。
- 选择已有产品和实际产品页面路径。核对网址与实物的跳转目标是否一致,再保存。
- 下载该网站专属的插件 ZIP,在 WordPress 的「插件 → 安装插件 → 上传插件」中安装并启用。安装授权有效期为 15 分钟;过期请重新下载。新下载会替换先前未使用的授权。
- 打开 WordPress「设置 → BrandGuard」。插件尝试关联下载时选择的账号和网站,自动验证网站所有权并获取配置;确认连接成功后,回到 BrandGuard 的「WordPress 验真插件」,刷新状态并点击「开启在官网显示结果」,再回到插件设置点击「刷新配置」。
- 打开对应产品页面查看验证区,再用手机轻触真实标签完成本次访问验证。
自动位置优先使用 WooCommerce 产品位置,并为缺少标准钩子的主题提供备用显示。需要精确安排位置时,可以选择短代码方式,将 [brandguard_proof] 放入对应页面或主题构建器的文本/短代码模块;同一页面只显示一个面板。
多个产品页可以使用同一网站的官方面板登记。修改接入中心的配置后,插件会重新同步;也可在插件设置点击「刷新配置」。缓存和主题设置可能需要刷新。已有手动配置的旧版插件升级后继续保留原设置,连接自助账号后才改用该连接配置。
启用会把品牌默认改为官方面板展示;沿用此默认的相关单件会采用组件方式,明确选择普通网页跳转的单件保持原方式。已有目标网址不变;仍需检查网页并完成实体 NFC 测试。
ZIP 中的短期安装授权只能连接指定网站。不要把它公开下载或转发给其他网站。安装中断或授权过期时重新下载即可;插件使用 ZIP 中的安装授权。
其他网站:官方面板
- 在接入中心选择「其他网站」,添加最终 HTTPS 网站地址、产品和目标路径。
- 按站点详情提供的路径放置所有权挑战文件,保持公开可访问,随后点击验证。文件位置、内容和检查结果都以该站点详情为准。
- 将接入中心生成的官方脚本放在页面
<head>中,早于分析、广告和会话录制脚本执行;在产品内容中插入指定容器。 - 完成网站验证,点击「开启在官网显示结果」,检查产品网址、组件显示和真实 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/密钥、建立产品目录、提交工厂任务、登记质检/发货,或执行一次新鲜碰标签验证。
- 账户管理员进入 Integrations → Business system API → Create business data token,只勾选该服务器需要的权限并设置期限。原文仅显示一次,保存在服务器秘密配置中。
- 从产品/规格页或已绑定目录的单件响应取得现有
productCode与variantSKU。此 API 没有产品目录列表/新建接口,产品显示名称不能代替目录身份。 - 先在 Staging 读取记录,完成分页、环境/租户作业隔离、版本处理及持久化恢复,再导入已批准测试数据。
- 保存对账回执;轮换时先配置同租户的新 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=100 | items:read;可按 q 搜索,每页最多 200。按 total/pageSize 翻页;分页不是冻结的数据快照。 |
| GET /items/{itemId} | items:read;对路径 ID 做 URL 编码。返回 mutationRevision、routeRevision 及目录/编码标识。 |
| POST /items/import | items: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-upsert | items:write;最多 500 个兼容 upsert,同样受限制;拒绝时整批回滚,没有外部幂等保证。 |
| GET /scans?page=1&pageSize=100 | scans: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。后者只准备记录,不会自动提交工厂任务。此操作会创建业务数据。
- 首次发送前,把租户、环境、唯一 key 及完整请求内容保存到受保护的持久化存储。key 为 1–128 个 ASCII 字母、数字或
._:-,不含空格。每次新导入使用独立 key。 - 通过 Idempotency-Key 发送。提交回执包含
receiptKey(与 key 相同)、idempotencyGuaranteed:true、数量、committedAt及items[]的 rowNumber、customerItemId、itemId、disposition。保存回执并逐件对账;计划数据行号从 2 开始。 - 超时、断线或收到不可解析响应时,保留原 key/内容。遵守 Retry-After 后,按原 key 查询回执。找到即按回执对账;404 仅表示此刻没有查到已提交回执,另一请求可能仍在执行。可用原 key/原内容重新发送 POST,不能换新 key。同租户替换 Token 后仍可恢复。
- 同 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 交接清单显示准确范围与数量。