# POS & Inventory System API Connection Documentation

This document describes how to connect and interact with the RESTful API endpoints of this system. You can use these endpoints to build a companion mobile application for product inquiries, stock lookups, daily sales summaries, and POS billing.

## Base URL
All API requests must be prefixed with:
`http://<server-ip-or-domain>/api`

---

## Authentication & Headers

Except for the `/login` endpoint, all requests require the following HTTP headers:
```http
Accept: application/json
Content-Type: application/json
Authorization: Bearer <your_access_token>
```

---

## Endpoints

### 1. User Authentication

#### **Login**
Authenticates a user and issues a Bearer token.
* **URL:** `/login`
* **Method:** `POST`
* **Headers:** `Accept: application/json`
* **Request Body:**
  ```json
  {
    "email": "cashier@example.com",
    "password": "password",
    "device_name": "iPhone 15 Pro"
  }
  ```
* **Success Response (200 OK):**
  ```json
  {
    "success": true,
    "token": "1|abCDeFGhiJ...",
    "user": {
      "id": 2,
      "name": "John Doe",
      "email": "cashier@example.com",
      "role": "cashier",
      "branch_id": 1,
      "branch_name": "Main Branch"
    }
  }
  ```

---

### 2. Product Search & Barcode Scanning

#### **Search Products**
Finds active products by name (English or Sinhala), SKU, or barcode.
* **URL:** `/products/search`
* **Method:** `GET`
* **Query Parameters:**
  * `q` (string, optional): Search keyword.
  * `category_id` (integer, optional): Filter by category.
* **Success Response (200 OK):**
  ```json
  {
    "success": true,
    "products": [
      {
        "id": 15,
        "barcode": "8801234567890",
        "sku": "PROD-102",
        "name_en": "Samsung Galaxy S24 Ultra",
        "name_si": "සැම්සුන්ග් ගැලැක්සි S24",
        "selling_price": "395000.00",
        "wholesale_price": "380000.00",
        "cost_price": "350000.00",
        "warranty_period": "1 Year",
        "condition": "new",
        "tax_rate": "18.00",
        "is_taxable": true,
        "unit": "pcs",
        "stock": 14,
        "image": null
      }
    ]
  }
  ```

#### **Find Product by Barcode**
Instantly retrieves details of a single product using a barcode scan.
* **URL:** `/products/barcode/{barcode}`
* **Method:** `GET`
* **URL Parameter:** `{barcode}` (e.g. `/products/barcode/8801234567890`)
* **Success Response (200 OK):**
  ```json
  {
    "success": true,
    "product": {
      "id": 15,
      "barcode": "8801234567890",
      "sku": "PROD-102",
      "name_en": "Samsung Galaxy S24 Ultra",
      "name_si": "සැම්සුන්ග් ගැලැක්සි S24",
      "selling_price": "395000.00",
      "wholesale_price": "380000.00",
      "cost_price": "350000.00",
      "warranty_period": "1 Year",
      "condition": "new",
      "tax_rate": "18.00",
      "is_taxable": true,
      "unit": "pcs",
      "stock": 14,
      "image": null
    }
  }
  ```

---

### 3. Stock Inquiry

#### **List Stock**
Displays active products with their current stock levels and minimum stock thresholds for the cashier's authenticated branch.
* **URL:** `/stock`
* **Method:** `GET`
* **Query Parameters:**
  * `q` (string, optional): Filter by name or barcode.
  * `page` (integer, optional): Page number (for pagination).
  * `per_page` (integer, optional): Number of results per page (default: 15).
* **Success Response (200 OK):**
  ```json
  {
    "success": true,
    "current_page": 1,
    "last_page": 3,
    "total": 42,
    "data": [
      {
        "product_id": 15,
        "barcode": "8801234567890",
        "name": "Samsung Galaxy S24 Ultra",
        "sku": "PROD-102",
        "stock": 14,
        "min_stock": 5,
        "status": "in_stock"
      },
      {
        "product_id": 18,
        "barcode": "9901456247921",
        "name": "Tempered Glass S24",
        "sku": "ACC-54",
        "stock": 2,
        "min_stock": 10,
        "status": "low_stock"
      }
    ]
  }
  ```

---

### 4. POS Billing (Checkout)

