# COMPONENT — shop-pos-api & REST API layer

> **Code location:** `app/Http/Controllers/Api/` (excluding `Desktop/`) + the root `Shop*`
> controllers · routes in `routes/api.php` and `routes/web.php`.
> **Nav:** Master → [../CLAUDE.md](../../../CLAUDE.md) · Rules → [MASTER_RULES.md](../phase-3-shared/MASTER_RULES.md) ·
> POS/ledger contract → [MASTER_INTEGRATION.md §3](../phase-3-shared/MASTER_INTEGRATION.md#3-shop-pos-integration-shop-pos-api--shared-inventory--ledger)

> Component scope: the retail **Shop POS**, the shop dashboard, payments, and the general `v1` REST
> surface. Desktop sync is documented separately in
> [COMPONENT_DESKTOP_SYNC_API.md](COMPONENT_DESKTOP_SYNC_API.md).

## 1. Identity & purpose
Two overlapping surfaces:
- **Shop POS / retail** — `ShopApiController` (dashboard), `ShopProductController`, and the shop web
  controllers (`ShopController`, `ShopProductController`, `ShopTransactionController`,
  `ShopContactController` in root `Http/Controllers/`). Backed by the `Shop*` models.
- **General REST / v1** — `ApiController` (auth:sanctum sample surface), `PaymentController`
  (references, process-payment, process-receipt), plus `GrnController`, `QcController`,
  `ChartOfAccountController`, `CostCenterController` API variants.

## 2. Routing & auth (`routes/api.php` + `routes/web.php`)
Three distinct middleware regimes — **know which one your endpoint needs**:
| Prefix / group | Middleware | Use |
|----------------|-----------|-----|
| `api/v1/*` (public) | none | reserved; add public routes deliberately |
| `api/v1/*` (protected) | `auth:sanctum` | token-authenticated REST (`/user`, `/test`, future items) |
| `api/v1/*` (web) | `web` (session) | **Shop dashboard, factory POS, payments** — browser-driven, session auth |

Live web-session endpoints today:
- `GET  api/v1/shop/dashboard` → `ShopApiController@getDashboardData`
- `POST api/v1/factory-pos/store` → `FactoryPOSController@storeApi`
- `GET  api/v1/get-references`, `POST api/v1/process-payment`, `POST api/v1/process-receipt`
  → `Api\PaymentController`

There are also `api`-prefixed QC routes registered in `routes/web.php`
(`api/qc`, `api/igp/search`, `api/warehouse/{warehouse}/bins`).

> ⚠️ `Api/Backup/ShopApiController copy*.php` are **legacy, not routed**. The live shop API is
> `Api/ShopApiController.php`. Verify with `php artisan route:list` before editing.

## 3. Rules specific to this component
1. **Pick the right auth regime.** POS/dashboard/payments run on `web` (session + CSRF); pure
   machine-to-machine REST uses `auth:sanctum`. Don't mix them.
2. **JSON contracts.** Return consistent `{ success, data, message }`-style JSON with correct HTTP
   status codes; validate input via FormRequests, not inline.
3. **Shop stock ≠ central inventory.** POS writes `ShopProductStock`/`ShopStock`, not
   `WarehouseCurrentStock`/`StockBalance`. Post shop-ledger effects to
   `ShopContactAccountTransaction`. Keep them balanced and wrap in `DB::transaction()`.
4. **Payments** must post correctly to the accounting ledger — coordinate with the
   [accounting-ledger module](COMPONENT_ERP_WEB_CORE.md#accounting-ledger-module).
5. **Version additively.** Keep `v1` stable; new fields are additive. The desktop client also
   consumes shop data via `api/desktop/*` — see
   [MASTER_INTEGRATION.md §3](../phase-3-shared/MASTER_INTEGRATION.md#3-shop-pos-integration-shop-pos-api--shared-inventory--ledger).

## 4. Shop domain models
`Shop`, `ShopProduct`, `ShopProductPrice`, `ShopProductStock`, `ShopStock`, `ShopContact`,
`ShopInvoice(+Item)`, `ShopInvoiceReturn(+Item)`, `ShopGoodsReceipt(+Item)`, `ShopExpenseCategory`,
`ShopContactAccountTransaction`, `ShopTransactionAttachment`.

## 5. Testing
Feature-test each endpoint's auth regime, validation failures, and the stock/ledger side effects of
a sale, return, and receipt. Confirm shop stock and shop ledger reconcile after each.