Inventory Backend API Documentation

Base URL: /api (example) Auth: Currently relies on device headers (x-device-sig, x-ws-token) and IP-based identification for proximity features.

Models:

• Vendor: Contains vendor_info and inventory arrays.
• DeviceScan: Records devices’ last scan (SSID info, timestamp, etc.).

1. Common Headers

| Header | Description | Required | | -------------- | -------------------------- | -------------------------------------- | | x-device-sig | Unique device signature | Optional (used in proximity detection) | | x-ws-token | Session or workspace token | Optional | | public_ip | Client IP address | Optional |

2. Inventory Endpoints

2.1 Get Inventory by Item ID

GET /inventory/:itemId

| Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------ | | itemId | String | Yes | Unique inventory item ID |

Response:

| Field | Type | Description | | -------- | ------ | ------------------------------------------- | | vendor | Object | Vendor info containing vendor_info fields | | item | Object | Inventory item matching itemId |

Error Codes:

| Status | Message | | ------ | ------------------------ | | 404 | Inventory item not found | | 500 | Internal server error |

2.2 Get Inventory by Proximity

GET /inventory

Headers used: x-device-sig, public_ip, x-ws-token

Response:

• List of vendors matching the last device scan SSIDs

| Field | Type | Description | | ------------- | ------ | ----------------------- | | vendor_id | String | Vendor identifier | | vendor_name | String | Name of vendor | | address | String | Vendor address | | inventory | Array | List of inventory items |

Error Codes:

| Status | Message | | ------ | ------------------------------------------ | | 404 | No recent proximity data found for this IP | | 500 | Internal server error |

2.3 Search Inventory

GET /search?query=<query>

| Query Parameter | Type | Required | Description | | --------------- | ------ | -------- | -------------------------------------------------------------- | | query | String | Yes | Fuzzy search term for inventory, vendor name, address, or tags |

Response:

| Field | Type | Description | | --------- | ------ | ------------------------------ | | query | String | Search term | | results | Array | List of vendors matching query |

Error Codes:

| Status | Message | | ------ | --------------------------- | | 400 | Query parameter is required | | 500 | Internal server error |

2.4 Create / Update / Delete Inventory

| Method | Endpoint | Request Body | Response | Notes | | ------ | ---------------------------------- | ----------------------------------------- | ----------------------------- | ---------------------------- | | POST | /vendor/:vendorId/inventory | { item_id, name, category, price, ... } | 200, added item | Add single inventory item | | POST | /vendor/:vendorId/inventory/bulk | { items: [{ item_id, name, ...}, ...] } | 200, items added | Add multiple inventory items | | PUT | /inventory/:itemId | { field: value, ... } | 200, updated item | Update fields of single item | | PUT | /inventory/:vendorId/bulk | [ { item_id, field: value }, ... ] | 200, summary of updated items | Bulk update inventory items | | DELETE | /inventory/:itemId | None | 200, deleted item | Delete single item | | DELETE | /inventory | { itemIds: [id1, id2, ...] } | 200, deletedCount | Bulk delete items |

3. Error Response Format

| Field | Type | Description | | --------- | ------ | ------------------------------------------------ | | error | String | Error message | | message | String | Optional descriptive message for success/failure |

Example:

{
  "error": "Vendor not found"
}

4. Notes / Guidelines

1. Proximity detection: GET /inventory uses device signature, token, or IP as a fallback to retrieve recent Wi-Fi scans.
2. Bulk operations: Partial success is possible; the response includes per-item update status.
3. Consistency: All update operations return the new state of the object after modification.
4. Pagination: Not implemented yet for search; consider adding limit and offset query params for large datasets.
5. Logging: Server logs device signatures and SSIDs for audit/debugging.