#### **Create Invoice**
Submits a cart to check out and register a new POS bill.
* **URL:** `/pos/invoice`
* **Method:** `POST`
* **Request Body:**
  ```json
  {
    "customer_name": "Ravi Dilshan",
    "customer_phone": "0771234567",
    "customer_company": "Nippon Tech",
    "customer_address": "Colombo, Sri Lanka",
    "bill_discount": 500,
    "bill_discount_type": "amount",
    "notes": "Delivered with charger",
    "items": [
      {
        "product_id": 15,
        "product_name": "Samsung Galaxy S24 Ultra",
        "product_barcode": "8801234567890",
        "imei_numbers": "IMEI-882736452819382",
        "warranty_period": "1 Year",
        "condition": "new",
        "quantity": 1,
        "unit_price": 395000,
        "cost_price": 350000,
        "discount": 0,
        "discount_type": "amount",
        "tax_rate": 18,
        "is_taxable": true
      }
    ],
    "payments": [
      {
        "method": "cash",
        "amount": 400000,
        "reference": null
      }
    ]
  }
  ```
  *(Payment methods must be one of: `cash`, `card`, `qr`, `bank_transfer`, `credit`)*

* **Success Response (201 Created):**
  ```json
  {
    "success": true,
    "message": "Invoice created successfully",
    "invoice": {
      "id": 103,
      "invoice_number": "INV-00103",
      "customer_name": "Ravi Dilshan",
      "customer_phone": "0771234567",
      "total": "394500.00",
      "created_at": "2026-07-20T00:39:00.000000Z",
      "items": [...],
      "payments": [...]
    }
  }
  ```

---

### 5. Sales Reports

#### **Daily Report**
Retrieves sales figures, payment breakdowns, and invoices for a specific date.
* **URL:** `/reports/daily`
* **Method:** `GET`
* **Query Parameters:**
  * `date` (string, optional): Format `YYYY-MM-DD` (default: today).
* **Success Response (200 OK):**
  ```json
  {
    "success": true,
    "date": "2026-07-20",
    "summary": {
      "total_sales": 394500.00,
      "total_invoices": 1,
      "total_refunds": 0.00,
      "cash_sales": 394500.00,
      "card_sales": 0.00,
      "qr_sales": 0.00,
      "bank_sales": 0.00,
      "courier_sales": 0.00
    },
    "invoices": [
      {
        "id": 103,
        "invoice_number": "INV-00103",
        "customer_name": "Ravi Dilshan",
        "total": "394500.00",
        "created_at": "2026-07-20 00:39:00",
        "cashier": "Admin User"
      }
    ]
  }
  ```

#### **Monthly Report**
Retrieves monthly summaries and daily sale statistics.
* **URL:** `/reports/monthly`
* **Method:** `GET`
* **Query Parameters:**
  * `month` (string, optional): Format `YYYY-MM` (default: current month).
* **Success Response (200 OK):**
  ```json
  {
    "success": true,
    "month": "2026-07",
    "summary": {
      "total_sales": 1420500.00,
      "total_refunds": 15000.00,
      "total_invoices": 12,
      "avg_daily": 142050.00
    },
    "daily_breakdown": [
      {
        "date": "2026-07-15",
        "invoices": 4,
        "total": "620000.00"
      },
      {
        "date": "2026-07-20",
        "invoices": 1,
        "total": "395000.00"
      }
    ]
  }
  ```

---

### 6. Cash Register Management

#### **Check Register Status**
Checks if the cashier has an active cash register open and gets stats.
* **URL:** `/register/status`
* **Method:** `GET`
* **Success Response (200 OK):**
  ```json
  {
    "success": true,
    "is_open": true,
    "register_id": 4,
    "opened_at": "2026-07-20 00:00:00",
    "opening_amount": 5000.00,
    "cash_sales": 18580.00,
    "expected_amount": 23580.00
  }
  ```

#### **Open Register**
Opens a cash register session for the logged-in cashier.
* **URL:** `/register/open`
* **Method:** `POST`
* **Request Body:**
  ```json
  {
    "opening_amount": 5000.00
  }
  ```
* **Success Response (201 Created):**
  ```json
  {
    "success": true,
    "message": "Cash register session opened successfully.",
    "register": {
      "id": 5,
      "user_id": 3,
      "branch_id": 1,
      "opening_amount": 5000,
      "opened_at": "2026-07-20T00:43:00.000000Z"
    }
  }
  ```

