# UdanKhatola Mobile App API Testing Guide

## Quick Start

### 1. Import Postman Collection
1. Open Postman
2. Click **Import** button
3. Select file: `UdanKhatola_API_Collection.postman_collection.json`
4. Collection will be imported with all endpoints

### 2. Configure Environment Variables
In Postman, set these collection variables:
- `base_url`: `http://localhost:8000/api` (or your server URL)
- `token`: (will be auto-set after login)

### 3. Test Flow

## Complete Testing Workflow

### Step 1: Authentication Flow

#### A. Request OTP
```
POST {{base_url}}/v2/request-otp
```
**Body:**
```json
{
  "mobile_number": "9876543210"
}
```
**Expected Response:**
```json
{
  "success": true,
  "data": {
    "otp_sent": true,
    "mobile": "9876543210",
    "valid_for": "24 hours"
  }
}
```

#### B. Login (Token auto-saved)
```
POST {{base_url}}/v2/login
```
**Body:**
```json
{
  "mobile_number": "9876543210",
  "otp": "123456",
  "device_id": "test-device-123",
  "fcm_token": "test-fcm-token"
}
```
**Expected Response:**
```json
{
  "success": true,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "partner": {
      "id": 1,
      "name": "Agent Name",
      "mobile": "9876543210",
      "loccode": "CHD"
    },
    "persistent_login": true
  }
}
```

#### C. Verify Token (Test Persistent Login)
```
GET {{base_url}}/v2/verify-token
Headers: Authorization: Bearer {{token}}
```

### Step 2: Location Validation

#### A. Validate Agent Location
```
POST {{base_url}}/v2/validate-location
Headers: Authorization: Bearer {{token}}
```
**Body:**
```json
{
  "latitude": 30.3165,
  "longitude": 78.0322
}
```

**Success Response:**
```json
{
  "success": true,
  "data": {
    "is_valid": true,
    "message": "Location validated successfully"
  }
}
```

**Failure Response (Outside Geofence):**
```json
{
  "success": false,
  "message": "You are outside the allowed booking area",
  "data": {
    "is_valid": false,
    "violations": [
      {
        "location": "Chandi Devi",
        "distance": 1500.25,
        "allowed_radius": 1000,
        "exceeded_by": 500.25
      }
    ]
  }
}
```

#### B. Get Region Locations
```
GET {{base_url}}/v2/partner-region-locations
Headers: Authorization: Bearer {{token}}
```

### Step 3: Booking Flow

#### A. Get Locations
```
GET {{base_url}}/v2/location-list
Headers: Authorization: Bearer {{token}}
```

#### B. Get Price Cards
```
POST {{base_url}}/v2/price-card-by-location
Headers: Authorization: Bearer {{token}}
```
**Body:**
```json
{
  "loccode": "CHD"
}
```

#### C. Get Available Slots
```
POST {{base_url}}/v2/available-slots
Headers: Authorization: Bearer {{token}}
```
**Body:**
```json
{
  "code": "ADULT001",
  "visit_date": "2026-04-15",
  "next_loccode": "CHD",
  "ticket_count": 2
}
```

#### D. Book Ticket (Simplified - No Customer OTP)
```
POST {{base_url}}/v2/book-ticket
Headers: Authorization: Bearer {{token}}
```
**Body:**
```json
{
  "customer_name": "John Doe",
  "customer_mobile": "9876543210",
  "loccode": "CHD",
  "visit_date": "2026-04-15",
  "slot": 10,
  "tickets": [
    {
      "code": "ADULT001",
      "quantity": 2,
      "amount": 500
    },
    {
      "code": "CHILD001",
      "quantity": 1,
      "amount": 250
    }
  ],
  "total_amount": 750,
  "latitude": 30.3165,
  "longitude": 78.0322
}
```

**Expected Response:**
```json
{
  "success": true,
  "data": {
    "booking_id": "UDK17131234565678",
    "customer_name": "John Doe",
    "total_tickets": 3,
    "total_amount": 750,
    "location_validated": true,
    "message": "Booking created successfully. Proceed to payment."
  }
}
```

