Subversion Repositories SmartDukaan

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
35844 vikas 1 
# ProfitMandi Web - API Workflow Documentation
2 
 
3 
> **Base Technology:** Spring Boot (Java)
4 
> **Authentication:** JWT Bearer Token via `Auth-Token` request header
5 
> **Response Format:** JSON (`application/json`)
6 
> **Response Wrapper:** All responses are wrapped in `ResponseEntity<?>` using `ResponseSender` utility
7 
 
8 
---
9 
 
10 
## Table of Contents
11 
 
12 
1. [Authentication & User Management](#1-authentication--user-management)
13 
2. [Store & Product Catalog](#2-store--product-catalog)
14 
3. [Cart & Checkout](#3-cart--checkout)
15 
4. [Order Management](#4-order-management)
16 
5. [Wallet & Payments](#5-wallet--payments)
17 
6. [Lead & Partner Management](#6-lead--partner-management)
18 
 
19 
---
20 
 
21 
## 1. Authentication & User Management
22 
 
23 
### 1.1 Google Login / Email Login
24 
 
25 
| Field | Value |
26 
|-------|-------|
27 
| **URL** | `POST /user/google-login` |
28 
| **Auth Required** | No |
29 
 
30 
**Request Body:**
31 
```json
32 
{
33 
  "email": "user@example.com",
34 
  "token": "google_oauth_token",
35 
  "password": "optional_password"
36 
}
37 
```
38 
 
39 
**Response (200 OK):**
40 
```json
41 
{
42 
  "token": "jwt_token_string",
43 
  "registered": true,
44 
  "userStatus": "ACTIVE",
45 
  "email": "user@example.com"
46 
}
47 
```
48 
 
49 
**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.
50 
 
51 
---
52 
 
53 
### 1.2 Get Unregistered User Token
54 
 
55 
| Field | Value |
56 
|-------|-------|
57 
| **URL** | `GET /user/token/unregistered` |
58 
| **Auth Required** | No |
59 
 
60 
**Request:** No parameters required.
61 
 
62 
**Response (200 OK):**
63 
```json
64 
{
65 
  "token": "jwt_token_for_guest",
66 
  "registered": false
67 
}
68 
```
69 
 
70 
**Workflow:** Generates a temporary guest token for unauthenticated users to browse the catalog and add items to cart before registration.
71 
 
72 
---
73 
 
74 
### 1.3 Get User Details (Authenticated)
75 
 
76 
| Field | Value |
77 
|-------|-------|
78 
| **URL** | `GET /user/detail` |
79 
| **Auth Required** | Yes (`Auth-Token` header) |
80 
 
81 
**Request:** No parameters. Auth token identifies the user.
82 
 
83 
**Response (200 OK):**
84 
```json
85 
{
86 
  "userId": 1234,
87 
  "userName": "John Doe",
88 
  "emailId": "john@example.com",
89 
  "userStatus": "REGISTERED",
90 
  "address": {
91 
    "line1": "123 Main St",
92 
    "city": "Delhi",
93 
    "state": "Delhi",
94 
    "pin": "110001"
95 
  },
96 
  "storeUrl": "/stores/delhi/new-delhi/SD1234",
97 
  "timelineStatus": "ACTIVE",
98 
  "fofoTrialEndDate": "2026-03-31",
99 
  "userInfo": { ... }
100 
}
101 
```
102 
 
103 
**Workflow:** Called after login to fetch the authenticated user's full profile including retailer/FOFO store details, address, and onboarding status.
104 
 
105 
---
106 
 
107 
### 1.4 Create New User
108 
 
109 
| Field | Value |
110 
|-------|-------|
111 
| **URL** | `POST /user` |
112 
| **Auth Required** | Yes (`Auth-Token` header) |
113 
 
114 
**Request Body:**
115 
```json
116 
{
117 
  "firstName": "John",
118 
  "lastName": "Doe",
119 
  "emailId": "john@example.com",
120 
  "mobieNumber": "9876543210",
121 
  "city": "Delhi",
122 
  "pinCode": "110001",
123 
  "state": "Delhi"
124 
}
125 
```
126 
 
127 
**Response (200 OK):**
128 
```json
129 
{
130 
  "message": "User created successfully"
131 
}
132 
```
133 
 
134 
---
135 
 
136 
### 1.5 Forgot Password
137 
 
138 
| Field | Value |
139 
|-------|-------|
140 
| **URL** | `POST /user/forgot-password` |
141 
| **Auth Required** | No |
142 
 
143 
**Request Body:**
144 
```json
145 
{
146 
  "email": "user@example.com"
147 
}
148 
```
149 
 
150 
**Response (200 OK):**
151 
```json
152 
true
153 
```
154 
 
155 
**Workflow:** Sends a password reset email to the registered email address.
156 
 
157 
---
158 
 
159 
### 1.6 Change Password
160 
 
161 
| Field | Value |
162 
|-------|-------|
163 
| **URL** | `POST /user/change-password` |
164 
| **Auth Required** | No |
165 
 
166 
**Request Body:**
167 
```json
168 
{
169 
  "email": "user@example.com",
170 
  "password": "current_password",
171 
  "newPassword": "new_password"
172 
}
173 
```
174 
 
175 
**Response (200 OK):**
176 
```json
177 
true
178 
```
179 
 
180 
---
181 
 
182 
## 2. Store & Product Catalog
183 
 
184 
### 2.1 Get Product/Entity Details
185 
 
186 
| Field | Value |
187 
|-------|-------|
188 
| **URL** | `GET /store/entity/{id}` |
189 
| **Auth Required** | Yes (`Auth-Token` header) |
190 
 
191 
**Path Parameters:**
192 
 
193 
| Parameter | Type | Description |
194 
|-----------|------|-------------|
195 
| `id` | long | Catalog item ID |
196 
 
197 
**Response (200 OK):**
198 
```json
199 
{
200 
  "catalogId": 5678,
201 
  "itemName": "Samsung Galaxy M14",
202 
  "brand": "Samsung",
203 
  "category": "Smartphones",
204 
  "mrp": 15999.00,
205 
  "dp": 12500.00,
206 
  "sellingPrice": 13999.00,
207 
  "imageUrl": "https://cdn.example.com/img/product.jpg",
208 
  "inStock": true,
209 
  "specs": { ... },
210 
  "availableQuantity": 25,
211 
  "color": "Blue"
212 
}
213 
```
214 
 
215 
**Workflow:** Fetches detailed product information including pricing, availability, and specifications for a catalog item.
216 
 
217 
---
218 
 
219 
### 2.2 Get Brands by Category
220 
 
221 
| Field | Value |
222 
|-------|-------|
223 
| **URL** | `GET /store/brands` |
224 
| **Auth Required** | Yes (`Auth-Token` header) |
225 
 
226 
**Query Parameters:**
227 
 
228 
| Parameter | Type | Required | Description |
229 
|-----------|------|----------|-------------|
230 
| `category_id` | String | Yes | Category ID to filter brands |
231 
 
232 
**Response (200 OK):**
233 
```json
234 
[
235 
  {
236 
    "brandId": 1,
237 
    "brandName": "Samsung",
238 
    "count": 45
239 
  },
240 
  {
241 
    "brandId": 2,
242 
    "brandName": "Apple",
243 
    "count": 30
244 
  }
245 
]
246 
```
247 
 
248 
---
249 
 
250 
### 2.3 Get Product Listings
251 
 
252 
| Field | Value |
253 
|-------|-------|
254 
| **URL** | `GET /store/listing/{listingUrl}` |
255 
| **Auth Required** | No |
256 
 
257 
**Path Parameters:**
258 
 
259 
| Parameter | Type | Description |
260 
|-----------|------|-------------|
261 
| `listingUrl` | String | URL slug for the listing (e.g., "best-sellers") |
262 
 
263 
**Response (200 OK):**
264 
```json
265 
{
266 
  "listingName": "Best Sellers",
267 
  "fofoCatalogResponses": [
268 
    {
269 
      "catalogId": 5678,
270 
      "itemName": "Samsung Galaxy M14",
271 
      "brand": "Samsung",
272 
      "mrp": 15999.00,
273 
      "dp": 12500.00,
274 
      "imageUrl": "https://cdn.example.com/img/product.jpg",
275 
      "inStock": true
276 
    }
277 
  ]
278 
}
279 
```
280 
 
281 
---
282 
 
283 
### 2.4 Get Partner Stock
284 
 
285 
| Field | Value |
286 
|-------|-------|
287 
| **URL** | `GET /store/partnerStock` |
288 
| **Auth Required** | Yes (`Auth-Token` header) |
289 
 
290 
**Query Parameters:**
291 
 
292 
| Parameter | Type | Default | Description |
293 
|-----------|------|---------|-------------|
294 
| `categoryId` | String | "3" | Category ID |
295 
| `offset` | int | required | Pagination offset |
296 
| `limit` | int | required | Page size |
297 
| `sort` | String | optional | Sort field |
298 
| `brand` | String | optional | Brand filter |
299 
| `subCategoryId` | int | optional | Sub-category filter |
300 
| `queryTerm` | String | optional | Search term |
301 
| `partnerStockOnly` | boolean | true | Show only partner's stock |
302 
 
303 
**Response (200 OK):**
304 
```json
305 
[
306 
  {
307 
    "catalogId": 5678,
308 
    "itemName": "Samsung Galaxy M14",
309 
    "brand": "Samsung",
310 
    "mrp": 15999.00,
311 
    "dp": 12500.00,
312 
    "availableQuantity": 10,
313 
    "imageUrl": "https://cdn.example.com/img/product.jpg"
314 
  }
315 
]
316 
```
317 
 
318 
---
319 
 
320 
### 2.5 Check Mobile Registration / Get Customer
321 
 
322 
| Field | Value |
323 
|-------|-------|
324 
| **URL** | `GET /store/checkmobile/{mobile}` |
325 
| **Auth Required** | No |
326 
 
327 
**Path Parameters:**
328 
 
329 
| Parameter | Type | Description |
330 
|-----------|------|-------------|
331 
| `mobile` | String | Mobile number to check |
332 
 
333 
**Query Parameters:**
334 
 
335 
| Parameter | Type | Default | Description |
336 
|-----------|------|---------|-------------|
337 
| `isSmartSeller` | boolean | false | Whether user is a smart seller |
338 
 
339 
**Response (200 OK):**
340 
```json
341 
{
342 
  "customer": {
343 
    "id": 100,
344 
    "firstName": "John",
345 
    "lastName": "Doe",
346 
    "mobile": "9876543210",
347 
    "email": "john@example.com",
348 
    "passwordExists": true
349 
  },
350 
  "exists": true
351 
}
352 
```
353 
 
354 
---
355 
 
356 
### 2.6 Store Customer Registration
357 
 
358 
| Field | Value |
359 
|-------|-------|
360 
| **URL** | `POST /store/register` |
361 
| **Auth Required** | No |
362 
 
363 
**Request Body:**
364 
```json
365 
{
366 
  "mobile": "9876543210",
367 
  "password": "secure_password",
368 
  "email": "john@example.com",
369 
  "firstName": "John",
370 
  "lastName": "Doe",
371 
  "isSmartSeller": false,
372 
  "referralCode": "REF123"
373 
}
374 
```
375 
 
376 
**Response (200 OK):**
377 
```json
378 
{
379 
  "id": 100,
380 
  "firstName": "John",
381 
  "lastName": "Doe",
382 
  "mobile": "9876543210",
383 
  "email": "john@example.com"
384 
}
385 
```
386 
 
387 
**Workflow:** Registers a new customer. For smart sellers, handles referral rewards and sends welcome email.
388 
 
389 
---
390 
 
391 
### 2.7 Store Customer Sign In
392 
 
393 
| Field | Value |
394 
|-------|-------|
395 
| **URL** | `POST /store/signin` |
396 
| **Auth Required** | No |
397 
 
398 
**Request Body:**
399 
```json
400 
{
401 
  "mobile": "9876543210",
402 
  "password": "user_password"
403 
}
404 
```
405 
 
406 
**Response (200 OK):**
407 
```json
408 
true
409 
```
410 
 
411 
---
412 
 
413 
### 2.8 Generate OTP
414 
 
415 
| Field | Value |
416 
|-------|-------|
417 
| **URL** | `GET /store/otp/generateOTP` |
418 
| **Auth Required** | No |
419 
 
420 
**Query Parameters:**
421 
 
422 
| Parameter | Type | Required | Description |
423 
|-----------|------|----------|-------------|
424 
| `mobile` | String | Yes | Mobile number to send OTP |
425 
 
426 
**Response (200 OK):**
427 
```json
428 
{
429 
  "referenceId": "abc123",
430 
  "status": "success"
431 
}
432 
```
433 
 
434 
---
435 
 
436 
## 3. Cart & Checkout
437 
 
438 
### 3.1 Add Items to Cart (Validate Cart)
439 
 
440 
| Field | Value |
441 
|-------|-------|
442 
| **URL** | `POST /cart` |
443 
| **Auth Required** | Yes (`Auth-Token` header) |
444 
 
445 
**Query Parameters:**
446 
 
447 
| Parameter | Type | Default | Description |
448 
|-----------|------|---------|-------------|
449 
| `pincode` | String | "110001" | Delivery pincode |
450 
 
451 
**Request Body:**
452 
```json
453 
{
454 
  "cartItems": [
455 
    {
456 
      "itemId": 5678,
457 
      "quantity": 2
458 
    },
459 
    {
460 
      "itemId": 9012,
461 
      "quantity": 1
462 
    }
463 
  ]
464 
}
465 
```
466 
 
467 
**Response (200 OK):**
468 
```json
469 
{
470 
  "cartResponse": {
471 
    "cartItems": [
472 
      {
473 
        "itemId": 5678,
474 
        "quantity": 2,
475 
        "sellingPrice": 13999.00,
476 
        "maxQuantity": 5,
477 
        "estimate": 3,
478 
        "promiseDelivery": "2026-02-28",
479 
        "imageUrl": "https://cdn.example.com/img/product.jpg",
480 
        "color": "Blue"
481 
      }
482 
    ],
483 
    "cartMessages": [],
484 
    "totalAmount": 27998,
485 
    "totalQty": 3,
486 
    "maxEstimate": 5
487 
  },
488 
  "response": "Success",
489 
  "message": "Items added to cart successfully"
490 
}
491 
```
492 
 
493 
**Workflow:** Validates cart items against inventory (store + warehouse), applies cashback/schemes, adjusts quantities based on availability, and returns delivery estimates.
494 
 
495 
---
496 
 
497 
### 3.2 Get Cart from Bucket
498 
 
499 
| Field | Value |
500 
|-------|-------|
501 
| **URL** | `GET /cart` |
502 
| **Auth Required** | Yes (`Auth-Token` header) |
503 
 
504 
**Query Parameters:**
505 
 
506 
| Parameter | Type | Default | Description |
507 
|-----------|------|---------|-------------|
508 
| `pincode` | String | "110001" | Delivery pincode |
509 
| `bucketId` | int | required | Bucket/cart ID |
510 
 
511 
**Response:** Same structure as `POST /cart` response above.
512 
 
513 
---
514 
 
515 
### 3.3 Change Delivery Address
516 
 
517 
| Field | Value |
518 
|-------|-------|
519 
| **URL** | `POST /cart/change-address` |
520 
| **Auth Required** | Yes (`Auth-Token` header) |
521 
 
522 
**Query Parameters:**
523 
 
524 
| Parameter | Type | Required | Description |
525 
|-----------|------|----------|-------------|
526 
| `addressId` | long | Yes | New delivery address ID |
527 
 
528 
**Response (200 OK):**
529 
```json
530 
"Address Changed successfully"
531 
```
532 
 
533 
---
534 
 
535 
### 3.4 Store Cart (Customer-Facing)
536 
 
537 
| Field | Value |
538 
|-------|-------|
539 
| **URL** | `POST /store/cart` |
540 
| **Auth Required** | Yes (`Auth-Token` header) |
541 
 
542 
**Request Body:**
543 
```json
544 
{
545 
  "cartItems": [
546 
    {
547 
      "itemId": 5678,
548 
      "quantity": 1,
549 
      "sellingPrice": 13999.00,
550 
      "smartSellerId": "SS001",
551 
      "pendingOrderItemPolicyPlan": null
552 
    }
553 
  ]
554 
}
555 
```
556 
 
557 
**Response (200 OK):**
558 
```json
559 
{
560 
  "cartResponse": {
561 
    "cartItems": [ ... ],
562 
    "cartMessages": [],
563 
    "totalAmount": 13999,
564 
    "totalQty": 1
565 
  },
566 
  "message": "Cart validated",
567 
  "description": ""
568 
}
569 
```
570 
 
571 
---
572 
 
573 
## 4. Order Management
574 
 
575 
### 4.1 Create Order from Cart
576 
 
577 
| Field | Value |
578 
|-------|-------|
579 
| **URL** | `GET /order/create` |
580 
| **Auth Required** | Yes (`Auth-Token` header) |
581 
 
582 
**Query Parameters:**
583 
 
584 
| Parameter | Type | Default | Description |
585 
|-----------|------|---------|-------------|
586 
| `paymentOption` | String | required | Payment method selection |
587 
| `walletUsed` | double | required | Amount deducted from wallet |
588 
| `selfPickup` | boolean | false | Whether customer picks up from store |
589 
| `freeCreditDays` | int | 0 | Free credit period in days |
590 
 
591 
**Response (200 OK):**
592 
```json
593 
{
594 
  "gatewayUrl": "https://payment-gateway.com/pay",
595 
  "postParams": { ... },
596 
  "paymentId": 78901
597 
}
598 
```
599 
 
600 
**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.
601 
 
602 
---
603 
 
604 
### 4.2 Confirm Store Order
605 
 
606 
| Field | Value |
607 
|-------|-------|
608 
| **URL** | `POST /store/confirmOrder` |
609 
| **Auth Required** | Yes (`Auth-Token` header) |
610 
 
611 
**Request Body:**
612 
```json
613 
{
614 
  "createPendingOrderItem": [
615 
    {
616 
      "itemId": 5678,
617 
      "quantity": 1,
618 
      "sellingPrice": 13999.00,
619 
      "smartSellerId": "SS001",
620 
      "pendingOrderItemPolicyPlan": {
621 
        "planId": 10,
622 
        "planAmount": 499.00
623 
      }
624 
    }
625 
  ],
626 
  "totalAmount": 14498
627 
}
628 
```
629 
 
630 
**Response (200 OK):**
631 
```json
632 
{
633 
  "poId": "PO-20260224-001"
634 
}
635 
```
636 
 
637 
**Workflow:** Creates a pending order from the customer-facing store. Validates inventory, sends order confirmation email/SMS, and notifies partners.
638 
 
639 
---
640 
 
641 
### 4.3 Get All Orders (Paginated)
642 
 
643 
| Field | Value |
644 
|-------|-------|
645 
| **URL** | `GET /order/all` |
646 
| **Auth Required** | Yes (`Auth-Token` header) |
647 
 
648 
**Query Parameters:**
649 
 
650 
| Parameter | Type | Default | Description |
651 
|-----------|------|---------|-------------|
652 
| `offset` | int | 0 | Pagination offset |
653 
| `limit` | int | 20 | Page size |
654 
 
655 
**Response (200 OK):**
656 
```json
657 
[
658 
  {
659 
    "orderId": 12345,
660 
    "unitPrice": "13999.00",
661 
    "totalAmount": "13999.00",
662 
    "itemName": "Samsung Galaxy M14",
663 
    "quantity": 1,
664 
    "itemId": 5678,
665 
    "orderedOn": "2026-02-24",
666 
    "promisedDelivery": "2026-02-28",
667 
    "status": "CONFIRMED",
668 
    "courierName": "Delhivery",
669 
    "awbNumber": "AWB123456",
670 
    "isCancellable": true,
671 
    "color": "Blue",
672 
    "shippingAddress": {
673 
      "addressId": "1",
674 
      "name": "John Doe",
675 
      "line1": "123 Main St",
676 
      "city": "Delhi",
677 
      "state": "Delhi",
678 
      "pin": "110001",
679 
      "phone": "9876543210"
680 
    }
681 
  }
682 
]
683 
```
684 
 
685 
---
686 
 
687 
### 4.4 Get Orders by Status and Month
688 
 
689 
| Field | Value |
690 
|-------|-------|
691 
| **URL** | `GET /order/orderAll/{status}/{yearMonth}` |
692 
| **Auth Required** | Yes (`Auth-Token` header) |
693 
 
694 
**Path Parameters:**
695 
 
696 
| Parameter | Type | Description |
697 
|-----------|------|-------------|
698 
| `status` | OrderStatus | Order status enum (e.g., CONFIRMED, DELIVERED, CANCELLED) |
699 
| `yearMonth` | YearMonth | Year-month in `YYYY-MM` format |
700 
 
701 
**Response (200 OK):**
702 
```json
703 
[
704 
  {
705 
    "orderId": 12345,
706 
    "itemName": "Samsung Galaxy M14",
707 
    "status": "DELIVERED",
708 
    "totalAmount": "13999.00",
709 
    "orderedOn": "2026-02-10"
710 
  }
711 
]
712 
```
713 
 
714 
---
715 
 
716 
### 4.5 Cancel Order (Partner)
717 
 
718 
| Field | Value |
719 
|-------|-------|
720 
| **URL** | `POST /partnerCancelOrder` |
721 
| **Auth Required** | Yes (`Auth-Token` header) |
722 
 
723 
**Query Parameters:**
724 
 
725 
| Parameter | Type | Required | Description |
726 
|-----------|------|----------|-------------|
727 
| `orderId` | int | Yes | Order ID to cancel |
728 
| `reason` | String | Yes | Cancellation reason |
729 
 
730 
**Response (200 OK):**
731 
```json
732 
true
733 
```
734 
 
735 
---
736 
 
737 
### 4.6 Search Items
738 
 
739 
| Field | Value |
740 
|-------|-------|
741 
| **URL** | `GET /item` |
742 
| **Auth Required** | Yes (`Auth-Token` header) |
743 
 
744 
**Query Parameters:**
745 
 
746 
| Parameter | Type | Required | Description |
747 
|-----------|------|----------|-------------|
748 
| `query` | String | Yes | Search keyword |
749 
 
750 
**Response (200 OK):**
751 
```json
752 
[
753 
  {
754 
    "itemId": 5678,
755 
    "itemName": "Samsung Galaxy M14",
756 
    "brand": "Samsung",
757 
    "imei": "352456789012345",
758 
    "mrp": 15999.00,
759 
    "dp": 12500.00
760 
  }
761 
]
762 
```
763 
 
764 
---
765 
 
766 
### 4.7 Check Item Availability
767 
 
768 
| Field | Value |
769 
|-------|-------|
770 
| **URL** | `GET /checkItemAvailability` |
771 
| **Auth Required** | Yes (`Auth-Token` header) |
772 
 
773 
**Query Parameters:**
774 
 
775 
| Parameter | Type | Required | Description |
776 
|-----------|------|----------|-------------|
777 
| `itemId` | int | Yes | Catalog item ID |
778 
 
779 
**Response (200 OK):**
780 
```json
781 
{
782 
  "itemId": 5678,
783 
  "availableQuantity": 15,
784 
  "warehouseStock": 10,
785 
  "storeStock": 5,
786 
  "lastUpdated": "2026-02-24T10:30:00"
787 
}
788 
```
789 
 
790 
---
791 
 
792 
### 4.8 Generate Invoice PDF
793 
 
794 
| Field | Value |
795 
|-------|-------|
796 
| **URL** | `GET /order/generateInvoice` |
797 
| **Auth Required** | No |
798 
 
799 
**Query Parameters:**
800 
 
801 
| Parameter | Type | Required | Description |
802 
|-----------|------|----------|-------------|
803 
| `invoiceNumber` | String | Yes | Invoice number |
804 
 
805 
**Response:** Returns a PDF file.
806 
 
807 
| Header | Value |
808 
|--------|-------|
809 
| Content-Type | `application/pdf` |
810 
| Content-Disposition | `inline; filename=invoice-{invoiceNumber}.pdf` |
811 
 
812 
---
813 
 
814 
## 5. Wallet & Payments
815 
 
816 
### 5.1 Get Wallet Balance
817 
 
818 
| Field | Value |
819 
|-------|-------|
820 
| **URL** | `GET /wallet/my-wallet` |
821 
| **Auth Required** | Yes (`Auth-Token` header) |
822 
 
823 
**Request:** No parameters.
824 
 
825 
**Response (200 OK):**
826 
```json
827 
{
828 
  "walletId": 456,
829 
  "balance": 25000.00,
830 
  "currency": "INR",
831 
  "retailerId": 789
832 
}
833 
```
834 
 
835 
---
836 
 
837 
### 5.2 Get Wallet Transaction History
838 
 
839 
| Field | Value |
840 
|-------|-------|
841 
| **URL** | `GET /wallet/my-wallet-history` |
842 
| **Auth Required** | Yes (`Auth-Token` header) |
843 
 
844 
**Request:** No parameters. Returns up to 150 recent transactions.
845 
 
846 
**Response (200 OK):**
847 
```json
848 
[
849 
  {
850 
    "transactionId": 1001,
851 
    "amount": 5000.00,
852 
    "type": "CREDIT",
853 
    "description": "Order refund #12345",
854 
    "timestamp": "2026-02-24T14:30:00",
855 
    "balance": 25000.00
856 
  },
857 
  {
858 
    "transactionId": 1000,
859 
    "amount": -13999.00,
860 
    "type": "DEBIT",
861 
    "description": "Order payment #12344",
862 
    "timestamp": "2026-02-23T10:00:00",
863 
    "balance": 20000.00
864 
  }
865 
]
866 
```
867 
 
868 
---
869 
 
870 
### 5.3 Add Money to Wallet (Bank Transfer)
871 
 
872 
| Field | Value |
873 
|-------|-------|
874 
| **URL** | `POST /wallet/add-money` |
875 
| **Auth Required** | Yes (`Auth-Token` header) |
876 
 
877 
**Request Body:**
878 
```json
879 
{
880 
  "transaction_reference": "UTR123456789",
881 
  "amount": 50000.00,
882 
  "reference_date": "2026-02-24",
883 
  "bank_name": "HDFC Bank"
884 
}
885 
```
886 
 
887 
**Response (200 OK):**
888 
```json
889 
true
890 
```
891 
 
892 
**Error Response (400 Bad Request):**
893 
```json
894 
{
895 
  "error": "Transaction Reference (UTR) UTR123456789 Already added"
896 
}
897 
```
898 
 
899 
**Workflow:** Creates a pending wallet top-up request via bank transfer. The request is verified and approved internally. Duplicate UTR numbers are rejected.
900 
 
901 
---
902 
 
903 
### 5.4 Add Money via Payment Gateway (Loan)
904 
 
905 
| Field | Value |
906 
|-------|-------|
907 
| **URL** | `GET /wallet/add-via-loan` |
908 
| **Auth Required** | Yes (`Auth-Token` header) |
909 
 
910 
**Query Parameters:**
911 
 
912 
| Parameter | Type | Required | Description |
913 
|-----------|------|----------|-------------|
914 
| `loanAmount` | double | Yes | Amount to add |
915 
| `surcharge` | double | Yes | Gateway surcharge |
916 
| `payMethod` | String | Yes | Payment method (e.g., "CREDIT_CARD") |
917 
| `gateway` | Gateway | Yes | Payment gateway (e.g., "CCAVENUE") |
918 
 
919 
**Response (200 OK):**
920 
```json
921 
{
922 
  "merchant_id": "M12345",
923 
  "order_id": "ORD-789",
924 
  "amount": "50000.00",
925 
  "redirect_url": "https://example.com/callback",
926 
  "cancel_url": "https://example.com/cancel",
927 
  "enc_val": "encrypted_payment_data",
928 
  "access_code": "ACC123",
929 
  "status": "pending"
930 
}
931 
```
932 
 
933 
**Workflow:** Returns payment gateway form parameters. The frontend renders the payment form and redirects to the gateway (CCAvenue/PineLabs).
934 
 
935 
---
936 
 
937 
### 5.5 Get Add Money History
938 
 
939 
| Field | Value |
940 
|-------|-------|
941 
| **URL** | `GET /wallet/add-money-history` |
942 
| **Auth Required** | Yes (`Auth-Token` header) |
943 
 
944 
**Query Parameters:**
945 
 
946 
| Parameter | Type | Default | Description |
947 
|-----------|------|---------|-------------|
948 
| `offset` | int | 0 | Pagination offset |
949 
| `limit` | int | 10 | Page size |
950 
 
951 
**Response (200 OK):**
952 
```json
953 
[
954 
  {
955 
    "id": 101,
956 
    "retailerId": 789,
957 
    "amount": 50000.00,
958 
    "transaction_reference": "UTR123456789",
959 
    "reference_date": "2026-02-24",
960 
    "bank_name": "HDFC Bank",
961 
    "status": "approved"
962 
  }
963 
]
964 
```
965 
 
966 
---
967 
 
968 
### 5.6 Get Payment Options
969 
 
970 
| Field | Value |
971 
|-------|-------|
972 
| **URL** | `GET /getPaymentOptions` |
973 
| **Auth Required** | No |
974 
 
975 
**Request:** No parameters.
976 
 
977 
**Response (200 OK):**
978 
```json
979 
{
980 
  "CCAVENUE": [
981 
    {
982 
      "paymentMethod": "CREDIT_CARD",
983 
      "paymentMethodDescription": "Credit Card",
984 
      "surcharge": 1.5
985 
    },
986 
    {
987 
      "paymentMethod": "NET_BANKING",
988 
      "paymentMethodDescription": "Net Banking",
989 
      "surcharge": 0.75
990 
    }
991 
  ],
992 
  "PINELABS": [
993 
    {
994 
      "paymentMethod": "UPI",
995 
      "paymentMethodDescription": "UPI Payment",
996 
      "surcharge": 0
997 
    }
998 
  ]
999 
}
1000 
```
1001 
 
1002 
---
1003 
 
1004 
## 6. Lead & Partner Management
1005 
 
1006 
### 6.1 Create / Update Lead
1007 
 
1008 
| Field | Value |
1009 
|-------|-------|
1010 
| **URL** | `POST /lead` |
1011 
| **Auth Required** | Yes (`Auth-Token` header) |
1012 
 
1013 
**Request Body:**
1014 
```json
1015 
{
1016 
  "firstName": "Jane",
1017 
  "lastName": "Smith",
1018 
  "mobile": "9876543210",
1019 
  "state": "Maharashtra",
1020 
  "city": "Mumbai",
1021 
  "address": "456 Park Avenue",
1022 
  "outletName": "Jane Electronics",
1023 
  "potential": "HIGH",
1024 
  "status": "NEW",
1025 
  "source": "REFERRAL",
1026 
  "reason": "",
1027 
  "remark": "Interested in franchise",
1028 
  "schelduleTimestamp": "2026-03-01T10:00:00",
1029 
  "communicationType": "CALL"
1030 
}
1031 
```
1032 
 
1033 
**Response (200 OK):**
1034 
```json
1035 
true
1036 
```
1037 
 
1038 
---
1039 
 
1040 
### 6.2 Get Leads by Status
1041 
 
1042 
| Field | Value |
1043 
|-------|-------|
1044 
| **URL** | `GET /lead-description` |
1045 
| **Auth Required** | Yes (`Auth-Token` header) |
1046 
 
1047 
**Query Parameters:**
1048 
 
1049 
| Parameter | Type | Required | Description |
1050 
|-----------|------|----------|-------------|
1051 
| `gmailId` | String | Yes | User's email ID |
1052 
| `status` | String | Yes | Lead status filter |
1053 
 
1054 
**Response (200 OK):**
1055 
```json
1056 
[
1057 
  {
1058 
    "leadId": 201,
1059 
    "firstName": "Jane",
1060 
    "lastName": "Smith",
1061 
    "mobile": "9876543210",
1062 
    "city": "Mumbai",
1063 
    "state": "Maharashtra",
1064 
    "status": "NEW",
1065 
    "potential": "HIGH",
1066 
    "createdDate": "2026-02-20"
1067 
  }
1068 
]
1069 
```
1070 
 
1071 
---
1072 
 
1073 
### 6.3 Create Referral
1074 
 
1075 
| Field | Value |
1076 
|-------|-------|
1077 
| **URL** | `POST /user/refferal` |
1078 
| **Auth Required** | Yes (`Auth-Token` header) |
1079 
 
1080 
**Request Body:**
1081 
```json
1082 
{
1083 
  "firstName": "Mike",
1084 
  "lastName": "Wilson",
1085 
  "mobile": "9123456789",
1086 
  "state": "Karnataka",
1087 
  "city": "Bangalore",
1088 
  "isFofoAssociate": true,
1089 
  "refereeEmail": "referee@example.com"
1090 
}
1091 
```
1092 
 
1093 
**Response (200 OK):**
1094 
```json
1095 
true
1096 
```
1097 
 
1098 
---
1099 
 
1100 
### 6.4 Get Referral Earnings
1101 
 
1102 
| Field | Value |
1103 
|-------|-------|
1104 
| **URL** | `GET /user/refferalAmount` |
1105 
| **Auth Required** | Yes (`Auth-Token` header) |
1106 
 
1107 
**Query Parameters:**
1108 
 
1109 
| Parameter | Type | Required | Description |
1110 
|-----------|------|----------|-------------|
1111 
| `refereeEmail` | String | Yes | Referee's email |
1112 
 
1113 
**Response (200 OK):**
1114 
```json
1115 
{
1116 
  "timestamp": "2026-02-24T10:00:00",
1117 
  "refferalEarningModel": [
1118 
    {
1119 
      "yearMonth": "2026-02",
1120 
      "pendingRefferal": 2,
1121 
      "approvedRefferal": 5,
1122 
      "maximumEarning": 50000,
1123 
      "minimumEarning": 10000,
1124 
      "actualEarning": 25000
1125 
    },
1126 
    {
1127 
      "yearMonth": "2026-01",
1128 
      "pendingRefferal": 0,
1129 
      "approvedRefferal": 3,
1130 
      "maximumEarning": 30000,
1131 
      "minimumEarning": 5000,
1132 
      "actualEarning": 15000
1133 
    }
1134 
  ]
1135 
}
1136 
```
1137 
 
1138 
---
1139 
 
1140 
## API Workflow Diagrams
1141 
 
1142 
### Complete Purchase Flow
1143 
 
1144 
```
1145 
[Customer Browses]
1146 
        |
1147 
        v
1148 
GET /store/listing/{url}  -----> Browse product catalog
1149 
        |
1150 
        v
1151 
GET /store/entity/{id}  -------> View product details
1152 
        |
1153 
        v
1154 
POST /store/cart  --------------> Add items to cart (validates inventory)
1155 
        |
1156 
        v
1157 
GET /store/otp/generateOTP  ---> Generate OTP for login
1158 
POST /store/signin  ------------> Authenticate
1159 
        |
1160 
        v
1161 
POST /store/confirmOrder  -----> Place order
1162 
        |
1163 
        v
1164 
GET /store/order  --------------> Track order status
1165 
        |
1166 
        v
1167 
GET /store/generateInvoice  ---> Download invoice PDF
1168 
```
1169 
 
1170 
### Partner (B2B) Order Flow
1171 
 
1172 
```
1173 
[Partner Login]
1174 
        |
1175 
        v
1176 
POST /user/google-login  ------> Authenticate & get JWT
1177 
        |
1178 
        v
1179 
GET /user/detail  --------------> Load user profile
1180 
        |
1181 
        v
1182 
GET /store/partnerStock  -------> Browse available stock
1183 
GET /store/brands  -------------> Filter by brands
1184 
        |
1185 
        v
1186 
POST /cart  ---------------------> Add items to cart
1187 
        |
1188 
        v
1189 
GET /wallet/my-wallet  ---------> Check wallet balance
1190 
GET /getPaymentOptions  --------> View payment methods
1191 
        |
1192 
        v
1193 
GET /order/create  --------------> Create order (payment gateway redirect)
1194 
        |
1195 
        v
1196 
GET /order/all  -----------------> View order history
1197 
GET /order/orderAll/{status}/{month}  --> Filter orders
1198 
        |
1199 
        v
1200 
GET /order/generateInvoice  ----> Download invoice
1201 
```
1202 
 
1203 
### Wallet Top-up Flow
1204 
 
1205 
```
1206 
[Partner Dashboard]
1207 
        |
1208 
        v
1209 
GET /wallet/my-wallet  ---------> Check current balance
1210 
        |
1211 
        +---------- Option A: Bank Transfer ----------+
1212 
        |                                              |
1213 
        v                                              v
1214 
POST /wallet/add-money  ------> Submit UTR details     |
1215 
        |                       (Status: Pending)      |
1216 
        v                                              |
1217 
GET /wallet/add-money-history --> Track request status  |
1218 
        |                                              |
1219 
        +---------- Option B: Online Payment ----------+
1220 
        |                                              |
1221 
        v                                              v
1222 
GET /getPaymentOptions  -------> Choose gateway        |
1223 
        |                                              |
1224 
        v                                              |
1225 
GET /wallet/add-via-loan  -----> Get payment form      |
1226 
        |                       (Redirect to gateway)  |
1227 
        v                                              |
1228 
GET /wallet/my-wallet  ---------> Verify updated balance
1229 
```
1230 
 
1231 
---
1232 
 
1233 
## Error Handling
1234 
 
1235 
All API errors follow a consistent pattern using `ProfitMandiBusinessException`:
1236 
 
1237 
**Error Response Structure:**
1238 
```json
1239 
{
1240 
  "field": "Transaction Reference (UTR)",
1241 
  "value": "UTR123456789",
1242 
  "message": "Already added"
1243 
}
1244 
```
1245 
 
1246 
**Common HTTP Status Codes:**
1247 
 
1248 
| Code | Description |
1249 
|------|-------------|
1250 
| 200 | Success |
1251 
| 400 | Bad Request (validation errors, business rule violations) |
1252 
| 403 | Forbidden (invalid or expired Auth-Token) |
1253 
| 500 | Internal Server Error |
1254 
 
1255 
---
1256 
 
1257 
## Authentication Notes
1258 
 
1259 
- **Header Name:** `Auth-Token`
1260 
- **Token Format:** JWT (JSON Web Token)
1261 
- **Token Source:** Returned by `/user/google-login` or `/user/token/unregistered`
1262 
- **Expiry Check:** `GET /user/token/isExpired?token={jwt_token}` returns `true/false`
1263 
- **User Context:** The JWT token is decoded server-side to populate `userId` and `userInfo` as request attributes, which are used by all authenticated endpoints.