Skip to main content

Barcode discovery (product creation)

Barcode discovery lets staff create a place product by scanning a packaged product barcode. The POS calls the backend, which looks up public catalog data and opens the product editor with fields prefilled.

Preconditions​

  • A CODESCAN device row must exist on the connected TPV service (place.HasCodeScan).
  • The operator needs ProductManage permission (createproduct).

Without a configured scanner, the discovery option is hidden (same rule as barcode assignment in product/shortcut editors).

Operator flow​

  1. Open Products in the place view.
  2. Tap the New product thumb (same as creating a product manually).
  3. Choose Add product by barcode in the type selector (group, product, generic, family…).
  4. Scan the barcode with the HID scanner (or use the barcode HID simulator in development).
  5. If the barcode already exists locally (doBarCode), show a warning toast (@place_product_item_discovery_barcode_exists) and stop — no backend call, no new product.
  6. Otherwise the backend queries external sources and emits a new product with best-effort prefill (barcode, name in the DTO language, remote photo URL when available).
  7. The product editor opens for review; complete missing fields and Accept — normal AddProduct + sync.

External sources (backend only)​

SourceRole
Open Food FactsPrimary catalog for packaged goods (name, brand, category, image, ingredients, allergens, nutrition).
Verified by GS1GTIN checksum validation; optional remote verification when BUILD_GS1_VERIFY_URL and BUILD_GS1_API_KEY are configured. GS1 does not invent product names when OFF has no data.

The browser never calls OFF or GS1 directly. All lookups go through GET/POST /barcode/discover.

API​

Query/body: barcode (normalized GTIN/EAN). Standard session params: device, session, place.

Response shape: BarcodeDiscoveryResult (found, name, brand, category, imageUrl, ingredients, allergens, nutrition, gs1Valid, gs1Licensee, sources, hint). See OpenAPI tag Barcode.

Limits​

  • Read-only prefill; no bidirectional sync with OFF/GS1.
  • Does not replace the internal place catalog or catalog-template products.
  • Remote image URLs are stored as-is; upload/sync policies follow the normal product photo flow.
  • Partial or missing external data still allows manual completion (barcode is always assigned; best-effort prefill, no operator warnings).

Server configuration​

Optional environment variables in server/.env:

VariablePurpose
BUILD_OPENFOODFACTS_USER_AGENTUser-Agent for OFF requests (recommended)
BUILD_OPENFOODFACTS_BASE_URLOFF API base (default: world.openfoodfacts.org)
BUILD_GS1_VERIFY_URLOptional GS1 verification API base URL
BUILD_GS1_API_KEYBearer token for GS1 API when configured
BUILD_BARCODE_DISCOVERY_TIMEOUTHTTP timeout seconds (default: 7)