#### **Close Register**
Closes the active cash register session.
* **URL:** `/register/close`
* **Method:** `POST`
* **Request Body:**
  ```json
  {
    "closing_amount": 23580.00,
    "notes": "Closed drawer on time"
  }
  ```
* **Success Response (200 OK):**
  ```json
  {
    "success": true,
    "message": "Cash register session closed successfully.",
    "summary": {
      "opening_amount": 5000.00,
      "cash_sales": 18580.00,
      "expected_amount": 23580.00,
      "closing_amount": 23580.00,
      "discrepancy": 0.00
    }
  }
  ```

---

### 7. Customer Management

#### **Search Customers**
Finds registered customers by name, phone, or company name.
* **URL:** `/customers/search`
* **Method:** `GET`
* **Query Parameters:**
  * `q` (string, required): Phone, name, or company keyword.
* **Success Response (200 OK):**
  ```json
  {
    "success": true,
    "customers": [
      {
        "id": 3,
        "name": "Ravi Dilshan",
        "phone": "0771234567",
        "company": "Nippon Tech",
        "address": "Colombo, Sri Lanka",
        "created_at": "2026-07-20T00:10:00.000000Z"
      }
    ]
  }
  ```

#### **Register Customer**
Creates a new customer record.
* **URL:** `/customers`
* **Method:** `POST`
* **Request Body:**
  ```json
  {
    "name": "Amila Perera",
    "phone": "0719876543",
    "company": "Apex Lanka",
    "address": "Kandy, Sri Lanka"
  }
  ```
* **Success Response (201 Created):**
  ```json
  {
    "success": true,
    "message": "Customer registered successfully.",
    "customer": {
      "id": 4,
      "name": "Amila Perera",
      "phone": "0719876543",
      "company": "Apex Lanka",
      "address": "Kandy, Sri Lanka",
      "created_at": "2026-07-20T00:45:00.000000Z"
    }
  }
  ```

#### **Customer Invoice History**
Retrieves previous sales invoices for a specific customer.
* **URL:** `/customers/{customer_id}/invoices`
* **Method:** `GET`
* **Success Response (200 OK):**
  ```json
  {
    "success": true,
    "customer": {
      "id": 3,
      "name": "Ravi Dilshan",
      "phone": "0771234567"
    },
    "invoices": [
      {
        "id": 22,
        "invoice_number": "COL01-260720-0017",
        "total": "1450.00",
        "created_at": "2026-07-20T00:40:00.000000Z",
        "items": [...],
        "payments": [...]
      }
    ]
  }
  ```

---

### 8. Warranty & Repairs

#### **Verify Warranty Status**
Looks up warranty coverage by scanning an IMEI/Serial number, Invoice number, or phone.
* **URL:** `/warranty/search`
* **Method:** `GET`
* **Query Parameters:**
  * `q` (string, required): IMEI, Invoice ID/Number, name or phone.
* **Success Response (200 OK):**
  ```json
  {
    "success": true,
    "items": [
      {
        "id": 38,
        "invoice_id": 22,
        "invoice_number": "COL01-260720-0017",
        "customer_name": "Test Api Customer",
        "customer_phone": "0777777777",
        "product_name": "Anchor Milk Powder 400g",
        "product_id": 16,
        "imei_numbers": "IMEI-882736452819382",
        "warranty_period": "1 Year",
        "sold_date": "2026-07-20",
        "expiry_date": "2027-07-20",
        "warranty_status": "active"
      }
    ]
  }
  ```

#### **File Warranty Claim**
Submits a warranty ticket (repair or replacement).
* **URL:** `/warranty/claim`
* **Method:** `POST`
* **Request Body:**
  ```json
  {
    "invoice_id": 22,
    "product_id": 16,
    "customer_name": "Test Api Customer",
    "customer_phone": "0777777777",
    "product_name": "Anchor Milk Powder 400g",
    "imei_numbers": "IMEI-882736452819382",
    "issue_description": "Device does not power on",
    "status": "received",
    "is_replaced": false
  }
  ```
* **Success Response (200 OK):**
  ```json
  {
    "success": true,
    "message": "Warranty claim ticket created successfully.",
    "claim": {
      "id": 12,
      "invoice_id": 22,
      "customer_name": "Test Api Customer",
      "issue_description": "Device does not power on",
      "status": "received",
      "created_at": "2026-07-20T00:46:00.000000Z"
    }
  }
  ```