Proximity Vendor 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 |

3. Vendor Endpoints

3.1 Get Vendor by ID

GET /vendor/:vendorId

| Parameter | Type | Required | Description | | ---------- | ------ | -------- | ----------------- | | vendorId | String | Yes | Vendor identifier |

Response: Vendor object including vendor_info and inventory.

Error Codes:

| Status | Message | | ------ | --------------------- | | 404 | Vendor not found | | 500 | Internal server error |

3.2 Get Vendor by Phone Number

GET /vendor?phoneNumber=<phoneNumber>

| Query Parameter | Type | Required | Description | | --------------- | ------ | -------- | --------------------- | | phoneNumber | String | Yes | Vendor contact number |

Response: Vendor object.

Error Codes:

| Status | Message | | ------ | --------------------------------------- | | 400 | phoneNumber query parameter is required | | 404 | Vendor not found | | 500 | Internal server error |

3.3 Create / Update / Delete Vendor

| Method | Endpoint | Request Body | Response | Notes | | ------ | ------------------- | ------------------------------------------------------------------------------- | ------------------- | ------------------------------- | | POST | /vendor | { vendor_id, name, address, contact, gps_location, opening_hours, inventory } | 201, vendor created | Create new vendor | | PUT | /vendor/:vendorId | { field: value, ... } | 200, updated vendor | Partial update supported | | DELETE | /vendor/:vendorId | None | 200, deleted vendor | Remove vendor and all inventory |

4. Error Response Format

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

Example:

{
  "error": "Vendor not found"
}

5. Notes / Guidelines

1. Proximity detection: GET /vendors 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.