Platform

← Customer workspace · 中文

Website & API integration guide

BrandGuard · Display official verification on your website or connect your business system.

Choose by your goal

GoalSetup
View results on BrandGuardSelect BrandGuard for the Item; no website integration is needed.
Open an ordinary webpage after verificationSet the Item destination; the Item opens that address directly.
Display the official panel on your websiteUse WordPress / Other websites below.
Open your website first and verify from your serverUse Live NFC API; an engineer implements the entry and result page.
Synchronize Items and read historical verificationsUse Business data API when needed, independently of display/live verification.

The website server uses a verification server token to submit NFC taps. An ERP or warehouse system uses a business data token to read or synchronize Item records.

The official panel displays the verification result for the current visit. Historical scan records are available through the Business system API.

WordPress verification plugin

  1. As an account administrator, open Integrations → WordPress verification plugin and start the WordPress setup. Enter the final HTTPS home URL, including any WordPress subdirectory.
  2. Select existing products and their exact page paths. Compare these with actual item destinations before saving.
  3. Download the site-specific ZIP. In WordPress, choose Plugins → Add New → Upload Plugin, then install and activate. Installation authorization lasts 15 minutes. Download again if it expires; a new download replaces an unused grant.
  4. Open Settings → BrandGuard. The plugin attempts to connect the account and website selected at download, verifies site ownership, and receives configuration. After connection succeeds, return to BrandGuard Integrations, refresh status, and choose Enable results on website. Then return to the plugin settings and choose Refresh configuration.
  5. Open a configured product page, check the panel, then tap a real NFC tag on your phone to test the complete flow.

Automatic placement uses the WooCommerce product position when available and provides fallback placement for themes without the standard hook. To choose an exact location, select shortcode placement and insert [brandguard_proof] into the matching page or a builder text/shortcode module. Only one panel is rendered per page.

A site supports multiple product paths. The plugin synchronizes changes from the integration center; you can also choose Refresh configuration in the plugin settings. Clear relevant page caches after changing configuration. Existing manually configured installations retain their settings until you connect a self-service account.

Enabling switches this customer account to official widget delivery. Related Items that inherit the brand default use the official panel. Items explicitly set to ordinary webpage redirects retain that mode. Existing Item destination URLs are unchanged; website checks and physical NFC acceptance are still required.

A downloaded ZIP contains a short-lived authorization for one website. Do not publish it as a public download or install it on another site. The plugin uses the installation authorization in this ZIP.

Other websites: official verification panel

  1. Register the official panel for your website. Enter its final HTTPS URL, select the products and specify their exact page paths.
  2. Publish the ownership challenge file at the path shown in site details. Keep it publicly reachable, then run verification.
  3. Copy the generated official script into the page's <head>, before analytics, advertising, or session replay scripts. Put its container where the verification panel should appear.
  4. Choose Enable results on website, inspect the target pages, and perform a fresh physical NFC tap.

Do not apply defer, async, delayed execution, or script mirroring to the official bootstrap. It removes the one-time URL fragment before other scripts execute. Do not copy proof parameters into analytics or recreate a current-verification badge from historical records.

If you use CSP, allow only the exact script, frame and connection origins shown in the generated installation details for this website. In current Staging the official script is https://staging-verify.brandguard.co/widget/v1.js. Obtain production origins from that environment generated details. For your own verification interface, use the Live verification API: the tag opens an approved website, and its server submits the original scanned URL. This requires a separate verification connection, encoding configuration, verification scopes and the compatible tag writer. Existing panel installations remain supported; historical scans do not prove a fresh visit.

Customer website first: Live verification

The customer administrator verifies website ownership and configures a verification connection and encoding. The engineer uses its exact handoff parameters to implement the exact saved tag entry path, trusted results, recovery and product mapping, then aligns factory writing and physical tests. Complete implementation steps and examples

Business system API: optional server integration

Use this API when an ERP, warehouse or other business server needs to synchronize Items or read historical verification activity. It is not required for manual workspace/Writer operation or Live NFC verification. It does not write tags, change UID/keys, create product catalogs, submit factory tasks, record quality/dispatch or execute a fresh NFC verification.

  1. An account administrator opens Integrations → Business system API → Create business data token. Choose only the scopes this server needs and an expiry. The plaintext appears once; store it in the server secret manager.
  2. Obtain existing productCode and variantSKU from Products/SKUs or a known product-bound Item response. This API has no product catalog listing/creation endpoint. Do not substitute a display name for catalog identity.
  3. Start with a read in Staging. Implement pagination, environment/tenant job separation, revision handling and durable write recovery before importing approved test records.
  4. Keep reconciliation receipts, rotate using a replacement same-tenant token, and revoke the old credential only after confirming the replacement works.
ScopePermission
items:readRead Item pages/details and committed import receipts.
items:writeImport or modify permitted Item data under catalog, revision and lifecycle checks. Does not include receipt lookup; add items:read when recovery needs it.
scans:readRead historical verification activity, including rejected requests; never fresh-visit proof.

Staging: https://staging-console.brandguard.co/api/customer/v1
Production: obtain the exact API URL from the approved production workspace. Use Authorization: Bearer YOUR_SERVER_TOKEN. Credentials and records are separate by environment and tenant. Business scopes cannot substitute for Live verifications:execute/verifications:read.

