# Weight-Based Products System

Complete Help & Documentation Center

## System Overview

##### What is This?

The Weight-Based Products system enables your store to sell items like meat, fruits, and vegetables by weight using EAN-13 barcodes that encode both product identity and weight.

##### Key Features

- EAN-13 compatible barcodes
- Weight embedded in barcode
- Automatic price calculation
- Tare weight handling
- Works with any compatible scale

##### How It Works

1. Create Products: Configure weight-based products with pricing and tare weights
2. Export to Scale: Download CSV and import to your label-printing scale
3. Weigh Items: Staff weighs items and scale generates barcodes automatically
4. Scan at Checkout: POS reads barcode, extracts weight, calculates price
5. Complete Sale: Customer pays the exact amount for the exact weight

#### Barcode Format

##### 2 0 1 2 3 4 5 0 1 5 0 0 7

20

Type
(Meat)

12345

Product
Code

01500

Weight
(1500g)

7

Check
Digit

#### Product Categories

??
Meat (20)
??
Fruits (21)
??
Vegetables (22)
??
Dairy (23)
??
Bakery (24)

## Complete Documentation

#### Setup Guide

Complete step-by-step instructions to set up the system from scratch. Covers database migration, product creation, testing, and deployment.

Open Setup Guide

#### Scale Integration Guide

How to integrate with different types of scales. Covers label-printing scales, external printers, Android/Tablet, and PC-based solutions.

Open Integration Guide

#### Configuration Templates

Specific setup instructions for popular scale models including CAS, Bizerba, Toledo, Avery Berkel, and Digi scales.

Open Configuration Guide

#### Technical Summary

In-depth technical documentation covering system architecture, database schema, API endpoints, and price calculation logic.

Open Technical Docs

#### Staff Quick Reference

Simple guide for counter staff. Print and laminate for quick access at butchery, produce, and deli counters.

Open Quick Reference

#### Complete Documentation Index

Master index with links to all documentation, quick start guide, and navigation to specific topics.

Open Master Index

## Quick Start (30 Minutes)

Prerequisites: CNPERP system running, PostgreSQL database configured, FastAPI server active on port 8010.

##

Add weight-based product fields to your database:

`cd C:\dev\cnperp-python
.\.venv\Scripts\Activate.ps1
python add_weight_based_products.py`
Expected: ? Weight-based product fields added successfully!

##

Create weight-based products:

1. Open: Products Page
2. Click "Add New Product"
3. Fill in basic details (Name, SKU, Category)
4. Check "Enable Weight-Based Selling"
5. Select Product Type (Meat, Fruits, etc.)
6. Enter 5-digit Product Code (e.g., 12345)
7. Set Price per kg (e.g., 125.00)
8. Set Tare weight if applicable (e.g., 50g for packaging)
9. Save Product

Tip: Create 5-10 sample products to test with.

##

###### Option A: Web Generator

Open Barcode Generator

1. Select a product from dropdown
2. Enter weight (e.g., 1500 grams)
3. Click "Generate Barcode Label"
4. Verify barcode and price are correct

###### Option B: Scale Simulator

`python scripts/scale_simulator.py`

Follow interactive prompts to simulate complete workflow.

##

Export products to import into your scale:

All Products Meat Only Fruits Only Vegetables Only

Next: Import CSV to your scale via USB, Network, or manual entry. See Configuration Templates for your specific scale model.

## Frequently Asked Questions

Q: What scales are compatible with this system?
A: Any label-printing scale that supports EAN-13 barcodes with configurable format. Popular models include CAS CL-5000, Bizerba GLMI-800, Mettler Toledo 8530, Avery Berkel HL122, and Digi SM-300. See the Scale Integration Guide for details.
Q: How is the price calculated?
A: Price = (Gross Weight - Tare Weight) × Price per kg
Example: 1500g gross - 50g tare = 1450g net = 1.45kg × R125/kg = R181.25
Q: What is tare weight?
A: Tare weight is the weight of packaging (tray, wrapper, container) that should not be charged to the customer. The system automatically subtracts this when calculating the price.
Q: Can I test without a physical scale?
A: Yes! Use the Barcode Generator web interface or run the scale simulator: `python scripts/scale_simulator.py`
Q: Why won't my barcode scan?
A: Common causes:

- Scale configured for wrong barcode type (must be EAN-13, not CODE-128)
- Checksum calculation not enabled in scale
- Poor print quality - clean the printhead
- Barcode too small or damaged

See the Troubleshooting Guide.
Q: How do I update prices on the scale?
A:

1. Update prices in CNPERP products page
2. Export new CSV: Download Here
3. Import to scale via USB/Network

For automated sync, see the Network Scale Management section in the setup guide.
Q: What do the barcode prefixes mean?
A: The first 2 digits identify the product category:

- 20 = Meat (Beef, Pork, Chicken, Lamb)
- 21 = Fruits (Apples, Bananas, Oranges)
- 22 = Vegetables (Tomatoes, Lettuce, Carrots)
- 23 = Dairy (Cheese, Butter by weight)
- 24 = Bakery (Bread, Cakes by weight)

Q: Can I use this for items sold by piece?
A: No, this system is specifically for weight-based products. For items sold by piece (count), use regular products with standard barcodes.

## Tools & Utilities

##### Barcode Generator

Generate and print weight-based barcode labels for your counter staff.

Open Tool

##### Product Management

Create and configure weight-based products with pricing and constraints.

Manage Products

##### Export for Scale

Download CSV file to import products into your label-printing scale.

Download CSV

#### API Endpoints

Endpoint | Method | Description | Action
--- | --- | --- | ---
`/api/v1/weight-products/weight-products` | GET | List all weight-based products (filter by category optional) | Test
`/api/v1/weight-products/parse-weight-barcode` | POST | Parse barcode and return product with calculated price |
`/api/v1/weight-products/export-for-scale` | GET | Export products as CSV for scale import | Download

##### Documentation

Loading...

Loading documentation...

`r`n
`r`n