# PHP Backend API Reference

Your PHP backend must implement these endpoints. All responses should be JSON.
All authenticated endpoints expect: `Authorization: Bearer <token>` header.

---

## AUTH

### POST /api/auth/telegram
Authenticate via Telegram initData.
```json
Request:  { "initData": "..." }
Response: { "success": true, "token": "jwt_token_here", "user": { "id": "...", "first_name": "..." }, "is_admin": false }
```

### POST /api/auth/admin-pin
Admin PIN login.
```json
Request:  { "pin": "1234" }
Response: { "success": true, "token": "jwt_token_here" }
```

### GET /api/auth/me (🔒 Auth)
Get current user info + role.
```json
Response: { "id": "uuid", "first_name": "...", "is_admin": true, "profile": {...} }
```

### POST /api/auth/logout (🔒 Auth)
Invalidate token.
```json
Response: { "success": true }
```

---

## PROFILE

### GET /api/profile (🔒 Auth)
```json
Response: { "id": "...", "telegram_id": 123, "first_name": "...", "last_name": "...", "photo_url": "...", "is_active": true }
```

### PUT /api/profile (🔒 Auth)
```json
Request:  { "first_name": "New Name" }
Response: { "success": true }
```

---

## WALLET

### GET /api/wallet/balance (🔒 Auth)
```json
Response: { "balance": 250.00 }
```

### GET /api/wallet/transactions?page=1&limit=20 (🔒 Auth)
```json
Response: { "transactions": [...], "total": 50 }
```

---

## DEPOSITS

### POST /api/deposits (🔒 Auth)
```json
Request:  { "amount": 100, "utr_number": "123456789012" }
Response: { "success": true, "deposit_id": "uuid" }
```

### GET /api/deposits (🔒 Auth)
```json
Response: { "deposits": [{ "id": "...", "amount": 100, "status": "pending", "utr_number": "...", "created_at": "..." }] }
```

---

## PLANS

### GET /api/plans (Public)
```json
Response: { "plans": [{ "id": "...", "name": "Pro", "price": 299, "daily_search_limit": 50, "per_search_cost": 2 }] }
```

### POST /api/plans/purchase (🔒 Auth)
```json
Request:  { "plan_id": "uuid" }
Response: { "success": true, "balance": 150.00, "plan": "Pro", "expires_at": "2026-04-16" }
```

### GET /api/plans/current (🔒 Auth)
```json
Response: { "plan": { "name": "Pro", "daily_search_limit": 50, "expires_at": "..." }, "searches_today": 5 }
```

---

## VEHICLE SEARCH

### POST /api/vehicle/lookup (🔒 Auth)
```json
Request:  { "registration_number": "MH01AB1234" }
Response: { "success": true, "search_id": "uuid", "result": { "owner": "...", "model": "...", ... }, "charged": 5, "balance": 245 }
```

### POST /api/vehicle/unlock (🔒 Auth)
```json
Request:  { "search_id": "uuid", "unlock_type": "mobile" }
Response: { "success": true, "data": { "mobile_no": "9876543210" }, "charged": 59, "remaining_balance": 186 }
```

### GET /api/search/history?page=1&limit=20 (🔒 Auth)
```json
Response: { "searches": [...], "total": 100 }
```

---

## REFERRALS

### GET /api/referrals/stats (🔒 Auth)
```json
Response: { "referral_code": "ABC123", "total_referrals": 5, "bonus_searches_remaining": 3 }
```

### POST /api/referrals/apply (🔒 Auth)
```json
Request:  { "code": "ABC123" }
Response: { "success": true }
```

---

## API KEYS

### GET /api/api-keys (🔒 Auth)
```json
Response: { "keys": [{ "id": "...", "name": "Default", "key_prefix": "vl_abc", "requests_today": 10, "requests_total": 500 }] }
```

### POST /api/api-keys (🔒 Auth)
```json
Request:  { "name": "My Key" }
Response: { "success": true, "key": "vl_abc123...full_key", "id": "uuid" }
```

### DELETE /api/api-keys/:id (🔒 Auth)
```json
Response: { "success": true }
```

---

## SETTINGS (Public)

### GET /api/settings
```json
Response: { "upi_enabled": true, "gateway_enabled": false, "oxapay_enabled": true, "upi_id": "pay@upi", "support_username": "support_bot" }
```

---

## PAYMENT

### POST /api/payment/create-order (🔒 Auth)
```json
Request:  { "amount": 500 }
Response: { "order_id": "...", "payment_url": "..." }
```

### POST /api/payment/oxapay (🔒 Auth)
```json
Request:  { "amount": 500 }
Response: { "payment_url": "https://oxapay.com/pay/..." }
```

---

## ADMIN ENDPOINTS (🔒 Admin only)

### GET /api/admin/users?page=1&search=
### PUT /api/admin/users/:id/toggle  `{ "is_active": false }`
### DELETE /api/admin/users/:id
### POST /api/admin/wallet/adjust  `{ "user_id": "...", "amount": 100, "description": "Bonus" }`
### GET /api/admin/deposits?status=pending
### PUT /api/admin/deposits/:id  `{ "action": "approved", "admin_note": "Verified" }`
### GET /api/admin/search-logs?page=1
### DELETE /api/admin/search-logs/:id
### GET /api/admin/settings
### PUT /api/admin/settings  `{ "key": "value", ... }`
### GET /api/admin/api-config
### PUT /api/admin/api-config  `{ ... }`
### POST /api/admin/telegram/broadcast  `{ "message": "Hello everyone!" }`

---

## PHP Implementation Notes

1. **Auth**: Use JWT (firebase/php-jwt). Verify Telegram initData hash with your bot token.
2. **Database**: MySQL with the schema from `/db.sql`
3. **UUIDs**: Use `UUID()` in MySQL or `ramsey/uuid` in PHP
4. **Telegram Notifications**: Use `file_get_contents` or `curl` to call Telegram Bot API
5. **CORS**: Add these headers to every response:
   ```php
   header("Access-Control-Allow-Origin: *");
   header("Access-Control-Allow-Headers: Authorization, Content-Type");
   header("Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS");
   if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') { http_response_code(204); exit; }
   ```