EndpointScope and behavior
GET /items?page=1&pageSize=100items:read; optional q, maximum pageSize 200. Follow total/pageSize; pages are not a frozen snapshot.
GET /items/{itemId}items:read; URL-encode the ID. Returns mutationRevision, routeRevision and catalog/encoding identifiers for supported updates.
POST /items/importitems:write; canonical product-bound creation/update. Existing ProductCode + VariantSKU required. At most 1,000 per row and 10,000 expanded Items.
GET /items/imports/{receiptKey}items:read; same-tenant committed receipt including generated Item IDs; not raw authentication proof.
PUT /items/{itemId}items:write; legacy compatible upsert. A missing path ID can create a LegacySnapshot without catalog binding. Prefer canonical import for new records. Existing legacy identity/production changes need current expectedRevision + reason and must pass lifecycle checks; bound/locked/delivered Items remain protected.
POST /items/bulk-upsertitems:write; up to 500 compatible upserts, same restrictions; rejected batch rolls back. No external idempotency guarantee.
GET /scans?page=1&pageSize=100scans:read; optional itemId. Historical activity can include failures and is not the accepted-verification counter.

The canonical import supports the fields in its OpenAPI schema, not every field available in the customer workspace. Use the workspace for unsupported attributes/Live encoding choices. Canonical eligible route changes use GET Item's routeRevision as expectedRouteRevision, and production changes use mutationRevision as expectedMutationRevision, with changeReason. Reading a revision does not grant permission to change a locked record.

Safe canonical import and recovery

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"}]}

New records require factoryIntent: NonFactory for a non-factory sample, or PrepareForFactory with batch for factory preparation. The latter prepares records; it does not submit a factory task. This operation creates business data.

  1. Before the first request, durably store the tenant, environment, unique key and exact request body. The key is 1–128 ASCII letters/digits or ._:-; no spaces. Use a distinct key for each new reviewed import.
  2. Send that key in Idempotency-Key. A committed response contains receiptKey (the same key), idempotencyGuaranteed:true, counts, committedAt and items[] with rowNumber, customerItemId, itemId and disposition. Persist and reconcile this receipt; plan row numbers start at 2.
  3. After a timeout, disconnect or malformed response, preserve the original key/body. Respect Retry-After, then GET the original receipt key. If found, use it. A 404 means no committed receipt was found at that moment; another request may still be running. Resend the same POST/key/body, never a new key. The same tenant can recover with a replacement token.
  4. The same key and canonical content returns the existing receipt (replayed:true). Different content returns 409 IdempotencyConflict. Corrections are a newly reviewed job with a new key after reconciling the old job; do not edit a pending retry.

The header remains optional for older clients. Without it, each call can create new Items, idempotencyGuaranteed:false and an explicit warning are returned. A receiptKey is generated, but if the response is lost that key is unknown. Do not blindly repeat an unkeyed import or legacy PUT/bulk write; reconcile existing records first. Receipts do not expire automatically.

Errors and examples

400 means rejected input/plan; unknown JSON properties produce an HTTP validation problem and are not silently saved. CatalogBindingRequired (missing product/variant/row) and ImportPlanRejected include errors:[{rowNumber,field,code,messageKey,args}]; show the row/field and resolve each cause. 401 means invalid/expired/revoked token or inactive tenant; 403 missing scope; 409 means idempotency, revision or lifecycle conflict. Do not blindly retry these. Gateway errors may be non-JSON. Reads may retry transient network/429/5xx failures after the given delay; unknown writes must use the recovery procedure above.

Use the OpenAPI for exact request/response schemas. The read CLI fetches all pages and deduplicates IDs; concurrent changes still require reconciliation. Download both Node files into one server directory: the read CLI imports the client module. The import module provides prepareImport, submitPreparedImport and recoverImport; importing it sends no request. Your application must implement protected durable storage and scheduling around these functions.

Moving to Production

Configure and verify the Production account, website approval, connection, tokens, encoding and Items separately. WordPress needs its Production site-specific ZIP; other websites use the panel code generated in Production; Live API needs Production encoding and matching labels. Replacing only an API base/domain does not migrate Staging records or already written labels. Preserve prior records and repeat authorized physical acceptance in Production.

Connection checks

StatusMeaning / next action
Ownership pendingCheck final domain, HTTPS, installation path, public challenge, and firewall. Verification does not follow redirects.
Authorization expired / usedDownload a fresh site package or import the new connection authorization as instructed.
Configuration synchronizedThe plugin received its settings. Inspect the actual product page before testing NFC.
Destination mismatchCompare product and captured item routes. Saving website settings does not rewrite existing item destinations.
No live verificationA direct page visit should be neutral. Tap the tag again and continue in the same browser; do not reuse an old verification link.
Missing panelCheck exact path, placement, and page cache. Use a shortcode module if automatic placement is unsuitable for your theme.
Environment unavailableCustomer configuration cannot enable a platform environment whose live delivery is disabled.
Origin disabled by an administratorContact the administrator for review. Re-enabling or reinstalling the plugin cannot override that decision.
Panel registration revokedAn account administrator can authorize a new installation to resume configuration updates. Website ownership approval is managed separately.

Acceptance should cover sealed, opened, ordinary, and expired visits. Tag authentication and package condition are separate; an authenticated opened tag must not appear as a sealed package.

Setup: pending ownership checks can be reopened with the original public JSON. Each Live API connection offers a website engineer handoff with explicit encoding and test Item selection, non-secret parameter download, and safe token replacement steps. See the Live verification guide. Items handoff manifests state their exact scope and count.