#### E. Confirm Payment (Location Re-validated)
```
POST {{base_url}}/v2/confirm-payment
Headers: Authorization: Bearer {{token}}
```
**Body:**
```json
{
  "booking_id": "UDK17131234565678",
  "payment_reference": "UPI123456789",
  "payment_status": "success",
  "latitude": 30.3165,
  "longitude": 78.0322
}
```

**Expected Response:**
```json
{
  "success": true,
  "data": {
    "booking_id": "UDK17131234565678",
    "status": "confirmed",
    "tickets_sent": true,
    "message": "Booking confirmed! Tickets sent via WhatsApp and SMS."
  }
}
```

### Step 4: Ticket Management

#### A. Download Ticket PDF
```
GET {{base_url}}/v2/download-ticket/UDK17131234565678
Headers: Authorization: Bearer {{token}}
```
**Response:** PDF file download

#### B. Share Ticket
```
POST {{base_url}}/v2/share-ticket
Headers: Authorization: Bearer {{token}}
```
**Body:**
```json
{
  "booking_id": "UDK17131234565678",
  "mobile": "9876543210"
}
```

#### C. Booking History
```
GET {{base_url}}/v2/booking-history?page=1
Headers: Authorization: Bearer {{token}}
```

## Testing Scenarios

### Scenario 1: Successful Booking Flow
1. Request OTP → Login
2. Validate location (within geofence)
3. Get locations → Get price cards → Get slots
4. Book ticket (location auto-validated)
5. Confirm payment (location re-validated)
6. Download/Share ticket

### Scenario 2: Location Validation Failure
1. Login
2. Validate location with coordinates outside geofence
3. Expect error with violation details
4. Cannot proceed to booking

### Scenario 3: Payment Timeout Protection
1. Login → Book ticket
2. Wait 5+ minutes
3. Try to confirm payment from different location
4. Expect location validation failure

### Scenario 4: Persistent Login
1. Login once with device_id
2. Close app
3. Reopen app → Call verify-token
4. Should be still logged in (no OTP required)

## Common Test Cases

### ✅ Positive Tests
- [ ] Login with valid OTP
- [ ] Location validation within geofence
- [ ] Booking with valid data
- [ ] Payment confirmation with valid location
- [ ] Download ticket PDF
- [ ] Share ticket via WhatsApp
- [ ] View booking history

### ❌ Negative Tests
- [ ] Login with invalid OTP
- [ ] Login with expired OTP (>24 hours)
- [ ] Location validation outside geofence
- [ ] Booking without location validation
- [ ] Payment confirmation from different location
- [ ] Access protected endpoints without token
- [ ] Book with invalid ticket codes

## Error Response Format

All errors follow this format:
```json
{
  "success": false,
  "message": "Error description",
  "data": {
    // Additional error details
  }
}
```

## Status Codes
- `200` - Success
- `400` - Validation Error
- `401` - Unauthorized (invalid/missing token)
- `403` - Forbidden (account inactive/expired)
- `404` - Not Found
- `500` - Server Error

## Environment Setup for Testing

### Local Development
```
base_url: http://localhost:8000/api
```

### Staging
```
base_url: https://staging.udankhatola.com/api
```

### Production
```
base_url: https://api.udankhatola.com/api
```

## Notes

1. **Token Management**: Token is automatically saved after login in Postman collection
2. **Location Coordinates**: Use real coordinates for testing geofencing
3. **OTP**: Check WhatsApp/SMS for actual OTP in production
4. **Booking IDs**: Save booking_id from response for subsequent operations
5. **Date Format**: Use `YYYY-MM-DD` for visit_date
6. **Slot Numbers**: Use 1-24 for hourly slots

## Troubleshooting

### Issue: "Token is invalid"
- Solution: Login again to get fresh token

### Issue: "Location validation failed"
- Solution: Check if coordinates are within geofence radius
- Verify location has latitude/longitude set in admin panel

### Issue: "Booking not found"
- Solution: Use correct booking_id from book-ticket response

### Issue: "Account validity expired"
- Solution: Contact admin to extend validity

## Support
For issues or questions, contact the development team.

---
**Last Updated:** April 13, 2026