# Expense API - cURL Examples

## Insert Expense with Image Upload

### Using multipart/form-data (File Upload)

```bash
# Upload image file with expense data
curl -X POST "http://192.168.1.3:3000/insert_expense" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -F "expense_date=2025-01-15" \
  -F "amount=50.00" \
  -F "reason=Transportation cost for collection" \
  -F "photo=@/path/to/your/image.jpg"
```

### Using JSON (without file upload, or with photo_url)

```bash
# Without photo
curl -X POST "http://192.168.1.3:3000/insert_expense" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -d '{
    "expense_date": "2025-01-15",
    "amount": 50.00,
    "reason": "Transportation cost for collection"
  }'
```

```bash
# With photo_url (external URL)
curl -X POST "http://192.168.1.3:3000/insert_expense" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -d '{
    "expense_date": "2025-01-15",
    "amount": 50.00,
    "reason": "Transportation cost for collection",
    "photo_url": "https://example.com/expense-photo.jpg"
  }'
```

### Using auth_token as query parameter

```bash
curl -X POST "http://192.168.1.3:3000/insert_expense?auth_token=YOUR_AUTH_TOKEN" \
  -F "expense_date=2025-01-15" \
  -F "amount=50.00" \
  -F "reason=Transportation cost for collection" \
  -F "photo=@/path/to/your/image.jpg"
```

## Get Today's Expense List

```bash
# Using Bearer token
curl -X GET "http://192.168.1.3:3000/today_expense_list" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
```

```bash
# Using auth_token query parameter
curl -X GET "http://192.168.1.3:3000/today_expense_list?auth_token=YOUR_AUTH_TOKEN"
```

## Get Multiple Expense Entries (with Date Range & Pagination)

```bash
# Get all expenses (default: 50 per page)
curl -X GET "http://192.168.1.3:3000/expenses" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
```

```bash
# Get expenses with date range
curl -X GET "http://192.168.1.3:3000/expenses?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
```

```bash
# Get expenses with pagination
curl -X GET "http://192.168.1.3:3000/expenses?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
```

```bash
# Get expenses with date range and pagination
curl -X GET "http://192.168.1.3:3000/expenses?start_date=2025-01-01&end_date=2025-01-31&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
```

```bash
# Get expenses from a specific date onwards
curl -X GET "http://192.168.1.3:3000/expenses?start_date=2025-01-01" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
```

```bash
# Get expenses up to a specific date
curl -X GET "http://192.168.1.3:3000/expenses?end_date=2025-01-31" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
```

**Query Parameters:**
- `start_date` or `from_date`: Start date (YYYY-MM-DD) - optional
- `end_date` or `to_date`: End date (YYYY-MM-DD) - optional
- `page`: Page number (default: 1) - optional
- `limit`: Items per page (default: 50, max recommended: 100) - optional

## Get Particular Expense Entry by ID

```bash
# Using expense ID in URL path
curl -X GET "http://192.168.1.3:3000/expense/123" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
```

```bash
# Using expense ID as query parameter
curl -X GET "http://192.168.1.3:3000/expense?expense_id=123" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
```

```bash
# Using auth_token query parameter
curl -X GET "http://192.168.1.3:3000/expense/123?auth_token=YOUR_AUTH_TOKEN"
```

**Note:** These endpoints only return expenses that belong to the authenticated agent (validated by token).

## Response Format

### Insert Expense Response

```json
{
  "status": "success",
  "message": "Expense inserted successfully",
  "data": {
    "expense_id": 123,
    "expense_date": "2025-01-15",
    "amount": 50.00,
    "reason": "Transportation cost for collection",
    "photo_url": "http://192.168.1.3:3000/uploads/expenses/expense-1705312345-123456789.jpg",
    "created_at": "2025-01-15T10:30:00.000Z"
  }
}
```

### Get Today's Expense List Response

