# Admin API: Get Collection Details for a Specific Agent

## Endpoint
`GET /admin/agents/:agent_id/collection-details` or `GET /admin/agent-collection-details?agent_id=5`

## Description
Returns collection details for a specific agent including:
- Agent information
- Collection summary (totals, pending amounts, collection rates)
- Customer details with loan and receipt information (optional)

This endpoint is similar to the agent's own `/collection_details` endpoint but accessible by admins for any agent in their company.

## Authentication
Requires admin authentication via Bearer token (JWT or auth_token).

## Query Parameters
- `agent_id` (required if using `/admin/agent-collection-details`): Agent ID
- `date` (optional): Target date for collection details (YYYY-MM-DD). Defaults to today
- `area` (optional): Filter by specific area(s). Comma-separated for multiple areas (e.g., "Area1,Area2")
- `include_customers` (optional): Include full customer details. Set to `true` or `1` to include

## cURL Examples

### 1. Get Collection Details for Agent ID 5 (Summary Only)
```bash
curl -X GET "http://192.168.1.3:3000/admin/agents/5/collection-details" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"
```

### 2. Get Collection Details with Customer Details
```bash
curl -X GET "http://192.168.1.3:3000/admin/agents/5/collection-details?include_customers=true" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"
```

### 3. Get Collection Details for Specific Date
```bash
curl -X GET "http://192.168.1.3:3000/admin/agents/5/collection-details?date=2025-12-06&include_customers=true" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"
```

### 4. Get Collection Details with Area Filter
```bash
curl -X GET "http://192.168.1.3:3000/admin/agents/5/collection-details?area=Area1,Area2&include_customers=true" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"
```

### 5. Using Query Parameter Route
```bash
curl -X GET "http://192.168.1.3:3000/admin/agent-collection-details?agent_id=5&date=2025-12-06&include_customers=true" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"
```

### 6. PowerShell Example
```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/collection-details?include_customers=true" `
-WebSession $session `
-Headers @{
  "Accept"="application/json"
  "Authorization"="Bearer YOUR_ADMIN_JWT_TOKEN"
}
```

## Response Format

### Success Response (200 OK) - Summary Only
```json
{
  "status": "success",
  "message": "Collection details retrieved for agent",
  "data": {
    "agent_info": {
      "agent_id": 5,
      "agent_name": "Raja",
      "agent_mobile": "8825948300",
      "line": "Line 2",
      "company_id": 15
    },
    "summary": {
      "total_customers": 25,
      "total_collection_amount": 2300.00,
      "total_amount_till_today": 2500.00,
      "total_needed_calculated_today": 2500.00,
      "total_collected_amount": 2300.00,
      "collected_today_amount": 500.00,
      "total_pending_amount": 200.00,
      "remaining_pending_amount": 200.00,
      "total_previous_unpaid": 150.00,
      "total_future_paid": 0.00,
      "total_partial_future_paid": 0.00,
      "collection_status": {
        "fully_paid": 20,
        "partially_paid": 3,
        "unpaid": 2
      },
      "payment_types": {
        "previous_unpaid": 2,
        "future_paid": 0,
        "partial_future_paid": 3,
        "full_paid": 20,
        "none": 0
      },
      "collection_rate": 80.00,
      "today_collection_rate": 21.74,
      "current_date": "2025-12-06",
      "areas": ["Area1", "Area2"]
    }
  }
}
```

### Success Response (200 OK) - With Customer Details
```json
{
  "status": "success",
  "message": "Collection details retrieved for agent",
  "data": {
    "agent_info": {
      "agent_id": 5,
      "agent_name": "Raja",
      "agent_mobile": "8825948300",
      "line": "Line 2",
      "company_id": 15
    },
    "summary": {
      "total_customers": 25,
      "total_collection_amount": 2300.00,
      "total_amount_till_today": 2500.00,
      "total_needed_calculated_today": 2500.00,
      "total_collected_amount": 2300.00,
      "collected_today_amount": 500.00,
      "total_pending_amount": 200.00,
      "remaining_pending_amount": 200.00,
      "total_previous_unpaid": 150.00,
      "total_future_paid": 0.00,
      "total_partial_future_paid": 0.00,
      "collection_status": {
        "fully_paid": 20,
        "partially_paid": 3,
        "unpaid": 2
      },
      "payment_types": {
        "previous_unpaid": 2,
        "future_paid": 0,
        "partial_future_paid": 3,
        "full_paid": 20,
        "none": 0
      },
      "collection_rate": 80.00,
      "today_collection_rate": 21.74,
      "current_date": "2025-12-06",
      "areas": ["Area1", "Area2"]
    },
    "customers": [
      {
        "loan_id": "DL2025001",
        "cust_id": 8,
        "cust_name": "Pavithra",
        "cust_mobile": "5346876764",
        "cust_address": "123 Main St",
        "area": "Area1",
        "loan_type": "Weekly",
        "loan_amt": 10000.00,
        "per_due_amt": 500.00,
        "dues": 20,
        "next_due_date": "2025-12-13",
        "last_due_date": "2025-12-06",
        "expected_collection": 500.00,
        "collected_today": 500.00,
        "pending": 0.00,
        "overdue_amount": 0.00,
        "payment_status": "fully_paid",
        "last_receipt": {
          "rec_no": "REC1764939408896",
          "rec_date": "2025-12-06",
          "paid_amnt": 500.00,
          "paid_dues": 1,
          "next_date": "2025-12-13"
        }
      },
      {
        "loan_id": "DL2025002",
        "cust_id": 9,
        "cust_name": "Kumar",
        "cust_mobile": "9876543210",
        "cust_address": "456 Oak Ave",
        "area": "Area2",
        "loan_type": "Daily",
        "loan_amt": 5000.00,
        "per_due_amt": 200.00,
        "dues": 25,
        "next_due_date": "2025-12-07",
        "last_due_date": "2025-12-06",
        "expected_collection": 200.00,
        "collected_today": 100.00,
        "pending": 100.00,
        "overdue_amount": 0.00,
        "payment_status": "partially_paid",
        "last_receipt": {
          "rec_no": "REC1764939408897",
          "rec_date": "2025-12-06",
          "paid_amnt": 100.00,
          "paid_dues": 0.5,
          "next_date": "2025-12-07"
        }
      }
    ]
  }
}
```

