# Helper Endpoint Contracts

This spec covers helper, lookup, search, and stats endpoints that support forms and dashboards. The main business save/delete/status endpoints are covered in the WMS, Accounting, Master Data, System Settings, and Document Lifecycle specs.

## Common Contract

Unless a route explicitly differs, helper endpoints:

- Load authenticated context through `db_auth.php`.
- Scope reads by the active `company_id`.
- Return JSON.
- Are consumed by AJAX from PHP pages.
- Should not mutate business documents unless their name says `manage`, `remove`, `delete`, `approve`, `confirm`, `cancel`, `void`, `issue`, `post`, `receive`, or `update`.

## ICS Search And Lookup

| Endpoint | Purpose | Main consumers |
|---|---|---|
| `app/ics/api/engine/contact_search.php` | Search contacts for stock/document forms. | Stock in/out/transfer and document source forms. |
| `app/ics/api/engine/product_search.php` | Search active products/SKUs for stock forms. | Stock in/out/transfer forms. |
| `app/ics/api/engine/barcode_lookup.php` | Resolve scanned barcode into product, lot/serial, or location context. | Scanner workflows and barcode-enabled forms. |
| `app/ics/api/engine/validate_scan_location.php` | Validate scanned warehouse/zone/aisle/rack context. | Scanner workflows. |
| `app/ics/api/engine/retrieve_stock_by_source.php` | Return stock rows linked to a source document. | WMS document detail and approval/deletion context. |

## ICS Location Helpers

| Endpoint | Purpose |
|---|---|
| `app/ics/api/engine/retrieve_warehouse.php` | Return active warehouses available to the company. |
| `app/ics/api/engine/retrieve_zone.php` | Return zones for a warehouse. |
| `app/ics/api/engine/retrieve_aisle.php` | Return aisles for a warehouse/zone. |
| `app/ics/api/engine/retrieve_rack.php` | Return racks for a warehouse/zone/aisle. |

These endpoints are driven by warehouse/storage setup and company location mode. They are used to populate dependent dropdowns and validate manual location selection.

## ICS Lot And Serial Helpers

| Endpoint | Purpose |
|---|---|
| `app/ics/api/engine/retrieve_lot.php` | Return known lots for a product/SKU. |
| `app/ics/api/engine/retrieve_active_lot.php` | Return lots with active stock availability. |
| `app/ics/api/engine/retrieve_active_serial.php` | Return serial numbers with active stock availability. |
| `app/ics/api/engine/sku_label_lots.php` | Return lots available for SKU label generation. |
| `app/ics/api/engine/sku_label_products.php` | Return products available for SKU label generation. |

## Stats Endpoints

| Endpoint | Purpose |
|---|---|
| `app/accounting/api/engine/account_stats.php` | Chart of accounts summary cards/statistics. |
| `app/accounting/api/engine/department_stats.php` | Department summary cards/statistics. |
| `app/contact/api/engine/contact_stats.php` | Contact summary cards/statistics. |
| `app/inventory/api/engine/product_stats.php` | Product summary cards/statistics. |
| `app/inventory/api/engine/warehouse_stats.php` | Warehouse summary cards/statistics. |
| `app/ics/api/engine_report/product_stats.php` | Stock/product operational statistics. |
| `app/ics/api/engine_report/warehouse_stats.php` | Stock overview warehouse statistics. |
| `app/dashboard/api/engine_report/reports_stats.php` | WMS dashboard cards and charts; gated by transaction limits. |

Stats endpoints are read-only dashboard/list-page support routes. They should follow the same quota behavior as their parent dashboard/report area where `UsageGuard` is applied.

## Retrieve Endpoints

Retrieve endpoints return one record or a bounded list needed by an edit form.

| Module | Endpoints |
|---|---|
| Contact | `retrieve_contact.php`, `retrieve_contact_type.php` |
| Inventory | `retrieve_category.php`, `retrieve_product.php`, `retrieve_storage.php`, `retrieve_warehouse.php` |
| Stock | `retrieve_stock_in.php`, `retrieve_stock_out.php`, `retrieve_stock_transfer.php` |
| Order | `retrieve_order.php`, `retrieve_invoice.php`, `retrieve_return.php` |
| PO | `retrieve_po.php`, `retrieve_supplier_return.php` |
| Revenue | `retrieve_quotation.php` |
| Expense | `retrieve_purchase_request.php` |
| Accounting | `retrieve_account.php`, `retrieve_department.php`, `get_journal_detail.php` |
| Settings | `retrieve_company.php`, `retrieve_profile.php`, `retrieve_smtp.php`, `retrieve_users.php` |

Expected behavior:

- Validate active company scope.
- Return only active positive-company rows unless the feature explicitly needs historical/deleted records.
- Avoid exposing rows from another company even when an ID is guessed.

## Generic Inventory Manager Endpoint

Endpoint: `app/inventory/api/engine/manager.php`

This route is an inventory utility endpoint guarded to owner/admin roles. It belongs with product/category/warehouse/storage maintenance and should not be used for unauthenticated or cross-module access.

## Endpoint Documentation Rule

When adding a new helper endpoint, update this file if the endpoint is not already clearly covered by a feature spec. Include:

- Endpoint path.
- Read/write behavior.
- Main consumer page.
- Important company/role/limit guards.
- Payload shape when frontend code depends on exact fields.