📂 Fail MD
📄 api-spec.md
📄 architecture.md
📄 compound-rules.md
📄 council-sync.md
📄 data-model.md
📄 money-ledger.md
📄 parking-rules.md
Sedang mengedit: api-spec.md
# Smart Parking — API Spec (Draft) Draft REST API surface for the backend. Paths and payloads will be refined during implementation. All endpoints (except auth and public lookups) require authentication and are **tenant-scoped** by the caller's role/tenant. ## Conventions - Base path: `/api/v1` - Auth: bearer token (JWT). Token carries `role` and `tenant_id` (for staff/admin). - Tenant scoping enforced by middleware on every request. - Errors: standard JSON `{ "error": { "code", "message" } }`. - Money amounts in the smallest currency unit or 2-dp decimal (decide in impl; be consistent). ## Auth | Method | Path | Who | Purpose | |---|---|---|---| | POST | `/auth/register` | public user | Register (mandatory before paying) | | POST | `/auth/login` | user / staff / admin | Login, returns token (+ role, tenant_id) | | POST | `/auth/refresh` | all | Refresh token | | POST | `/auth/logout` | all | Invalidate token | ## Users & Vehicles | Method | Path | Notes | |---|---|---| | GET | `/me` | Current user/staff profile | | GET | `/vehicles` | List my vehicles | | POST | `/vehicles` | Add vehicle (enforce per-tenant limit at use time) | | DELETE | `/vehicles/{id}` | Remove link | | POST | `/vehicles/{id}/share` | Link another user (M:N, within limits) | ## Parking Sessions | Method | Path | Notes | |---|---|---| | GET | `/parking/quote` | Compute fee + end_at for `{plate, zone, hours, start}` (applies windows/rest/holiday/daily-max) | | POST | `/parking/sessions` | Start session `{vehicle_id, zone_id, hours, pay_method}` → tenant set by location | | GET | `/parking/sessions` | List my sessions (active/history) | | GET | `/parking/sessions/{id}` | Session detail | | POST | `/parking/sessions/{id}/extend` | Extend (respects windows/rest/daily-max) | ## Scanner / Enforcement (staff) | Method | Path | Notes | |---|---|---| | GET | `/scan/{plate}` | Check active paid session for `plate` + staff.tenant_id → PAID / NOT PAID. Reads Primary (avoid replication lag) | | POST | `/compounds` | Issue compound `{plate, type, evidence[], geo}` → tenant = staff's tenant | ## Compounds | Method | Path | Notes | |---|---|---| | GET | `/compounds` | List (tenant-scoped; user sees own) | | GET | `/compounds/{id}` | Detail | | POST | `/compounds/{id}/pay` | Pay `{pay_method}` (User App or Staff Parking walk-in) | | GET | `/compound-types` | Catalog of types | | GET | `/compound-rates` | Rates per tenant/type | ## Wallet & Payments | Method | Path | Notes | |---|---|---| | GET | `/wallet` | Balance (computed from ledger) — global | | POST | `/wallet/topup` | Top-up via gateway `{amount, method}` (respect min/max) | | POST | `/wallet/refund` | Refund **current balance only** to user | | GET | `/payments` | My payment history | | GET | `/payment-methods` | Available methods (FPX, card, e-wallet, saved cards) | ## Payment Webhook (gateway → backend) | Method | Path | Notes | |---|---|---| | POST | `/webhooks/payments/{provider}` | Razer / Chip Asia callbacks. Verify signature. Update ledger. Idempotent | ## IoT Ingestion (sensors → backend) | Method | Path | Notes | |---|---|---| | POST | `/ingest/uplink/{provider}` | LoRaWAN uplink (webhook). Decode → update bay status. Idempotent | | GET | `/bays` | Bay status (tenant-scoped) | | GET | `/zones/{id}/occupancy` | Aggregated occupancy (e.g. 20/26) | ## Maps / Discovery (User App) | Method | Path | Notes | |---|---|---| | GET | `/map/nearby` | Nearby zones + occupancy + geo `{lat,lng,radius}` | ## Admin / Finance (Company A + tenant views) | Method | Path | Who | Notes | |---|---|---|---| | GET | `/admin/dashboard` | role-based | Tenant view vs Company A view | | GET | `/admin/revenue` | tenant + A | Recognized revenue | | GET | `/admin/ledger` | tenant + A | Filtered ledger | | GET | `/admin/float` | Company A | Wallet float/liability | | GET | `/admin/reserve` | Company A | Rolling reserve | | GET | `/admin/commission` | Company A | Per-tenant commission | | GET | `/admin/settlements` | tenant + A | Settlement/payout records | | GET | `/admin/reconciliation` | Company A | Bank vs ledger check | | GET | `/admin/reports/monthly-statement` | tenant + A | Monthly statement | ## Settings / Config | Method | Path | Notes | |---|---|---| | GET/PUT | `/settings/global/*` | General, Branding, Backup, Maintenance | | GET/PUT | `/settings/integration/*` | API/Webhook, Weather, Maps, Telegram, Email, SMS, Recycle Bin, Public Holiday | | CRUD | `/roles`, `/users`, `/staff`, `/admins` | Role & user management | | CRUD | `/tenants` | Company A only | | PUT | `/tenants/{id}/commission` | Company A only | | CRUD | `/zones`, `/bays`, `/rates`, `/charging-windows` | Per tenant | | CRUD | `/devices`, `/gateways` | IoT devices | | GET | `/logs/activity`, `/logs/audit` | Logs | ## Notifications (internal) - User events → **SMS + Email** (session created, expiry reminder, compound issued, payment receipt). - System/technical events → **Telegram** (IT team). ## Cross-Cutting Rules - **Tenant scoping** middleware on every authenticated route. - **Idempotency** on webhooks and ingestion. - **Read-after-write** sensitive reads (scanner) target Primary. - **Immutable ledger** for all money movements. - **Audit log** for admin actions. ## Open Items - Final path/payload schemas. - Pagination, filtering, rate-limiting conventions. - Gateway-specific webhook formats (Razer / Chip Asia).
Simpan Perubahan