wms-app/docs/reviewing/helper-endpoints.md

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.