```json
{
  "status": "success",
  "message": "Today's expense list retrieved successfully",
  "data": {
    "agent_info": {
      "agent_id": 1,
      "agent_name": "John Doe",
      "company_id": 1
    },
    "date": "2025-01-15",
    "expenses": [
      {
        "expense_id": 123,
        "expense_date": "2025-01-15",
        "amount": 50.00,
        "reason": "Transportation cost for collection",
        "photo_url": "http://192.168.1.3:3000/uploads/expenses/expense-1705312345-123456789.jpg",
        "created_at": "2025-01-15T10:30:00.000Z"
      }
    ],
    "summary": {
      "total_expenses": 1,
      "total_amount": 50.00
    }
  }
}
```

### Get Multiple Expenses Response

```json
{
  "status": "success",
  "message": "Expenses retrieved successfully",
  "data": {
    "agent_info": {
      "agent_id": 1,
      "agent_name": "John Doe",
      "company_id": 1
    },
    "filters": {
      "start_date": "2025-01-01",
      "end_date": "2025-01-31"
    },
    "pagination": {
      "page": 1,
      "limit": 50,
      "total_count": 150,
      "total_pages": 3,
      "has_next": true,
      "has_previous": false
    },
    "expenses": [
      {
        "expense_id": 123,
        "expense_date": "2025-01-15",
        "amount": 50.00,
        "reason": "Transportation cost for collection",
        "photo_url": "http://192.168.1.3:3000/uploads/expenses/expense-1705312345-123456789.jpg",
        "notes": "Collection Agent Expense - Transportation cost",
        "voucher_id": "EXP1705312345",
        "created_at": "2025-01-15T10:30:00.000Z"
      },
      {
        "expense_id": 124,
        "expense_date": "2025-01-16",
        "amount": 25.00,
        "reason": "Lunch expense",
        "photo_url": null,
        "notes": "Collection Agent Expense - Lunch expense",
        "voucher_id": "EXP1705312346",
        "created_at": "2025-01-16T12:00:00.000Z"
      }
    ],
    "summary": {
      "total_expenses": 2,
      "total_amount": 75.00,
      "total_all_expenses": 150
    }
  }
}
```

### Get Particular Expense Entry Response

```json
{
  "status": "success",
  "message": "Expense retrieved successfully",
  "data": {
    "expense_id": 123,
    "expense_date": "2025-01-15",
    "amount": 50.00,
    "reason": "Transportation cost for collection",
    "photo_url": "http://192.168.1.3:3000/uploads/expenses/expense-1705312345-123456789.jpg",
    "notes": "Collection Agent Expense - Transportation cost for collection",
    "voucher_id": "EXP1705312345",
    "created_at": "2025-01-15T10:30:00.000Z"
  }
}
```

**Error Response (if expense not found or doesn't belong to agent):**

```json
{
  "status": "error",
  "message": "Expense not found or you do not have permission to access it"
}
```

## Notes

1. **File Upload**: 
   - Use `multipart/form-data` format
   - Field name for file must be `photo`
   - Supported image formats: jpeg, jpg, png, gif, webp
   - Maximum file size: 5MB

2. **expense_id**: 
   - This is the database ID (auto-increment) from the voucher table
   - It's returned in the response after successful insertion

3. **agent_id**: 
   - Removed from response (already available in authentication token)
   - Agent information is available from the token

4. **photo_url**: 
   - If file is uploaded, returns the full URL to access the uploaded image
   - Format: `http://YOUR_HOST/uploads/expenses/expense-TIMESTAMP-RANDOM.ext`
   - Images are stored in `uploads/expenses/` directory

5. **Authentication**: 
   - Required for all expense endpoints
   - Can be provided via:
     - `Authorization: Bearer TOKEN` header
     - `auth_token` query parameter

6. **Getting Multiple Expenses**:
   - Use `/expenses` endpoint for multiple entries
   - Supports date range filtering with `start_date` and `end_date`
   - Supports pagination with `page` and `limit` parameters
   - Returns pagination metadata (total count, total pages, has_next, has_previous)
   - Returns summary with total amount for current page and total count of all expenses