# Chitti Finserv API Documentation

## Base URL
```
http://localhost:5000/api
```

## Authentication
All protected routes require a Bearer token in the Authorization header:
```
Authorization: Bearer <your-jwt-token>
```

## API Endpoints

### Authentication Routes

#### Register User
```
POST /auth/register
```
**Body:**
```json
{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "9876543210",
  "password": "password123"
}
```

#### Login User
```
POST /auth/login
```
**Body:**
```json
{
  "email": "john@example.com",
  "password": "password123"
}
```

#### Send OTP
```
POST /auth/send-otp
```
**Body:**
```json
{
  "email": "john@example.com"
}
```

#### Verify OTP
```
POST /auth/verify-otp
```
**Body:**
```json
{
  "email": "john@example.com",
  "otp": "123456"
}
```

#### Get Current User
```
GET /auth/me
```
**Headers:** Authorization required

#### Update FCM Token
```
PUT /auth/fcm-token
```
**Headers:** Authorization required
**Body:**
```json
{
  "fcmToken": "firebase-fcm-token"
}
```

#### Logout
```
POST /auth/logout
```
**Headers:** Authorization required

### Categories Routes

#### Get All Categories
```
GET /categories
```

#### Get Single Category
```
GET /categories/:id
```

#### Create Category (Admin Only)
```
POST /categories
```
**Headers:** Authorization required
**Body:**
```json
{
  "name": "Personal Loan",
  "icon": "personal.svg",
  "description": "Personal loan category",
  "sortOrder": 1
}
```

#### Update Category (Admin Only)
```
PUT /categories/:id
```
**Headers:** Authorization required
**Body:**
```json
{
  "name": "Personal Loan",
  "icon": "personal.svg",
  "description": "Updated description",
  "sortOrder": 2,
  "isActive": true
}
```

#### Delete Category (Admin Only)
```
DELETE /categories/:id
```
**Headers:** Authorization required

#### Update Category Order (Admin Only)
```
PUT /categories/order
```
**Headers:** Authorization required
**Body:**
```json
{
  "categories": [
    { "id": "category1", "sortOrder": 1 },
    { "id": "category2", "sortOrder": 2 }
  ]
}
```

### Loan Applications Routes

#### Get All Applications (Agent/Admin Only)
```
GET /loan-applications?status=pending&category=categoryId&page=1&limit=10&search=john
```
**Headers:** Authorization required
**Query Parameters:**
- `status`: Filter by status (pending, under_review, approved, rejected, disbursed)
- `category`: Filter by category ID
- `page`: Page number (default: 1)
- `limit`: Items per page (default: 10)
- `search`: Search by user name, email, or phone

#### Get User's Applications
```
GET /loan-applications/my-applications
```
**Headers:** Authorization required

#### Get Single Application
```
GET /loan-applications/:id
```
**Headers:** Authorization required

#### Create Loan Application
```
POST /loan-applications
```
**Headers:** Authorization required
**Body:**
```json
{
  "category": "categoryId",
  "loanType": "personal",
  "loanAmount": 50000,
  "loanPurpose": "Home renovation",
  "monthlyIncome": 75000,
  "employmentType": "salaried",
  "companyName": "ABC Corp",
  "workExperience": 5,
  "address": {
    "street": "123 Main St",
    "city": "Mumbai",
    "state": "Maharashtra",
    "pincode": "400001"
  },
  "documents": {
    "aadharCard": "aadhar-upload-url",
    "panCard": "pan-upload-url",
    "bankStatement": "bank-statement-url",
    "salarySlip": "salary-slip-url"
  }
}
```

#### Update Application Status (Agent/Admin Only)
```
PUT /loan-applications/:id/status
```
**Headers:** Authorization required
**Body:**
```json
{
  "status": "approved",
  "remarks": "Application approved after verification"
}
```

#### Update Application
```
PUT /loan-applications/:id
```
**Headers:** Authorization required
**Body:** Same as create application

#### Delete Application
```
DELETE /loan-applications/:id
```
**Headers:** Authorization required

#### Get Dashboard Statistics (Agent/Admin Only)
```
GET /loan-applications/dashboard/stats
```
**Headers:** Authorization required

### Health Check
```
GET /health
```

## Response Format

### Success Response
```json
{
  "success": true,
  "message": "Operation successful",
  "data": {
    // Response data
  }
}
```

### Error Response
```json
{
  "success": false,
  "message": "Error message",
  "errors": [
    {
      "field": "email",
      "message": "Please enter a valid email"
    }
  ]
}
```

## Status Codes

- `200` - Success
- `201` - Created
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `500` - Server Error

## File Upload

For file uploads, use multipart/form-data and send files to the upload endpoint. The response will contain the file URL to be used in the application.

## Push Notifications

The API automatically sends push notifications when:
- Loan application status is updated
- New loan application is created (for agents)

## Email Notifications

The API automatically sends emails when:
- User registers (welcome email)
- OTP is sent for verification
- Loan application status is updated

## Rate Limiting

- 100 requests per 15 minutes per IP address
- Rate limit headers are included in responses

## Environment Variables

Make sure to set up the following environment variables:

```env
PORT=5000
NODE_ENV=development
MONGODB_URI=mongodb://localhost:27017/chitti_finserv
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRE=7d
FIREBASE_PROJECT_ID=your-firebase-project-id
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
```