### Success Response (200 OK) - No Areas Found
```json
{
  "status": "success",
  "message": "No areas found for this agent",
  "data": {
    "agent_info": {
      "agent_id": 5,
      "agent_name": "Raja",
      "agent_mobile": "8825948300",
      "line": "Line 2",
      "company_id": 15
    },
    "customers": [],
    "summary": {
      "total_customers": 0,
      "total_collection_amount": 0,
      "total_amount_till_today": 0,
      "total_needed_calculated_today": 0,
      "total_collected_amount": 0,
      "collected_today_amount": 0,
      "total_pending_amount": 0,
      "remaining_pending_amount": 0,
      "total_previous_unpaid": 0,
      "total_future_paid": 0,
      "total_partial_future_paid": 0,
      "collection_status": {
        "fully_paid": 0,
        "partially_paid": 0,
        "unpaid": 0
      },
      "payment_types": {
        "previous_unpaid": 0,
        "future_paid": 0,
        "partial_future_paid": 0,
        "full_paid": 0,
        "none": 0
      },
      "collection_rate": 0,
      "today_collection_rate": 0,
      "current_date": "2025-12-06",
      "areas": []
    }
  }
}
```

### Error Response (400 Bad Request)
```json
{
  "status": "error",
  "message": "Agent ID is required"
}
```

### Error Response (400 Bad Request - Invalid Agent ID)
```json
{
  "status": "error",
  "message": "Invalid agent ID"
}
```

### Error Response (404 Not Found)
```json
{
  "status": "error",
  "message": "Agent not found or does not belong to your company"
}
```

### Error Response (401 Unauthorized)
```json
{
  "status": "error",
  "message": "Admin authentication required"
}
```

### Error Response (500 Internal Server Error)
```json
{
  "status": "error",
  "message": "Failed to fetch collection details for agent",
  "error": "Error message details"
}
```

## Notes

1. **Authentication**: Replace `YOUR_ADMIN_JWT_TOKEN` with a valid admin JWT token obtained from `/admin/login` or `/?admin_login=true`.

2. **Date Format**: Use `YYYY-MM-DD` format for dates (e.g., `2025-12-06`). Defaults to today if not provided.

3. **Area Filtering**: 
   - If `area` parameter is provided, only returns collection details for those specific areas
   - If not provided, uses all areas from the agent's assigned line
   - Multiple areas can be specified as comma-separated values

4. **Customer Details**: 
   - By default, only summary statistics are returned
   - Set `include_customers=true` to get full customer list with loan and receipt details
   - Customer details include loan information, payment status, and last receipt information

5. **Summary Statistics**:
   - `total_customers`: Total number of customers with loans in the agent's areas
   - `total_collection_amount`: Total amount expected to be collected
   - `total_collected_amount`: Total amount collected (all time)
   - `collected_today_amount`: Amount collected today
   - `total_pending_amount`: Total pending amount
   - `collection_rate`: Percentage of customers fully paid
   - `today_collection_rate`: Percentage of today's collection target achieved

6. **Payment Status**: 
   - `fully_paid`: Customer has paid all dues up to today
   - `partially_paid`: Customer has paid some but not all dues
   - `unpaid`: Customer has not paid any dues

7. **Company Filtering**: The endpoint automatically filters by the admin's company_id, ensuring admins can only access agents from their own company.

## Example with Real Server URL

```bash
curl -X GET "http://192.168.1.3:3000/admin/agents/5/collection-details?include_customers=true&date=2025-12-06" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```