POS Receipts (إيصالات نقاط البيع)

The Receipts endpoint provides barcode-based lookup for POS invoices. This is used for receipt reprints, customer returns, and order verification at the counter.

How It Works

Every POS sale generates two identifiers on the sales_invoices record:

Field	Description	Example
receipt_number	Sequential receipt number per branch	POS-2026-02-00015
receipt_barcode	Scannable barcode string (no dashes)	POSPOS20260200015

The lookup endpoint searches both fields, so scanning either format will find the receipt.

API Endpoint

Method	Endpoint	Description	Permission
GET	/api/pos/receipts/barcode/{barcode}	Look up receipt by barcode or receipt number	pos.receipt-sequence.view

Request / Response Examples

Look Up Receipt

curl

curl -G /api/pos/receipts/barcode/POSPOS20260200015 \
  -H "Authorization: Bearer {token}"

Dart

final response = await dio.get('/api/pos/receipts/barcode/POSPOS20260200015');

Response 200 OK

{
  "id": 42,
  "invoice_number": "INV-000042",
  "receipt_number": "POS-2026-02-00015",
  "receipt_barcode": "POSPOS20260200015",
  "date": "2026-02-28",
  "customer_name": "Walk-in Customer",
  "status": "posted",
  "subtotal": "39.000",
  "discount_amount": "0.000",
  "tax_amount": "1.550",
  "total": "40.550",
  "cashier": "Ahmed",
  "items": [
    {
      "product_id": 10,
      "product_name": "Wireless Mouse",
      "quantity": "2.000",
      "unit_price": "15.500",
      "line_total": "31.000"
    },
    {
      "product_id": 22,
      "product_name": "USB Cable",
      "quantity": "1.000",
      "unit_price": "8.000",
      "line_total": "8.000"
    }
  ]
}

Response 404 Not Found

{
  "message": "Receipt not found."
}

Business Rules

1. POS invoices only -- The lookup only searches invoices where is_pos = true.
2. Dual search -- The {barcode} parameter is matched against both receipt_barcode and receipt_number, so either format works.
3. Company scoping -- Only receipts belonging to the authenticated user's company are returned.
4. Flat response -- The response is a flat JSON object (not wrapped in a resource), including the cashier name and simplified items array for receipt rendering.