Subversion Repositories SmartDukaan

Rev

Blame | Last modification | View Log | RSS feed 

# ProfitMandi Web - API Workflow Documentation

> **Base Technology:** Spring Boot (Java)
> **Authentication:** JWT Bearer Token via `Auth-Token` request header
> **Response Format:** JSON (`application/json`)
> **Response Wrapper:** All responses are wrapped in `ResponseEntity<?>` using `ResponseSender` utility

---

## Table of Contents

1. [Authentication & User Management](#1-authentication--user-management)
2. [Store & Product Catalog](#2-store--product-catalog)
3. [Cart & Checkout](#3-cart--checkout)
4. [Order Management](#4-order-management)
5. [Wallet & Payments](#5-wallet--payments)
6. [Lead & Partner Management](#6-lead--partner-management)

---

## 1. Authentication & User Management

### 1.1 Google Login / Email Login

| Field | Value |
|-------|-------|
| **URL** | `POST /user/google-login` |
| **Auth Required** | No |

**Request Body:**
```json
{
  "email": "user@example.com",
  "token": "google_oauth_token",
  "password": "optional_password"
}
```

**Response (200 OK):**
```json
{
  "token": "jwt_token_string",
  "registered": true,
  "userStatus": "ACTIVE",
  "email": "user@example.com"
}
```

**Workflow:** This is the primary login endpoint. It accepts a Google OAuth token or email/password combination. Returns a JWT token used for all subsequent authenticated requests via the `Auth-Token` header.

---

### 1.2 Get Unregistered User Token

| Field | Value |
|-------|-------|
| **URL** | `GET /user/token/unregistered` |
| **Auth Required** | No |

**Request:** No parameters required.

**Response (200 OK):**
```json
{
  "token": "jwt_token_for_guest",
  "registered": false
}
```

**Workflow:** Generates a temporary guest token for unauthenticated users to browse the catalog and add items to cart before registration.

---

### 1.3 Get User Details (Authenticated)

| Field | Value |
|-------|-------|
| **URL** | `GET /user/detail` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Request:** No parameters. Auth token identifies the user.

**Response (200 OK):**
```json
{
  "userId": 1234,
  "userName": "John Doe",
  "emailId": "john@example.com",
  "userStatus": "REGISTERED",
  "address": {
    "line1": "123 Main St",
    "city": "Delhi",
    "state": "Delhi",
    "pin": "110001"
  },
  "storeUrl": "/stores/delhi/new-delhi/SD1234",
  "timelineStatus": "ACTIVE",
  "fofoTrialEndDate": "2026-03-31",
  "userInfo": { ... }
}
```

**Workflow:** Called after login to fetch the authenticated user's full profile including retailer/FOFO store details, address, and onboarding status.

---

### 1.4 Create New User

| Field | Value |
|-------|-------|
| **URL** | `POST /user` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Request Body:**
```json
{
  "firstName": "John",
  "lastName": "Doe",
  "emailId": "john@example.com",
  "mobieNumber": "9876543210",
  "city": "Delhi",
  "pinCode": "110001",
  "state": "Delhi"
}
```

**Response (200 OK):**
```json
{
  "message": "User created successfully"
}
```

---

### 1.5 Forgot Password

| Field | Value |
|-------|-------|
| **URL** | `POST /user/forgot-password` |
| **Auth Required** | No |

**Request Body:**
```json
{
  "email": "user@example.com"
}
```

**Response (200 OK):**
```json
true
```

**Workflow:** Sends a password reset email to the registered email address.

---

### 1.6 Change Password

| Field | Value |
|-------|-------|
| **URL** | `POST /user/change-password` |
| **Auth Required** | No |

**Request Body:**
```json
{
  "email": "user@example.com",
  "password": "current_password",
  "newPassword": "new_password"
}
```

**Response (200 OK):**
```json
true
```

---

## 2. Store & Product Catalog

### 2.1 Get Product/Entity Details

| Field | Value |
|-------|-------|
| **URL** | `GET /store/entity/{id}` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | long | Catalog item ID |

**Response (200 OK):**
```json
{
  "catalogId": 5678,
  "itemName": "Samsung Galaxy M14",
  "brand": "Samsung",
  "category": "Smartphones",
  "mrp": 15999.00,
  "dp": 12500.00,
  "sellingPrice": 13999.00,
  "imageUrl": "https://cdn.example.com/img/product.jpg",
  "inStock": true,
  "specs": { ... },
  "availableQuantity": 25,
  "color": "Blue"
}
```

**Workflow:** Fetches detailed product information including pricing, availability, and specifications for a catalog item.

---

### 2.2 Get Brands by Category

| Field | Value |
|-------|-------|
| **URL** | `GET /store/brands` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category_id` | String | Yes | Category ID to filter brands |

**Response (200 OK):**
```json
[
  {
    "brandId": 1,
    "brandName": "Samsung",
    "count": 45
  },
  {
    "brandId": 2,
    "brandName": "Apple",
    "count": 30
  }
]
```

---

### 2.3 Get Product Listings

| Field | Value |
|-------|-------|
| **URL** | `GET /store/listing/{listingUrl}` |
| **Auth Required** | No |

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `listingUrl` | String | URL slug for the listing (e.g., "best-sellers") |

**Response (200 OK):**
```json
{
  "listingName": "Best Sellers",
  "fofoCatalogResponses": [
    {
      "catalogId": 5678,
      "itemName": "Samsung Galaxy M14",
      "brand": "Samsung",
      "mrp": 15999.00,
      "dp": 12500.00,
      "imageUrl": "https://cdn.example.com/img/product.jpg",
      "inStock": true
    }
  ]
}
```

---

### 2.4 Get Partner Stock

| Field | Value |
|-------|-------|
| **URL** | `GET /store/partnerStock` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `categoryId` | String | "3" | Category ID |
| `offset` | int | required | Pagination offset |
| `limit` | int | required | Page size |
| `sort` | String | optional | Sort field |
| `brand` | String | optional | Brand filter |
| `subCategoryId` | int | optional | Sub-category filter |
| `queryTerm` | String | optional | Search term |
| `partnerStockOnly` | boolean | true | Show only partner's stock |

**Response (200 OK):**
```json
[
  {
    "catalogId": 5678,
    "itemName": "Samsung Galaxy M14",
    "brand": "Samsung",
    "mrp": 15999.00,
    "dp": 12500.00,
    "availableQuantity": 10,
    "imageUrl": "https://cdn.example.com/img/product.jpg"
  }
]
```

---

### 2.5 Check Mobile Registration / Get Customer

| Field | Value |
|-------|-------|
| **URL** | `GET /store/checkmobile/{mobile}` |
| **Auth Required** | No |

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `mobile` | String | Mobile number to check |

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `isSmartSeller` | boolean | false | Whether user is a smart seller |

**Response (200 OK):**
```json
{
  "customer": {
    "id": 100,
    "firstName": "John",
    "lastName": "Doe",
    "mobile": "9876543210",
    "email": "john@example.com",
    "passwordExists": true
  },
  "exists": true
}
```

---

### 2.6 Store Customer Registration

| Field | Value |
|-------|-------|
| **URL** | `POST /store/register` |
| **Auth Required** | No |

**Request Body:**
```json
{
  "mobile": "9876543210",
  "password": "secure_password",
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "isSmartSeller": false,
  "referralCode": "REF123"
}
```

**Response (200 OK):**
```json
{
  "id": 100,
  "firstName": "John",
  "lastName": "Doe",
  "mobile": "9876543210",
  "email": "john@example.com"
}
```

**Workflow:** Registers a new customer. For smart sellers, handles referral rewards and sends welcome email.

---

### 2.7 Store Customer Sign In

| Field | Value |
|-------|-------|
| **URL** | `POST /store/signin` |
| **Auth Required** | No |

**Request Body:**
```json
{
  "mobile": "9876543210",
  "password": "user_password"
}
```

**Response (200 OK):**
```json
true
```

---

### 2.8 Generate OTP

| Field | Value |
|-------|-------|
| **URL** | `GET /store/otp/generateOTP` |
| **Auth Required** | No |

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mobile` | String | Yes | Mobile number to send OTP |

**Response (200 OK):**
```json
{
  "referenceId": "abc123",
  "status": "success"
}
```

---

## 3. Cart & Checkout

### 3.1 Add Items to Cart (Validate Cart)

| Field | Value |
|-------|-------|
| **URL** | `POST /cart` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `pincode` | String | "110001" | Delivery pincode |

**Request Body:**
```json
{
  "cartItems": [
    {
      "itemId": 5678,
      "quantity": 2
    },
    {
      "itemId": 9012,
      "quantity": 1
    }
  ]
}
```

**Response (200 OK):**
```json
{
  "cartResponse": {
    "cartItems": [
      {
        "itemId": 5678,
        "quantity": 2,
        "sellingPrice": 13999.00,
        "maxQuantity": 5,
        "estimate": 3,
        "promiseDelivery": "2026-02-28",
        "imageUrl": "https://cdn.example.com/img/product.jpg",
        "color": "Blue"
      }
    ],
    "cartMessages": [],
    "totalAmount": 27998,
    "totalQty": 3,
    "maxEstimate": 5
  },
  "response": "Success",
  "message": "Items added to cart successfully"
}
```

**Workflow:** Validates cart items against inventory (store + warehouse), applies cashback/schemes, adjusts quantities based on availability, and returns delivery estimates.

---

### 3.2 Get Cart from Bucket

| Field | Value |
|-------|-------|
| **URL** | `GET /cart` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `pincode` | String | "110001" | Delivery pincode |
| `bucketId` | int | required | Bucket/cart ID |

**Response:** Same structure as `POST /cart` response above.

---

### 3.3 Change Delivery Address

| Field | Value |
|-------|-------|
| **URL** | `POST /cart/change-address` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `addressId` | long | Yes | New delivery address ID |

**Response (200 OK):**
```json
"Address Changed successfully"
```

---

### 3.4 Store Cart (Customer-Facing)

| Field | Value |
|-------|-------|
| **URL** | `POST /store/cart` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Request Body:**
```json
{
  "cartItems": [
    {
      "itemId": 5678,
      "quantity": 1,
      "sellingPrice": 13999.00,
      "smartSellerId": "SS001",
      "pendingOrderItemPolicyPlan": null
    }
  ]
}
```

**Response (200 OK):**
```json
{
  "cartResponse": {
    "cartItems": [ ... ],
    "cartMessages": [],
    "totalAmount": 13999,
    "totalQty": 1
  },
  "message": "Cart validated",
  "description": ""
}
```

---

## 4. Order Management

### 4.1 Create Order from Cart

| Field | Value |
|-------|-------|
| **URL** | `GET /order/create` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `paymentOption` | String | required | Payment method selection |
| `walletUsed` | double | required | Amount deducted from wallet |
| `selfPickup` | boolean | false | Whether customer picks up from store |
| `freeCreditDays` | int | 0 | Free credit period in days |

**Response (200 OK):**
```json
{
  "gatewayUrl": "https://payment-gateway.com/pay",
  "postParams": { ... },
  "paymentId": 78901
}
```

**Workflow:** Converts the validated cart into an order. If payment is required, returns a payment gateway URL with form parameters. For wallet-only payments, the order is confirmed immediately.

---

### 4.2 Confirm Store Order

| Field | Value |
|-------|-------|
| **URL** | `POST /store/confirmOrder` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Request Body:**
```json
{
  "createPendingOrderItem": [
    {
      "itemId": 5678,
      "quantity": 1,
      "sellingPrice": 13999.00,
      "smartSellerId": "SS001",
      "pendingOrderItemPolicyPlan": {
        "planId": 10,
        "planAmount": 499.00
      }
    }
  ],
  "totalAmount": 14498
}
```

**Response (200 OK):**
```json
{
  "poId": "PO-20260224-001"
}
```

**Workflow:** Creates a pending order from the customer-facing store. Validates inventory, sends order confirmation email/SMS, and notifies partners.

---

### 4.3 Get All Orders (Paginated)

| Field | Value |
|-------|-------|
| **URL** | `GET /order/all` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `offset` | int | 0 | Pagination offset |
| `limit` | int | 20 | Page size |

**Response (200 OK):**
```json
[
  {
    "orderId": 12345,
    "unitPrice": "13999.00",
    "totalAmount": "13999.00",
    "itemName": "Samsung Galaxy M14",
    "quantity": 1,
    "itemId": 5678,
    "orderedOn": "2026-02-24",
    "promisedDelivery": "2026-02-28",
    "status": "CONFIRMED",
    "courierName": "Delhivery",
    "awbNumber": "AWB123456",
    "isCancellable": true,
    "color": "Blue",
    "shippingAddress": {
      "addressId": "1",
      "name": "John Doe",
      "line1": "123 Main St",
      "city": "Delhi",
      "state": "Delhi",
      "pin": "110001",
      "phone": "9876543210"
    }
  }
]
```

---

### 4.4 Get Orders by Status and Month

| Field | Value |
|-------|-------|
| **URL** | `GET /order/orderAll/{status}/{yearMonth}` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | OrderStatus | Order status enum (e.g., CONFIRMED, DELIVERED, CANCELLED) |
| `yearMonth` | YearMonth | Year-month in `YYYY-MM` format |

**Response (200 OK):**
```json
[
  {
    "orderId": 12345,
    "itemName": "Samsung Galaxy M14",
    "status": "DELIVERED",
    "totalAmount": "13999.00",
    "orderedOn": "2026-02-10"
  }
]
```

---

### 4.5 Cancel Order (Partner)

| Field | Value |
|-------|-------|
| **URL** | `POST /partnerCancelOrder` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `orderId` | int | Yes | Order ID to cancel |
| `reason` | String | Yes | Cancellation reason |

**Response (200 OK):**
```json
true
```

---

### 4.6 Search Items

| Field | Value |
|-------|-------|
| **URL** | `GET /item` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | String | Yes | Search keyword |

**Response (200 OK):**
```json
[
  {
    "itemId": 5678,
    "itemName": "Samsung Galaxy M14",
    "brand": "Samsung",
    "imei": "352456789012345",
    "mrp": 15999.00,
    "dp": 12500.00
  }
]
```

---

### 4.7 Check Item Availability

| Field | Value |
|-------|-------|
| **URL** | `GET /checkItemAvailability` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `itemId` | int | Yes | Catalog item ID |

**Response (200 OK):**
```json
{
  "itemId": 5678,
  "availableQuantity": 15,
  "warehouseStock": 10,
  "storeStock": 5,
  "lastUpdated": "2026-02-24T10:30:00"
}
```

---

### 4.8 Generate Invoice PDF

| Field | Value |
|-------|-------|
| **URL** | `GET /order/generateInvoice` |
| **Auth Required** | No |

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `invoiceNumber` | String | Yes | Invoice number |

**Response:** Returns a PDF file.

| Header | Value |
|--------|-------|
| Content-Type | `application/pdf` |
| Content-Disposition | `inline; filename=invoice-{invoiceNumber}.pdf` |

---

## 5. Wallet & Payments

### 5.1 Get Wallet Balance

| Field | Value |
|-------|-------|
| **URL** | `GET /wallet/my-wallet` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Request:** No parameters.

**Response (200 OK):**
```json
{
  "walletId": 456,
  "balance": 25000.00,
  "currency": "INR",
  "retailerId": 789
}
```

---

### 5.2 Get Wallet Transaction History

| Field | Value |
|-------|-------|
| **URL** | `GET /wallet/my-wallet-history` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Request:** No parameters. Returns up to 150 recent transactions.

**Response (200 OK):**
```json
[
  {
    "transactionId": 1001,
    "amount": 5000.00,
    "type": "CREDIT",
    "description": "Order refund #12345",
    "timestamp": "2026-02-24T14:30:00",
    "balance": 25000.00
  },
  {
    "transactionId": 1000,
    "amount": -13999.00,
    "type": "DEBIT",
    "description": "Order payment #12344",
    "timestamp": "2026-02-23T10:00:00",
    "balance": 20000.00
  }
]
```

---

### 5.3 Add Money to Wallet (Bank Transfer)

| Field | Value |
|-------|-------|
| **URL** | `POST /wallet/add-money` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Request Body:**
```json
{
  "transaction_reference": "UTR123456789",
  "amount": 50000.00,
  "reference_date": "2026-02-24",
  "bank_name": "HDFC Bank"
}
```

**Response (200 OK):**
```json
true
```

**Error Response (400 Bad Request):**
```json
{
  "error": "Transaction Reference (UTR) UTR123456789 Already added"
}
```

**Workflow:** Creates a pending wallet top-up request via bank transfer. The request is verified and approved internally. Duplicate UTR numbers are rejected.

---

### 5.4 Add Money via Payment Gateway (Loan)

| Field | Value |
|-------|-------|
| **URL** | `GET /wallet/add-via-loan` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loanAmount` | double | Yes | Amount to add |
| `surcharge` | double | Yes | Gateway surcharge |
| `payMethod` | String | Yes | Payment method (e.g., "CREDIT_CARD") |
| `gateway` | Gateway | Yes | Payment gateway (e.g., "CCAVENUE") |

**Response (200 OK):**
```json
{
  "merchant_id": "M12345",
  "order_id": "ORD-789",
  "amount": "50000.00",
  "redirect_url": "https://example.com/callback",
  "cancel_url": "https://example.com/cancel",
  "enc_val": "encrypted_payment_data",
  "access_code": "ACC123",
  "status": "pending"
}
```

**Workflow:** Returns payment gateway form parameters. The frontend renders the payment form and redirects to the gateway (CCAvenue/PineLabs).

---

### 5.5 Get Add Money History

| Field | Value |
|-------|-------|
| **URL** | `GET /wallet/add-money-history` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `offset` | int | 0 | Pagination offset |
| `limit` | int | 10 | Page size |

**Response (200 OK):**
```json
[
  {
    "id": 101,
    "retailerId": 789,
    "amount": 50000.00,
    "transaction_reference": "UTR123456789",
    "reference_date": "2026-02-24",
    "bank_name": "HDFC Bank",
    "status": "approved"
  }
]
```

---

### 5.6 Get Payment Options

| Field | Value |
|-------|-------|
| **URL** | `GET /getPaymentOptions` |
| **Auth Required** | No |

**Request:** No parameters.

**Response (200 OK):**
```json
{
  "CCAVENUE": [
    {
      "paymentMethod": "CREDIT_CARD",
      "paymentMethodDescription": "Credit Card",
      "surcharge": 1.5
    },
    {
      "paymentMethod": "NET_BANKING",
      "paymentMethodDescription": "Net Banking",
      "surcharge": 0.75
    }
  ],
  "PINELABS": [
    {
      "paymentMethod": "UPI",
      "paymentMethodDescription": "UPI Payment",
      "surcharge": 0
    }
  ]
}
```

---

## 6. Lead & Partner Management

### 6.1 Create / Update Lead

| Field | Value |
|-------|-------|
| **URL** | `POST /lead` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Request Body:**
```json
{
  "firstName": "Jane",
  "lastName": "Smith",
  "mobile": "9876543210",
  "state": "Maharashtra",
  "city": "Mumbai",
  "address": "456 Park Avenue",
  "outletName": "Jane Electronics",
  "potential": "HIGH",
  "status": "NEW",
  "source": "REFERRAL",
  "reason": "",
  "remark": "Interested in franchise",
  "schelduleTimestamp": "2026-03-01T10:00:00",
  "communicationType": "CALL"
}
```

**Response (200 OK):**
```json
true
```

---

### 6.2 Get Leads by Status

| Field | Value |
|-------|-------|
| **URL** | `GET /lead-description` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `gmailId` | String | Yes | User's email ID |
| `status` | String | Yes | Lead status filter |

**Response (200 OK):**
```json
[
  {
    "leadId": 201,
    "firstName": "Jane",
    "lastName": "Smith",
    "mobile": "9876543210",
    "city": "Mumbai",
    "state": "Maharashtra",
    "status": "NEW",
    "potential": "HIGH",
    "createdDate": "2026-02-20"
  }
]
```

---

### 6.3 Create Referral

| Field | Value |
|-------|-------|
| **URL** | `POST /user/refferal` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Request Body:**
```json
{
  "firstName": "Mike",
  "lastName": "Wilson",
  "mobile": "9123456789",
  "state": "Karnataka",
  "city": "Bangalore",
  "isFofoAssociate": true,
  "refereeEmail": "referee@example.com"
}
```

**Response (200 OK):**
```json
true
```

---

### 6.4 Get Referral Earnings

| Field | Value |
|-------|-------|
| **URL** | `GET /user/refferalAmount` |
| **Auth Required** | Yes (`Auth-Token` header) |

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `refereeEmail` | String | Yes | Referee's email |

**Response (200 OK):**
```json
{
  "timestamp": "2026-02-24T10:00:00",
  "refferalEarningModel": [
    {
      "yearMonth": "2026-02",
      "pendingRefferal": 2,
      "approvedRefferal": 5,
      "maximumEarning": 50000,
      "minimumEarning": 10000,
      "actualEarning": 25000
    },
    {
      "yearMonth": "2026-01",
      "pendingRefferal": 0,
      "approvedRefferal": 3,
      "maximumEarning": 30000,
      "minimumEarning": 5000,
      "actualEarning": 15000
    }
  ]
}
```

---

## API Workflow Diagrams

### Complete Purchase Flow

```
[Customer Browses]
        |
        v
GET /store/listing/{url}  -----> Browse product catalog
        |
        v
GET /store/entity/{id}  -------> View product details
        |
        v
POST /store/cart  --------------> Add items to cart (validates inventory)
        |
        v
GET /store/otp/generateOTP  ---> Generate OTP for login
POST /store/signin  ------------> Authenticate
        |
        v
POST /store/confirmOrder  -----> Place order
        |
        v
GET /store/order  --------------> Track order status
        |
        v
GET /store/generateInvoice  ---> Download invoice PDF
```

### Partner (B2B) Order Flow

```
[Partner Login]
        |
        v
POST /user/google-login  ------> Authenticate & get JWT
        |
        v
GET /user/detail  --------------> Load user profile
        |
        v
GET /store/partnerStock  -------> Browse available stock
GET /store/brands  -------------> Filter by brands
        |
        v
POST /cart  ---------------------> Add items to cart
        |
        v
GET /wallet/my-wallet  ---------> Check wallet balance
GET /getPaymentOptions  --------> View payment methods
        |
        v
GET /order/create  --------------> Create order (payment gateway redirect)
        |
        v
GET /order/all  -----------------> View order history
GET /order/orderAll/{status}/{month}  --> Filter orders
        |
        v
GET /order/generateInvoice  ----> Download invoice
```

### Wallet Top-up Flow

```
[Partner Dashboard]
        |
        v
GET /wallet/my-wallet  ---------> Check current balance
        |
        +---------- Option A: Bank Transfer ----------+
        |                                              |
        v                                              v
POST /wallet/add-money  ------> Submit UTR details     |
        |                       (Status: Pending)      |
        v                                              |
GET /wallet/add-money-history --> Track request status  |
        |                                              |
        +---------- Option B: Online Payment ----------+
        |                                              |
        v                                              v
GET /getPaymentOptions  -------> Choose gateway        |
        |                                              |
        v                                              |
GET /wallet/add-via-loan  -----> Get payment form      |
        |                       (Redirect to gateway)  |
        v                                              |
GET /wallet/my-wallet  ---------> Verify updated balance
```

---

## Error Handling

All API errors follow a consistent pattern using `ProfitMandiBusinessException`:

**Error Response Structure:**
```json
{
  "field": "Transaction Reference (UTR)",
  "value": "UTR123456789",
  "message": "Already added"
}
```

**Common HTTP Status Codes:**

| Code | Description |
|------|-------------|
| 200 | Success |
| 400 | Bad Request (validation errors, business rule violations) |
| 403 | Forbidden (invalid or expired Auth-Token) |
| 500 | Internal Server Error |

---

## Authentication Notes

- **Header Name:** `Auth-Token`
- **Token Format:** JWT (JSON Web Token)
- **Token Source:** Returned by `/user/google-login` or `/user/token/unregistered`
- **Expiry Check:** `GET /user/token/isExpired?token={jwt_token}` returns `true/false`
- **User Context:** The JWT token is decoded server-side to populate `userId` and `userInfo` as request attributes, which are used by all authenticated endpoints.