# Admin Agent Activity Logs API This endpoint provides a comprehensive timeline view of all agent activities including location tracking, receipts, and expenses. ## Endpoint ``` GET /admin/agents/:id/logs GET /admin/agent-activity-logs?agent_id=:id ``` ## Authentication Requires admin authentication via JWT token or `auth_token` in the Authorization header. ## Request Parameters ### Path Parameters - `id` (required): Agent ID ### Query Parameters (Optional) - `agent_id` (optional): Agent ID (alternative to path parameter) - `start_date` (optional): Start date filter (YYYY-MM-DD format) - `end_date` (optional): End date filter (YYYY-MM-DD format) - `start_time` (optional): Start time filter (HH:MM:SS format) - `end_time` (optional): End time filter (HH:MM:SS format) - `activity_type` (optional): Filter by activity type (`collection`, `travel`, `check_in`, `check_out`, `expense`, `other`) - `limit` (optional): Maximum number of records per type (default: 1000) ## Response Format ### Success Response (200 OK) ```json { "status": "success", "message": "Agent activity logs retrieved successfully", "data": { "agent": { "id": 5, "name": "John Doe", "mobile_no": "9876543210", "line": "Line 1", "status": "active", "address": "123 Main St" }, "filters": { "start_date": "2025-01-01", "end_date": "2025-01-31", "start_time": null, "end_time": null, "activity_type": null, "limit": null }, "summary": { "total_activities": 150, "total_locations": 80, "total_receipts": 45, "total_expenses": 25, "total_collected": 125000.50, "total_expense_amount": 5000.00, "net_collection": 120000.50, "activity_type_counts": { "collection": 45, "travel": 20, "check_in": 5, "check_out": 5, "expense": 25, "other": 50 } }, "timeline": [ { "type": "location", "id": 123, "timestamp": "2025-01-15T10:30:00.000Z", "activity_type": "collection", "data": { "latitude": 11.3410, "longitude": 77.7172, "accuracy": 10.5, "address": "Erode, Tamil Nadu, India", "receipt_id": 56, "loan_id": "DL2025001", "remark": "Collection at customer location" } }, { "type": "receipt", "id": 56, "timestamp": "2025-01-15T10:25:00.000Z", "activity_type": "collection", "data": { "rec_no": "REC001", "rec_date": "2025-01-15", "loan_id": "DL2025001", "cust_id": 123, "cust_name": "Customer Name", "cust_mobile": "9876543210", "paid_amnt": 5000.00, "paid_dues": 0, "remark": "Payment received" } }, { "type": "expense", "id": 25, "timestamp": "2025-01-15T09:00:00.000Z", "activity_type": "expense", "data": { "voucher_id": "VOUCH001", "expense_date": "2025-01-15", "reason": "Fuel", "amount": 500.00, "photo_url": "http://192.168.1.3:3000/uploads/expenses/expense-1234567890.jpg", "notes": "Fuel for collection route" } } ], "by_date": { "2025-01-15": [ { "type": "location", "id": 123, "timestamp": "2025-01-15T10:30:00.000Z", "activity_type": "collection", "data": { ... } } ], "2025-01-14": [ ... ] }, "timestamp": "2025-01-15T12:00:00.000Z" } } ``` ### Error Responses #### 400 Bad Request - Missing Agent ID ```json { "status": "error", "message": "Agent ID is required" } ``` #### 401 Unauthorized - Admin Authentication Required ```json { "status": "error", "message": "Admin authentication required" } ``` #### 404 Not Found - Agent Not Found ```json { "status": "error", "message": "Agent not found" } ``` #### 500 Internal Server Error ```json { "status": "error", "message": "Failed to fetch agent activity logs", "error": "Error details" } ``` ## Activity Types - **location**: Location tracking entries - **receipt**: Receipt/collection entries - **expense**: Expense/voucher entries ## Activity Type Values - `collection`: Related to receipt collection - `travel`: Agent traveling - `check_in`: Agent checking in - `check_out`: Agent checking out - `expense`: Expense entry - `other`: General tracking ## cURL Examples ### Get All Activity Logs for Agent ```bash curl -X GET "http://192.168.1.3:3000/admin/agents/5/logs" \ -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \ -H "Accept: application/json" ``` ### Get Activity Logs with Date Range ```bash curl -X GET "http://192.168.1.3:3000/admin/agents/5/logs?start_date=2025-01-01&end_date=2025-01-31" \ -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \ -H "Accept: application/json" ``` ### Get Activity Logs with Date and Time Range ```bash curl -X GET "http://192.168.1.3:3000/admin/agents/5/logs?start_date=2025-01-15&end_date=2025-01-15&start_time=09:00:00&end_time=18:00:00" \ -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \ -H "Accept: application/json" ``` ### Get Activity Logs Filtered by Activity Type ```bash curl -X GET "http://192.168.1.3:3000/admin/agents/5/logs?activity_type=collection" \ -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \ -H "Accept: application/json" ``` ### Get Activity Logs Using Query Parameter ```bash curl -X GET "http://192.168.1.3:3000/admin/agent-activity-logs?agent_id=5&start_date=2025-01-01&end_date=2025-01-31" \ -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \ -H "Accept: application/json" ``` ### Get Activity Logs with Limit ```bash curl -X GET "http://192.168.1.3:3000/admin/agents/{id}/logs?start_date=2025-01-01&end_date=2025-01-31&limit=100" \ -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \ -H "Accept: application/json" ``` ## PowerShell Examples ### Get All Activity Logs for Agent ```powershell $session = New-Object Microsoft.PowerShell.Commands.WebRequestSession $session.UserAgent = "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1" Invoke-WebRequest -UseBasicParsing ` -Uri "http://192.168.1.3:3000/admin/agents/5/logs" ` -WebSession $session ` -Headers @{ "Accept"="application/json" "Authorization"="Bearer YOUR_ADMIN_JWT_TOKEN" } ` -ContentType "application/json" ``` ### Get Activity Logs with Date Range ```powershell $session = New-Object Microsoft.PowerShell.Commands.WebRequestSession $session.UserAgent = "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1" Invoke-WebRequest -UseBasicParsing ` -Uri "http://192.168.1.3:3000/admin/agents/5/logs?start_date=2025-01-01&end_date=2025-01-31" ` -WebSession $session ` -Headers @{ "Accept"="application/json" "Authorization"="Bearer YOUR_ADMIN_JWT_TOKEN" } ` -ContentType "application/json" ``` ## Features 1. **Comprehensive Timeline**: Combines location logs, receipts, and expenses into a single chronological timeline 2. **Date/Time Filtering**: Filter activities by date range and time range 3. **Activity Type Filtering**: Filter by specific activity types 4. **Grouped by Date**: Activities are also grouped by date for easier navigation 5. **Summary Statistics**: Provides totals for collections, expenses, and net collection 6. **Activity Type Counts**: Shows count of each activity type 7. **Flexible Routing**: Supports both path parameter and query parameter formats ## Use Cases - **Agent Performance Review**: View all agent activities in a timeline - **Daily Activity Report**: Get all activities for a specific day - **Collection Analysis**: Analyze collection patterns and locations - **Expense Tracking**: Track agent expenses alongside collections - **Route Analysis**: View location logs to understand agent movement patterns - **Audit Trail**: Complete audit trail of all agent activities ## Notes - Activities are sorted by timestamp (most recent first) - Default limit is 1000 records per type if not specified - Date filters apply to `created_at` for locations, `rec_date` for receipts, and `date` for expenses - Time filters only work when combined with date filters - The endpoint verifies that the agent belongs to the admin's company