POS Products (منتجات نقاط البيع)

The POS Products endpoints provide optimized product retrieval for the POS interface. They return active products with stock quantities, support category filtering, text search across multiple fields, and barcode/SKU lookup.

API Endpoints

Method	Endpoint	Description	Permission
GET	/api/pos/products	List products for POS grid	pos.products.view
GET	/api/pos/products/search	Search products by name/code/SKU/barcode	pos.products.search
GET	/api/pos/products/barcode/{code}	Look up product by exact barcode or SKU	pos.products.view

Query Parameters

List Products (GET /products)

Parameter	Type	Description
warehouse_id	integer	Filter stock balances to a specific warehouse
category_id	integer	Filter by product category
per_page	integer	Items per page (default: 50, max: 100)

Search Products (GET /products/search)

Parameter	Type	Required	Description
q	string	yes	Search term (min 1 char). Searches name, name_ar, code, sku, barcode
warehouse_id	integer	no	Filter stock balances to a specific warehouse
per_page	integer	no	Items per page (default: 20, max: 50)

Barcode Lookup (GET /products/barcode/{code})

Parameter	Type	Description
warehouse_id	integer	Filter stock balances to a specific warehouse

The {code} URL parameter matches against the product's barcode or sku field exactly.

Request / Response Examples

List Products (Grid)

curl

curl -G /api/pos/products \
  -H "Authorization: Bearer {token}" \
  -d "warehouse_id=1" \
  -d "category_id=3" \
  -d "per_page=50"

Dart

final response = await dio.get('/api/pos/products', queryParameters: {
  'warehouse_id': 1,
  'category_id': 3,
  'per_page': 50,
});

Response 200 OK

{
  "data": [
    {
      "id": 10,
      "name": "Wireless Mouse",
      "name_ar": "ماوس لاسلكي",
      "code": "PROD-000010",
      "sku": "WM-001",
      "barcode": "BC00000010",
      "sale_price": "15.500",
      "category": { "id": 3, "name": "Electronics" },
      "base_unit": { "id": 1, "name": "Piece" },
      "stock_balances": [
        { "warehouse_id": 1, "quantity": "45.000" }
      ]
    }
  ],
  "links": { "..." : "..." },
  "meta": { "current_page": 1, "last_page": 3, "per_page": 50, "total": 120 }
}

Search Products

curl

curl -G /api/pos/products/search \
  -H "Authorization: Bearer {token}" \
  -d "q=mouse" \
  -d "warehouse_id=1"

Dart

final response = await dio.get('/api/pos/products/search', queryParameters: {
  'q': 'mouse',
  'warehouse_id': 1,
});

Barcode Lookup

curl

curl -G /api/pos/products/barcode/BC00000010 \
  -H "Authorization: Bearer {token}" \
  -d "warehouse_id=1"

Dart

final response = await dio.get('/api/pos/products/barcode/BC00000010', queryParameters: {
  'warehouse_id': 1,
});

Response 200 OK -- Returns a single product object (same structure as the list).

Response 404 Not Found -- If no product matches the barcode or SKU.

{
  "message": "Product not found for barcode: BC99999999"
}

Business Rules

1. Active products only -- All endpoints only return products where is_active = true and type = 'product' (services are excluded).
2. Company scoping -- Products are filtered to the authenticated user's company.
3. Stock with warehouse filter -- When warehouse_id is provided, only the stock balance for that warehouse is returned. Otherwise, all warehouse balances are included.
4. Barcode + SKU fallback -- The barcode lookup matches against both barcode and sku fields, returning the first match.
5. Pagination limits -- The grid endpoint caps at 100 items per page; the search endpoint caps at 50.
6. Search fields -- The search endpoint performs a LIKE search across name, name_ar, code, sku, and barcode.