Vardhan Oil API Documentation

Version 1.0.0

← Back to Home

Quick Navigation

📌 Overview

Base URL: http://localhost:8000/api

Authentication: Bearer Token (Laravel Sanctum)

Response Format: JSON

📱 Firebase Required:

All authentication endpoints require a valid Firebase ID token obtained from Firebase Authentication.

🛠️ Utility APIs

POST /api/validate-pincode

Validate Indian pincode and get location details

📍 Pincode-First Approach:

User enters pincode → API validates → Returns state, city, district → User confirms/edits → Enters area manually

→ Request Body:

{
  "pincode": "400053"
}

✓ Success Response (200):

{
  "success": true,
  "message": "Pincode validated successfully",
  "data": {
    "pincode": "400053",
    "area": "Andheri West H.O",
    "city": "Mumbai",
    "state": "Maharashtra",
    "country": "India"
  }
}

⚠️ Uses India Post API in real-time. May have occasional timeouts.

🔐 Authentication APIs

POST /api/auth/register

Register a new user

⚠️ Content-Type: multipart/form-data

Required Fields:

firebase_token - Firebase ID token
phone - 10 digits (6-9xxxxxxxxx)
name - User name (2-100 chars)
email - Valid email (unique)
profile_picture - Image file (JPG/PNG, max 2MB)
pincode - 6 digit Indian pincode
state - State name (from pincode API)
city - City name (from pincode API)
area - Area/locality (user enters manually)

Optional Fields:

district - District name (auto-filled from pincode API)
distributor_name - Distributor name
retailer_name - Retailer name
garage_name - Garage name
referral_code - Referral code from existing user

✓ Success Response (201):

{
  "success": true,
  "message": "Registration successful",
  "data": {
    "user": {
      "id": 1,
      "phone": "9876543210",
      "name": "John Doe",
      "email": "john@example.com",
      "profile_picture_url": "https://.../storage/profiles/...",
      "state": "Maharashtra",
      "city": "Mumbai",
      "district": "Mumbai",
      "referral_code": "VRD4X8K2",
      "wallet_balance": "0.00",
      "kyc_status": "pending"
    },
    "token": "1|sanctum_token_here"
  }
}
POST /api/auth/login

Login existing user

→ Request Body:

{
  "firebase_token": "eyJhbGciOiJSUzI1NiIs...",
  "phone": "9876543210"
}

✓ Success Response (200):

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": { ... },
    "token": "2|new_sanctum_token_here"
  }
}
POST /api/auth/logout Protected

Logout current user and revoke token

Headers:

Authorization: Bearer {token}
GET /api/auth/me Protected

Get current authenticated user details

👤 Profile APIs

GET /api/profile Protected

Get user profile with statistics

✓ Success Response:

{
  "success": true,
  "data": {
    "user": { ... },
    "statistics": {
      "total_referrals": 5,
      "wallet_balance": "500.00",
      "total_earned": "1500.00"
    }
  }
}
POST /api/profile/update Protected

Update user profile (all fields optional)

Updatable Fields (All Optional):

name, email, profile_picture (file)
state_id, city_id, area, pincode
distributor_name, retailer_name, garage_name

💡 Note: Old profile picture is automatically deleted when uploading new one.

DELETE /api/profile/delete Protected

Delete user account permanently

→ Request Body:

{
  "confirmation": "DELETE"
}

🛠️ System APIs

GET
/api/health

Check API health status
GET
/api/db-check

Check database connection

🔄 Authentication Flow

1

Pincode Entry

User enters pincode → App calls /api/validate-pincode

2

Location Auto-Fill

API returns state, city, district → App pre-fills these fields

3

User Confirmation

User confirms/edits state & city, enters area manually

4

Firebase OTP

App sends OTP to user's phone via Firebase

5

OTP Verification

User enters OTP → Firebase verifies and returns ID token

6

Registration

App sends all data + Firebase token to /api/auth/register

7

Success

API validates everything and returns user + Sanctum token

⚙️ Setup Requirements

🔥 Firebase Setup Required

  1. Create Firebase project at Firebase Console
  2. Enable Phone Authentication
  3. Download Service Account JSON from Settings → Service Accounts
  4. Save as storage/app/firebase-credentials.json
  5. Add FIREBASE_PROJECT_ID to .env

📁 Storage Setup

Run on server:

php artisan storage:link

© 2026 Vardhan Oil. Powered by <TAG97>