# Auth Service — v3 API Reference **Base URL:** `http://127.0.0.1:8000/v3/` **All POST / PATCH / DELETE bodies are JSON.** **Authenticated endpoints require:** `Authorization: Bearer ` --- ## 1. Centralised Login > Works for all roles: Buyer, Seller, Super Admin, Admin, Support Executive, Field Executive. > Identifier can be a **10-digit mobile number** or **email address**. > OTP is always `123456` in local / pre-production. --- ### 1.1 Send OTP ```bash curl -X POST http://127.0.0.1:8000/v3/auth/send-otp/ \ -H "Content-Type: application/json" \ -d '{ "identifier": "8658880453" }' ``` **With email:** ```bash curl -X POST http://127.0.0.1:8000/v3/auth/send-otp/ \ -H "Content-Type: application/json" \ -d '{ "identifier": "pratik@gmail.com" }' ``` --- ### 1.2 Verify OTP → Receive Tokens ```bash curl -X POST http://127.0.0.1:8000/v3/auth/verify-otp/ \ -H "Content-Type: application/json" \ -d '{ "identifier": "8658880453", "otp": "123456" }' ``` **With email:** ```bash curl -X POST http://127.0.0.1:8000/v3/auth/verify-otp/ \ -H "Content-Type: application/json" \ -d '{ "identifier": "pratik@gmail.com", "otp": "123456" }' ``` --- ### 1.3 Refresh Access Token ```bash curl -X POST http://127.0.0.1:8000/v3/auth/token/refresh/ \ -H "Content-Type: application/json" \ -d '{ "refresh_token": "" }' ``` --- ## 2. All Users > Accessible by **Super Admin** and **Admin**. --- ### 2.1 List All Users (basic) ```bash curl -X GET http://127.0.0.1:8000/v3/users/ \ -H "Authorization: Bearer " ``` ### 2.2 Universal Search ```bash curl -X GET "http://127.0.0.1:8000/v3/users/?search=john" \ -H "Authorization: Bearer " ``` > Searches across `full_name`, `email`, `mobile_number` (case-insensitive). ### 2.3 Filter by Role ```bash # Single role curl -X GET "http://127.0.0.1:8000/v3/users/?role_id=2" \ -H "Authorization: Bearer " # Multiple roles curl -X GET "http://127.0.0.1:8000/v3/users/?role_id=2,5" \ -H "Authorization: Bearer " ``` ### 2.4 Filter by Status ```bash # Active only curl -X GET "http://127.0.0.1:8000/v3/users/?status=1" \ -H "Authorization: Bearer " # Multiple statuses curl -X GET "http://127.0.0.1:8000/v3/users/?status=1,2" \ -H "Authorization: Bearer " ``` > Status values: `0`=Deleted, `1`=Active, `2`=Inactive, `3`=Blocked ### 2.5 Filter by Date Joined ```bash # Today curl -X GET "http://127.0.0.1:8000/v3/users/?date_filter=today" \ -H "Authorization: Bearer " # Yesterday curl -X GET "http://127.0.0.1:8000/v3/users/?date_filter=yesterday" \ -H "Authorization: Bearer " # Past 30 days curl -X GET "http://127.0.0.1:8000/v3/users/?date_filter=past_30_days" \ -H "Authorization: Bearer " # Custom date range curl -X GET "http://127.0.0.1:8000/v3/users/?date_filter=custom&date_from=2026-01-01&date_to=2026-03-31" \ -H "Authorization: Bearer " ``` ### 2.6 Filter by Gender ```bash curl -X GET "http://127.0.0.1:8000/v3/users/?gender=1" \ -H "Authorization: Bearer " ``` > Gender values: `1`=Male, `2`=Female, `3`=Other ### 2.7 Filter by Profile Completion ```bash curl -X GET "http://127.0.0.1:8000/v3/users/?is_profile_completed=true" \ -H "Authorization: Bearer " ``` ### 2.8 Combined Filters ```bash curl -X GET "http://127.0.0.1:8000/v3/users/?search=john&role_id=2&status=1&date_filter=past_30_days&page=1&page_size=10" \ -H "Authorization: Bearer " ``` ### 2.9 Force Refresh (bypass cache) ```bash curl -X GET "http://127.0.0.1:8000/v3/users/?refresh=1" \ -H "Authorization: Bearer " ``` > Busts the entire users cache, fetches fresh data from DB, re-caches it. > Use when you need guaranteed latest data (e.g. after a bulk operation). --- ### 2.10 Get User Detail (role-aware) ```bash curl -X GET http://127.0.0.1:8000/v3/users/101/ \ -H "Authorization: Bearer " ``` > Replace `101` with the target `user_id`. > Response shape changes based on the **target user's role** — see table below. | Target Role | Extra fields in response | |---|---| | Super Admin (1) | Base info only | | Admin (2) | `permissions[]` | | Seller (3) | `business_info`, `bank_info` (with document URLs) | | Buyer (4) | `buyer_profile`, `wallet` | | Field Executive (5) | `fe_profile` (KYC + bank with file URLs), `commission`, `wallet` | | Support (6) | `permissions[]` | | Store Manager (7) | Base info only | **Example response — Field Executive:** ```json { "status": true, "message": "User fetched successfully.", "data": { "id": 101, "full_name": "Ramesh Kumar", "mobile_number": "9876543210", "email": "ramesh@example.com", "role_id": 5, "role_name": "Field Executive", "status": 1, "status_label": "Active", "gender": 1, "gender_label": "Male", "image_url": "https://auth.neardelight.com/getImage?file=ProfileImage/...", "is_profile_completed": true, "is_email_verified": true, "is_mobile_verified": true, "referral_code": "FE123", "date_joined": "2026-01-15T10:00:00", "last_login": "2026-03-25T08:30:00", "fe_profile": { "id": 12, "executive_type": "individual", "organisation_name": null, "referral_code": "FE123", "joining_date": "2026-01-15", "is_kyc_verified": true, "kyc_verified_at": "2026-01-20T12:00:00", "is_bank_verified": true, "bank_verified_at": "2026-01-21T09:00:00", "status": true, "kyc_details": { "pan": { "number": "ABCDE1234F", "file_url": "https://auth.neardelight.com/getImage?file=..." }, "aadhar": { "number": "1234 5678 9012", "file_url": "https://auth.neardelight.com/getImage?file=..." }, "gst": { "number": "", "file_url": "" } }, "bank_details": { "holder_name": "Ramesh Kumar", "bank_name": "SBI", "branch_name": "MG Road", "account_number": "1234567890", "ifsc_code": "SBIN0001234", "cheque_passbook_url": "https://auth.neardelight.com/getImage?file=..." } }, "commission": { "daily_seller_order_charge": { "amount": "10.00", "effective_from": "2026-01-01", "is_fe_override": false }, "order_commission": { "amount": "1.00", "effective_from": "2026-01-01", "is_fe_override": false }, "onboarding_bonus": { "amount": "10.00", "effective_from": "2026-01-01", "is_fe_override": false } }, "wallet": { "balance": 250.00, "total_credited": 300.00, "total_debited": 50.00 } } } ``` **Example response — Seller:** ```json { "status": true, "message": "User fetched successfully.", "data": { "id": 55, "full_name": "Anita Store", "role_id": 3, "role_name": "Seller", "business_info": { "store_name": "Anita's Kitchen", "business_legal_name": "Anita Foods Pvt Ltd", "fssai_number": "12345678901234", "pan_number": "AAAPL1234C", "has_gst": true, "gst_number": "22AAAPL1234C1Z5", "city": "Mumbai", "state_name": "Maharashtra", "pincode": "400001", "store_logo": "https://auth.neardelight.com/getImage?file=...", "pan_card_doc": "https://auth.neardelight.com/getImage?file=...", "gst_doc": "https://auth.neardelight.com/getImage?file=..." }, "bank_info": { "holder_name": "Anita Foods Pvt Ltd", "bank_name": "HDFC", "branch_name": "Andheri", "account_number": "9876543210", "ifsc_code": "HDFC0001234", "cheque_passbook": "https://auth.neardelight.com/getImage?file=..." } } } ``` **Example response — Buyer:** ```json { "status": true, "message": "User fetched successfully.", "data": { "id": 200, "full_name": "Priya Singh", "role_id": 4, "role_name": "Buyer", "buyer_profile": { "date_of_birth": "1998-04-12", "food_preference": "veg", "used_referral_code": "FERAHUL", "is_signup_bonus_claimed": true, "notifications_enabled": true }, "wallet": { "balance": 75.00, "total_earned": 100.00, "total_spent": 25.00, "total_expired": 0.00 } } } ``` --- ## 3. Admin User Management > All endpoints in this section are **Super Admin only**. > Assign/revoke permissions on an admin **force-logouts all their active sessions** — they must re-login to receive the updated token. --- ### 3.1 Create Admin ```bash curl -X POST http://127.0.0.1:8000/v3/admins/create/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "full_name": "John Doe", "email": "john@example.com", "mobile_number": "9876543210", "password": "Admin@123" }' ``` > `password` is optional — a random password is generated if omitted (login is OTP-based). --- ### 3.2 Get Admin Detail ```bash curl -X GET http://127.0.0.1:8000/v3/admins/42/ \ -H "Authorization: Bearer " ``` > Replace `42` with the admin's `user_id`. > Response includes a `permissions` array with all active grants attached to this admin (module, action, label, expiry, etc.). --- ### 3.3 Update Admin ```bash curl -X PATCH http://127.0.0.1:8000/v3/admins/42/update/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "full_name": "John Smith", "email": "johnsmith@example.com", "mobile_number": "9876543211" }' ``` > All fields are optional — send only what needs to change. --- ### 3.4 Toggle Admin Active / Inactive > **Endpoint moved.** Use the unified account toggle: > `PATCH /v3/accounts//toggle/` > See **Section 8 — Account Toggle** for full details. --- ## 3. Permission Master > All endpoints in this section are **Super Admin only**. --- ### 3.1 List All Permissions ```bash curl -X GET http://127.0.0.1:8000/v3/admin/permissions/ \ -H "Authorization: Bearer " ``` **With pagination and search:** ```bash curl -X GET "http://127.0.0.1:8000/v3/admin/permissions/?page=1&page_size=20&search=sellers" \ -H "Authorization: Bearer " ``` > `search` — searches across module, action, label, description (case-insensitive) > `page` — page number (default: 1) > `page_size` — items per page (default: 20, max: 100) --- ### 3.2 Create a New Permission ```bash curl -X POST http://127.0.0.1:8000/v3/admin/permissions/create/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "module": "catalog", "action": "view", "label": "View Catalog", "description": "Can browse and search the product catalog" }' ``` > `action` must be one of: `view`, `add`, `edit`, `delete`. > `(module, action)` pair must be unique across the system. --- ### 3.3 Toggle Permission Active / Inactive ```bash curl -X PATCH http://127.0.0.1:8000/v3/admin/permissions/5/toggle/ \ -H "Authorization: Bearer " ``` > Replace `5` with the `permission_id` from the list endpoint. > Disabling a permission **blocks it globally** for all users who hold it. --- ## 4. User Permission Management > Assign/revoke permissions triggers **force-logout** for the target user — they must re-login to get a fresh token with updated permissions. --- ### 4.1 Get Permissions Assigned to a User > Accessible by **Super Admin** and **Admin**. ```bash curl -X GET "http://127.0.0.1:8000/v3/admin/permissions/user/?user_id=42" \ -H "Authorization: Bearer " ``` **With pagination and search:** ```bash curl -X GET "http://127.0.0.1:8000/v3/admin/permissions/user/?user_id=42&search=orders&page=1&page_size=20" \ -H "Authorization: Bearer " ``` --- ### 4.2 Assign Permissions to a User > **Super Admin only.** > `expires_at` is optional — omit for a permanent grant. ```bash curl -X POST http://127.0.0.1:8000/v3/admin/permissions/user/assign/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "user_id": 42, "permission_ids": [1, 5, 9] }' ``` **With expiry date:** ```bash curl -X POST http://127.0.0.1:8000/v3/admin/permissions/user/assign/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "user_id": 42, "permission_ids": [1, 5, 9], "expires_at": "2026-12-31T23:59:59" }' ``` --- ### 4.3 Revoke Permissions from a User > **Super Admin only.** > Sets `is_active=false` on the grant — row is kept for audit trail. ```bash curl -X DELETE http://127.0.0.1:8000/v3/admin/permissions/user/revoke/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "user_id": 42, "permission_ids": [1, 9] }' ``` --- ## 5. Field Executive Management > All endpoints in this section are **Super Admin only**. > FE list is available via `GET /v3/users/?role_id=5` (section 2). > Deactivating an FE immediately **force-logouts all their active sessions**. > All file uploads use `multipart/form-data`. JSON body for non-file requests. --- ### Field Names Reference | Purpose | Field name in request | Notes | |-----------------|-------------------------------|----------------------------------| | PAN number | `pan_number` | Text field | | PAN file | `pan_file` | File upload | | Aadhar number | `aadhar_number` | Text field | | Aadhar file | `aadhar_file` | File upload | | GST number | `gst_number` | Text field | | GST file | `gst_file` | File upload | | Cheque/Passbook | `cheque_passbook` | File upload | | Bank details | `bank_details` (JSON) or flat fields | `holder_name`, `bank_name`, `branch_name`, `account_number`, `ifsc_code` | | Commission | `commission_daily_seller_order_charge`, `commission_order_commission`, `commission_onboarding_bonus` | Flat fields | --- ### 5.1 Create Field Executive — Minimal (non-commission-based) > Creates user (role=5) + FE profile + wallet atomically. `joining_date` is always today. > Pass `is_commission_based=false` to create an FE without fees — KYC & bank details will not be required. ```bash curl -X POST http://127.0.0.1:8000/v3/field-executives/create/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "full_name": "Ravi Kumar", "mobile_number": "9876543210", "email": "ravi@example.com", "is_commission_based": false }' ``` --- ### 5.1a Create Field Executive — Commission-based (full details + KYC files + bank + commission) > `is_commission_based` defaults to `true` if omitted. > Send as `multipart/form-data` when uploading files. ```bash curl --request POST \ --url http://127.0.0.1:8000/v3/field-executives/create/ \ --header 'Authorization: Bearer ' \ --form 'full_name=Ravi Kumar' \ --form 'mobile_number=9876543210' \ --form 'email=ravi@example.com' \ --form 'password=MyPass@123' \ --form 'is_commission_based=true' \ --form 'executive_type=individual' \ --form 'referral_code=FERAVI01' \ --form 'pan_number=ABCDE1234F' \ --form 'pan_file=@/path/to/pan.jpg' \ --form 'aadhar_number=123456789012' \ --form 'aadhar_file=@/path/to/aadhar.jpg' \ --form 'gst_number=22ABCDE1234F1Z5' \ --form 'gst_file=@/path/to/gst.jpg' \ --form 'commission_daily_seller_order_charge=12.00' \ --form 'commission_order_commission=1.50' \ --form 'commission_onboarding_bonus=15.00' ``` > `password` — optional, defaults to mobile number if omitted > `referral_code` — optional, auto-generated if omitted; returns error if already taken > `executive_type` — `individual` (default) or `organization` > `organisation_name` — required when `executive_type=organization` > `is_commission_based` — `true` (default) or `false`; when `false`, KYC & bank fields are ignored > Commission fields — optional; global defaults apply if omitted **Organization type example:** ```bash curl --request POST \ --url http://127.0.0.1:8000/v3/field-executives/create/ \ --header 'Authorization: Bearer ' \ --form 'full_name=Kumar Enterprises Rep' \ --form 'mobile_number=9876543211' \ --form 'email=kumar@enterprises.com' \ --form 'executive_type=organization' \ --form 'organisation_name=Kumar Enterprises' \ --form 'is_commission_based=false' ``` --- ### 5.2 Get FE Detail ```bash curl --request GET \ --url http://127.0.0.1:8000/v3/field-executives/5/ \ --header 'Authorization: Bearer ' ``` > Replace `5` with the FE's `user_id`. > Response includes: user info, FE profile (bank + KYC details, referral code), wallet balance, active commission rates, and assigned permissions. --- ### 5.3 Update FE — Basic fields (JSON) > All fields optional — send only what needs to change. ```bash curl --request PATCH \ --url http://127.0.0.1:8000/v3/field-executives/5/update/ \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "full_name": "Ravi Kumar Updated", "email": "ravi.new@example.com", "mobile_number": "9876543299", "executive_type": "individual", "joining_date": "2026-02-01" }' ``` --- ### 5.3a Update FE — Bank details (JSON) > Updating bank details automatically **resets bank verification**. ```bash curl --request PATCH \ --url http://127.0.0.1:8000/v3/field-executives/5/update/ \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "bank_details": { "holder_name": "Ravi Kumar", "bank_name": "SBI", "branch_name": "MG Road", "account_number": "1234567890", "ifsc_code": "SBIN0001234" } }' ``` --- ### 5.3b Update FE — KYC numbers + files (multipart) ```bash curl --request PATCH \ --url http://127.0.0.1:8000/v3/field-executives/5/update/ \ --header 'Authorization: Bearer ' \ --form 'pan_number=ABCDE1234F' \ --form 'pan_file=@/path/to/pan.jpg' \ --form 'aadhar_number=123456789012' \ --form 'aadhar_file=@/path/to/aadhar.jpg' \ --form 'gst_number=22ABCDE1234F1Z5' \ --form 'gst_file=@/path/to/gst.jpg' ``` > File field names: `pan_file`, `aadhar_file`, `gst_file` --- ### 5.3c Update FE — Bank cheque/passbook file (multipart) ```bash curl --request PATCH \ --url http://127.0.0.1:8000/v3/field-executives/5/update/ \ --header 'Authorization: Bearer ' \ --form 'holder_name=Ravi Kumar' \ --form 'bank_name=SBI' \ --form 'branch_name=MG Road' \ --form 'account_number=1234567890' \ --form 'ifsc_code=SBIN0001234' \ --form 'cheque_passbook=@/path/to/cheque.jpg' ``` > File field name: `cheque_passbook` --- ### 5.4 Toggle FE Active / Inactive > **Endpoint moved.** Use the unified account toggle: > `PATCH /v3/accounts//toggle/` > See **Section 8 — Account Toggle** for full details. --- ### 5.5 Verify KYC ```bash curl --request PATCH \ --url http://127.0.0.1:8000/v3/field-executives/5/verify-kyc/ \ --header 'Authorization: Bearer ' ``` > Sets `is_kyc_verified=true`, records `kyc_verified_at` and `kyc_verified_by`. > Returns 200 with message if already verified. --- ### 5.6 Verify Bank Details ```bash curl --request PATCH \ --url http://127.0.0.1:8000/v3/field-executives/5/verify-bank/ \ --header 'Authorization: Bearer ' ``` > Sets `is_bank_verified=true`, records `bank_verified_at` and `bank_verified_by`. > Returns 400 if bank details are not saved yet. --- ### 5.7 Update Commission Rates > Creates new versioned override rows. Old rows are closed (effective_to = yesterday). ```bash curl --request PATCH \ --url http://127.0.0.1:8000/v3/field-executives/5/commission/ \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "daily_seller_order_charge": 15.00, "order_commission": 2.00, "onboarding_bonus": 20.00 }' ``` **Update a single rate:** ```bash curl --request PATCH \ --url http://127.0.0.1:8000/v3/field-executives/5/commission/ \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "order_commission": 2.50 }' ``` > Response includes the full updated commission snapshot for all 3 types. --- ### FE Commission Types Reference | commission_type | Request field name | Default | |--------------------------------------|----------------------------------------------|---------| | `daily_seller_order_charge` | `commission_daily_seller_order_charge` | ₹10.00 | | `order_commission` | `commission_order_commission` | ₹1.00 | | `onboarding_bonus` | `commission_onboarding_bonus` | ₹10.00 | --- ### FE Detail Response Shape ```json { "status": true, "message": "Field Executive fetched successfully.", "data": { "user": { "id": 5, "full_name": "Ravi Kumar", "email": "ravi@example.com", "mobile_number": "9876543210", "status": 1, "last_login": null, "created_at": "2026-03-24T10:00:00" }, "profile": { "fe_id": 3, "executive_type": "individual", "organisation_name": null, "referral_code": "FERAVI01", "joining_date": "2026-03-24", "is_commission_based": true, "is_kyc_verified": false, "kyc_verified_at": null, "is_bank_verified": false, "bank_verified_at": null, "status": 1, "bank_details": { "holder_name": "Ravi Kumar", "bank_name": "SBI", "branch_name": "MG Road", "account_number": "1234567890", "ifsc_code": "SBIN0001234", "cheque_passbook_path": "FieldExecutive/202603/bank/cheque.jpg" }, "kyc_details": { "pan": { "number": "ABCDE1234F", "file_path": "FieldExecutive/202603/kyc/pan.jpg" }, "aadhar": { "number": "123456789012", "file_path": "FieldExecutive/202603/kyc/aadhar.jpg" }, "gst": { "number": "22ABCDE1234F1Z5", "file_path": "FieldExecutive/202603/kyc/gst.jpg" } } }, "wallet": { "balance": "0.00", "total_credited": "0.00", "total_debited": "0.00" }, "commission": { "daily_seller_order_charge": { "amount": "10.00", "effective_from": "2026-03-24", "is_fe_override": false }, "order_commission": { "amount": "1.00", "effective_from": "2026-03-24", "is_fe_override": false }, "onboarding_bonus": { "amount": "10.00", "effective_from": "2026-03-24", "is_fe_override": false } }, "permissions": [ { "user_permission_id": 12, "permission_id": 3, "module": "sellers", "action": "view", "label": "View Sellers", "permission_active": true, "granted_by_id": 1, "granted_by_name": "Super Admin", "granted_at": "2026-03-20T09:00:00", "expires_at": null, "is_expired": false } ] } } ``` --- ### 5.8 FE Profile (Self-Service / SA / Admin) > **FE** — no `user_id` param (own record). **SA / Admin** — pass `?user_id=`. > Includes: user info, KYC, bank, wallet summary, commission, and `kyc_complete` / `bank_complete` flags. ```bash # Field Executive curl --request GET \ --url http://127.0.0.1:8000/v3/field-executives/profile/ \ --header 'Authorization: Bearer ' ``` ```bash # Super Admin / Admin curl --request GET \ --url 'http://127.0.0.1:8000/v3/field-executives/profile/?user_id=5' \ --header 'Authorization: Bearer ' ``` **Response:** ```json { "status": true, "message": "Profile fetched successfully.", "data": { "user": { "id": 5, "full_name": "Ravi Kumar", "email": "ravi@example.com", "mobile_number": "9876543210", "status": 1, "last_login": null, "created_at": "2026-03-24T10:00:00" }, "profile": { "fe_id": 3, "executive_type": "individual", "organisation_name": null, "referral_code": "FERAVI01", "joining_date": "2026-03-24", "is_commission_based": true, "is_kyc_verified": false, "kyc_verified_at": null, "is_bank_verified": false, "bank_verified_at": null, "status": true }, "kyc_details": { "pan": { "number": "ABCDE1234F", "file_url": "https://host/getImage?file=...", "has_file": true }, "aadhar": { "number": "", "file_url": "", "has_file": false }, "gst": { "number": "", "file_url": "", "has_file": false } }, "bank_details": { "holder_name": "Ravi Kumar", "bank_name": "SBI", "branch_name": "MG Road", "account_number": "1234567890", "ifsc_code": "SBIN0001234", "cheque_passbook_url": "" }, "kyc_complete": false, "bank_complete": false, "wallet": { "balance": "150.00", "total_credited": "200.00", "total_debited": "50.00" }, "commission": { "daily_seller_order_charge": { "amount": "10.00", "effective_from": "2026-03-24", "is_fe_override": false }, "order_commission": { "amount": "1.00", "effective_from": "2026-03-24", "is_fe_override": false }, "onboarding_bonus": { "amount": "10.00", "effective_from": "2026-03-24", "is_fe_override": false } } } } ``` --- ### 5.9 FE Profile Update — KYC & Bank (FE Self-Service / SA / Admin) > FE can add or update KYC and bank details **only while that section is incomplete**. > Once all fields in a section are filled, it is **locked** — the FE must contact support to make changes. > Send only the fields you want to update (multipart/form-data). > > **Non-commission FEs:** Returns `400` — KYC & bank not applicable. SA must use `PATCH /v3/field-executives//update/` for forced edits. > > **Lock rules (commission-based FEs only):** > - KYC locked when: all 3 sections (pan, aadhar, gst) have both a number AND a document file > - Bank locked when: holder_name, bank_name, branch_name, account_number, ifsc_code, cheque_passbook all filled ```bash # Submit PAN number + file (FE self-service) curl --request PATCH \ --url http://127.0.0.1:8000/v3/field-executives/profile/update/ \ --header 'Authorization: Bearer ' \ --form 'pan_number=ABCDE1234F' \ --form 'pan_file=@/path/to/pan.jpg' ``` ```bash # Submit all KYC at once curl --request PATCH \ --url http://127.0.0.1:8000/v3/field-executives/profile/update/ \ --header 'Authorization: Bearer ' \ --form 'pan_number=ABCDE1234F' \ --form 'pan_file=@/path/to/pan.jpg' \ --form 'aadhar_number=123456789012' \ --form 'aadhar_file=@/path/to/aadhar.jpg' \ --form 'gst_number=22ABCDE1234F1Z5' \ --form 'gst_file=@/path/to/gst.jpg' ``` ```bash # Submit bank details curl --request PATCH \ --url http://127.0.0.1:8000/v3/field-executives/profile/update/ \ --header 'Authorization: Bearer ' \ --form 'holder_name=Ravi Kumar' \ --form 'bank_name=SBI' \ --form 'branch_name=MG Road' \ --form 'account_number=1234567890' \ --form 'ifsc_code=SBIN0001234' \ --form 'cheque_passbook=@/path/to/cheque.jpg' ``` **Success Response (200):** ```json { "status": true, "message": "Your details have been saved successfully.", "kyc_complete": false, "bank_complete": true } ``` **Locked section error (400):** ```json { "status": false, "message": "Your bank details are already complete and cannot be changed. Please contact support if you need to make corrections." } ``` **Non-commission FE error (400):** ```json { "status": false, "message": "This field executive is not commission-based. KYC and bank details are not needed for this account." } ``` > `kyc_complete` and `bank_complete` in the response tell the UI whether to show or hide the edit form. --- ### 5.11 View Commission Structure (FE Self-Service / SA / Admin) > **FE** — no `user_id` param needed (own record returned automatically). > **SA / Admin** — pass `?user_id=`. ```bash # Field Executive viewing their own commission curl --request GET \ --url http://127.0.0.1:8000/v3/field-executives/commission/ \ --header 'Authorization: Bearer ' ``` ```bash # Super Admin / Admin viewing a specific FE's commission curl --request GET \ --url 'http://127.0.0.1:8000/v3/field-executives/commission/?user_id=5' \ --header 'Authorization: Bearer ' ``` **Response:** ```json { "status": true, "message": "Commission structure fetched successfully.", "data": { "fe_id": 3, "user_id": 5, "referral_code": "FERAVI01", "commission": { "daily_seller_order_charge": { "amount": "10.00", "effective_from": "2026-03-24", "is_fe_override": false }, "order_commission": { "amount": "1.00", "effective_from": "2026-03-24", "is_fe_override": false }, "onboarding_bonus": { "amount": "10.00", "effective_from": "2026-03-24", "is_fe_override": true } } } } ``` --- ### 5.12 View Wallet Balance (FE Self-Service / SA / Admin) > **FE** — no `user_id` param needed. > **SA / Admin** — pass `?user_id=`. ```bash # Field Executive curl --request GET \ --url http://127.0.0.1:8000/v3/field-executives/wallet/ \ --header 'Authorization: Bearer ' ``` ```bash # Super Admin / Admin curl --request GET \ --url 'http://127.0.0.1:8000/v3/field-executives/wallet/?user_id=5' \ --header 'Authorization: Bearer ' ``` **Response:** ```json { "status": true, "message": "Wallet details fetched successfully.", "data": { "fe_id": 3, "user_id": 5, "referral_code": "FERAVI01", "balance": "150.00", "total_credited": "200.00", "total_debited": "50.00", "last_updated": "2026-03-24T10:30:00" } } ``` --- ### 5.13 Wallet Transactions (FE Self-Service / SA / Admin) > **FE** — no `user_id` needed. > **SA / Admin** — pass `?user_id=`. **All filters optional — can be combined:** | Param | Values | |--------------------|------------------------------------------------------------------------| | `transaction_type` | `credit` \| `debit` | | `credit_type` | `daily_seller_order_charge` \| `order_commission` \| `onboarding_bonus` | | `debit_type` | `withdrawal` | | `reference_type` | `seller` \| `order` \| `withdrawal` | | `start_date` | `YYYY-MM-DD` | | `end_date` | `YYYY-MM-DD` | | `page` | integer (default `1`) | | `page_size` | integer (default `10`, max `100`) | ```bash # All transactions (FE own) curl --request GET \ --url http://127.0.0.1:8000/v3/field-executives/wallet/transactions/ \ --header 'Authorization: Bearer ' ``` ```bash # Credits only in a date range (FE own) curl --request GET \ --url 'http://127.0.0.1:8000/v3/field-executives/wallet/transactions/?transaction_type=credit&start_date=2026-03-01&end_date=2026-03-31' \ --header 'Authorization: Bearer ' ``` ```bash # SA viewing a specific FE's onboarding bonuses curl --request GET \ --url 'http://127.0.0.1:8000/v3/field-executives/wallet/transactions/?user_id=5&credit_type=onboarding_bonus' \ --header 'Authorization: Bearer ' ``` **Response:** ```json { "status": true, "message": "Transactions fetched successfully.", "data": [ { "id": 101, "transaction_type": "credit", "credit_type": "onboarding_bonus", "debit_type": null, "amount": "10.00", "balance_before": "140.00", "balance_after": "150.00", "reference_type": "seller", "reference_id": 42, "transaction_date": "2026-03-24", "description": "Onboarding bonus for seller #42", "created_at": "2026-03-24T11:00:00" } ], "pagination": { "page": 1, "page_size": 10, "total_count": 1, "total_pages": 1, "has_next": false, "has_previous": false, "next_page": null, "previous_page": null, "next": null, "previous": null } } ``` --- ## 6. Support Executive Management > All endpoints in this section are **Super Admin only**. > Support Executives (role=6) can be assigned permissions just like Admins. --- ### 6.1 Create Support Executive ```bash curl --request POST \ --url http://127.0.0.1:8000/v3/support/create/ \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "full_name": "Anita Sharma", "email": "anita@example.com", "mobile_number": "9876543210", "password": "Support@123" }' ``` > `password` — optional, defaults to mobile number if omitted. --- ### 6.2 Get Support Executive Detail ```bash curl --request GET \ --url http://127.0.0.1:8000/v3/support/10/ \ --header 'Authorization: Bearer ' ``` > Response includes profile + all active permissions assigned to this executive. --- ### 6.3 Update Support Executive ```bash curl --request PATCH \ --url http://127.0.0.1:8000/v3/support/10/update/ \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "full_name": "Anita Sharma Updated", "email": "anita.new@example.com" }' ``` > All fields optional — send only what needs to change. --- ### 6.4 Toggle Support Executive Active / Inactive > **Endpoint moved.** Use the unified account toggle: > `PATCH /v3/accounts//toggle/` > See **Section 8 — Account Toggle** for full details. --- ### 6.5 Support Executive Profile (Self-Service / SA) > **Support Executive** — no `user_id` param needed (own record). > **Super Admin** — pass `?user_id=`. > Profile information is **read-only** for the Support Executive. Only Super Admin can update it. ```bash # Support Executive viewing own profile curl --request GET \ --url http://127.0.0.1:8000/v3/support/profile/ \ --header 'Authorization: Bearer ' ``` ```bash # Super Admin viewing a specific Support Executive curl --request GET \ --url 'http://127.0.0.1:8000/v3/support/profile/?user_id=10' \ --header 'Authorization: Bearer ' ``` **Response:** ```json { "status": true, "message": "Profile fetched successfully.", "data": { "id": 10, "full_name": "Anita Sharma", "email": "anita@example.com", "mobile_number": "9876543210", "status": 1, "is_email_verified": false, "is_mobile_verified": false, "is_profile_completed": false, "created_at": "2026-03-24T10:00:00", "last_login": null, "permissions": [ { "user_permission_id": 5, "permission_id": 2, "module": "sellers", "action": "view", "label": "View Sellers", "permission_active": true, "granted_by_id": 1, "granted_by_name": "Super Admin", "granted_at": "2026-03-20T09:00:00", "expires_at": null, "is_expired": false } ] } } ``` --- ## 7. Session Management > All endpoints require a valid `Authorization: Bearer ` header. > Every authenticated user can manage only their own sessions. --- ### 7.1 Logout (current session) ```bash curl --request POST \ --url http://127.0.0.1:8000/v3/auth/logout/ \ --header 'Authorization: Bearer ' ``` > Blacklists the current token and closes the current session. No body needed. --- ### 7.2 List All Active Sessions ```bash curl --request GET \ --url http://127.0.0.1:8000/v3/auth/sessions/ \ --header 'Authorization: Bearer ' ``` **Response:** ```json { "status": true, "message": "Sessions fetched successfully.", "count": 2, "data": [ { "session_id": 14, "device_name": "Chrome on Windows", "os_name": "Windows 11", "ip_address": "192.168.1.10", "user_agent": "Mozilla/5.0 ...", "created_at": "2026-03-24T08:00:00", "last_activity": "2026-03-24T10:30:00", "is_current": true }, { "session_id": 11, "device_name": "Android App", "os_name": "Android 13", "ip_address": "103.21.58.9", "user_agent": "okhttp/4.9.3", "created_at": "2026-03-22T14:00:00", "last_activity": "2026-03-23T18:00:00", "is_current": false } ] } ``` > `is_current: true` marks the session belonging to the token used in this request. --- ### 7.3 Logout a Specific Session ```bash curl --request DELETE \ --url http://127.0.0.1:8000/v3/auth/sessions/11/ \ --header 'Authorization: Bearer ' ``` > Replace `11` with the `session_id` from the list. Users can only logout their own sessions. --- ### 7.4 Logout All Sessions ```bash curl --request DELETE \ --url http://127.0.0.1:8000/v3/auth/sessions/logout-all/ \ --header 'Authorization: Bearer ' ``` > Blacklists **all** active sessions including the current one. User must login again after this. --- ## 8. Account Toggle > Single endpoint to activate or deactivate **Admin**, **Support Executive**, or **Field Executive**. > Super Admin only. Role is detected automatically. | Role | Status values | Tables | |------|---------------|--------| | Admin (2) | `1` ↔ `2` | `users` | | Support Executive (6) | `1` ↔ `2` | `users` | | Field Executive (5) | `1` ↔ `0` | `users` + `field_executives` | > Deactivation always **force-logouts all active sessions**. ```bash # Deactivate / activate an Admin curl --request PATCH \ --url http://127.0.0.1:8000/v3/accounts/42/toggle/ \ --header 'Authorization: Bearer ' ``` ```bash # Deactivate / activate a Support Executive curl --request PATCH \ --url http://127.0.0.1:8000/v3/accounts/20/toggle/ \ --header 'Authorization: Bearer ' ``` ```bash # Deactivate / activate a Field Executive curl --request PATCH \ --url http://127.0.0.1:8000/v3/accounts/5/toggle/ \ --header 'Authorization: Bearer ' ``` **Response (200):** ```json { "status": true, "message": "Field Executive deactivated successfully.", "is_active": false } ``` **Error — user not found or unsupported role (404):** ```json { "status": false, "message": "We could not find this account." } ``` --- ## Role Reference | role_id | Title | |---------|---------------------| | 1 | Super Admin | | 2 | Admin | | 3 | Seller | | 4 | Buyer | | 5 | Field Executive | | 6 | Support Executive | | 7 | Store Manager | ## Permission Check Rules | Role | Permission Check | |-----------------|----------------------------| | Super Admin | Always allowed — no check | | Admin | Checked against DB / cache | | Field Executive | Checked against DB / cache | | Buyer / Seller | No permission system | ## Pagination — Standard Response Block Every list endpoint returns a `pagination` object: ```json "pagination": { "page": 1, "page_size": 10, "total_count": 45, "total_pages": 5, "has_next": true, "has_previous": false, "next_page": 2, "previous_page": null, "next": "http://127.0.0.1:8000/v3/admins/?page=2&page_size=10", "previous": null } ``` # Roles ROLE_SUPER_ADMIN = 1 ROLE_ADMIN = 2 ROLE_SELLER = 3 ROLE_BUYER = 4 ROLE_FIELD_EXECUTIVE = 5 ROLE_SUPPORT = 6 ROLE_STORE_MANAGER = 7