extra_api

# Extra App for ERPNext - Complete API Documentation

**Version:** 1.0.1  
**Publisher:** sammish  
**License:** MIT

A comprehensive ERPNext custom application that extends core functionality with retail-focused features, advanced payment management, inventory controls, enhanced reporting capabilities, and **complete mobile API integration**.

## 🚀 Key Features

### 💳 Advanced Payment Management
- **Unified Payment Override System**: Modify payment methods for submitted Sales Invoices with proper GL entry cleanup
- **Role-Based Payment Modification**: Configurable access control for payment modifications
- **Dynamic Account Detection**: Automatically detects and handles various payment account types
- **GL Entry Cleanup**: Surgical removal of excess GL entries when reducing payment methods
- **Cost Center Support**: Proper cost center handling during payment modifications

### 📱 **Mobile API Integration (NEW)**
- **Customer Management APIs**: Search and retrieve customers with pagination
- **Real-time Inventory APIs**: Check stock availability with reservation handling
- **Sales Order Management**: Complete order lifecycle with validation
- **Stock Reservation System**: Automatic stock reservation and release
- **Authentication & Session Management**: Secure API access

### 🏪 Retail & Inventory Management
- **Inventory Transfer System**: Custom doctype for efficient stock transfers between locations
- **Inventory Receipt Management**: Streamlined receipt processing with item-level tracking
- **In-Transit Warehouse Integration**: Configurable warehouse management for transfers

### 📊 Enhanced Reporting Suite
- **Sales Margin Reports**: 
  - Brand-wise sales margin analysis
  - Vendor-wise sales margin reporting with data science features
  - Month-wise margin reporting
- **Sales Register Enhancements**: Multiple formats and consolidated views
- **Stock Reports**: 
  - Stock statement with advanced filtering
  - SOH (Stock on Hand) formatting
- **Statement of Accounts**: Custom formatting and processing
- **Day End Reports**: Comprehensive daily sales summaries
- **Barcode Master**: Barcode management and tracking

### 🏷️ Product Attribute Management
Advanced product categorization with custom doctypes:
- **Age Category**: Age-based product classification
- **Category & Sub-Brand**: Hierarchical product organization
- **Fashion Attributes**: Collar, Color, Fabric, Fit, Pattern, Pocket, Season, Size, Sleeve
- **Occasion Management**: Event-based product categorization
- **Vendor Name Management**: Centralized vendor information

### 💰 Financial Tools
- **Additional Salary Bulk Update**: Mass salary adjustments with item-level tracking
- **Item Price Updater**: Bulk price management system
- **Tax Template Management**: Streamlined tax configuration

### ⚙️ System Configuration
- **Extra Settings**: Centralized configuration management

---

# 📱 Mobile API Documentation

## 🌟 Overview
This section provides all API endpoints for Mobile App integration with the Extra ERPNext system.

## 🔗 Base URL
```
http://your-domain.com/api/method/
```

## 🔐 Authentication
All APIs require authentication. Use one of these methods:

### Method 1: Session-based (Recommended for Mobile Apps)
```bash
# 1. Login to get session
POST /api/method/login
{
  "usr": "your_username",
  "pwd": "your_password"
}

# 2. Use returned session in subsequent calls
Headers: {
  "Cookie": "sid=session_id_from_login_response"
}
```

### Method 2: API Key (Production)
```bash
Headers: {
  "Authorization": "token api_key:api_secret"
}
```

---

## 📱 API Endpoints Summary

| Category | Endpoint | Method | Purpose |
|----------|----------|--------|---------|
| **Customer Management** | `extra.api.get_customers` | GET | Get all customers (max 100) |
| | `extra.api.search_customers` | GET/POST | Search customers by name/GSTIN |
| **Inventory Management** | `extra.api.get_item_stock` | GET | Get actual stock quantity |
| | `extra.api.get_projected_qty` | GET | Get available stock (considering orders) |
| | `extra.api.check_inventory_before_order` | POST | Validate stock before order creation |
| **Sales Order Management** | `extra.api.create_sales_order` | POST | Create new sales order |
| | `extra.api.get_sales_orders` | GET | Get existing sales orders |
| | `extra.api.get_sales_order_status` | GET | Get detailed order status |
| | `extra.api.cancel_sales_order` | POST | Cancel order & free stock |
| | `extra.api.close_sales_order` | POST | Close order & free remaining stock |

---

## 🏷️ Customer APIs

### 1. Get All Customers
```http
GET /api/method/extra.api.get_customers?limit=50
```

**Parameters:**
- `limit` (optional): Max customers to return (default: 100, max: 100)

**Response:**
```json
{
  "message": {
    "success_key": 1,
    "message": "Customers fetched successfully",
    "customers": [
      {
        "name": "SPACE FOR MEN",
        "customer_name": "SPACE FOR MEN",
        "gstin": "29ABCDE1234F1Z5"
      }
    ],
    "total_count": 1,
    "limit_applied": 50
  }
}
```

### 2. Search Customers
```http
POST /api/method/extra.api.search_customers
{
  "data": "{\"search_term\": \"SPACE\", \"limit\": 20}"
}
```

**Parameters:**
- `search_term` (optional): Text to search in name/customer_name/GSTIN
- `limit` (optional): Max results (default: 100, max: 100)

**Response:**
```json
{
  "message": {
    "success_key": 1,
    "message": "Found 1 customers",
    "customers": [...],
    "search_term": "SPACE",
    "can_create_order": true
  }
}
```

---

## 📦 Inventory APIs

### 1. Get Item Stock (Actual Quantity)
```http
GET /api/method/extra.api.get_item_stock?item_code=10200103
```

**Parameters:**
- `item_code` (required): Item code to check
- `warehouse` (optional): Warehouse name (uses default if not provided)

**Response:**
```json
{
  "message": {
    "success_key": 1,
    "message": "Stock fetched successfully",
    "item_code": "10200103",
    "item_name": "SHIRT NA CASUAL SHIRT",
    "stock_uom": "Nos",
    "warehouse": "Central Store - EAS",
    "available_qty": 11.0
  }
}
```

### 2. Get Projected Quantity (Available for Sale)
```http
GET /api/method/extra.api.get_projected_qty?item_code=10200103
```

**Response:**
```json
{
  "message": {
    "success_key": 1,
    "item_code": "10200103",
    "actual_qty": 11.0,
    "projected_qty": 1.0,
    "pending_sales_orders": 10.0,
    "pending_purchase_orders": 0,
    "available_for_new_orders": 1.0
  }
}
```

### 3. Check Inventory Before Order (Recommended)
```http
POST /api/method/extra.api.check_inventory_before_order
{
  "data": "{\"customer\": \"SPACE FOR MEN\", \"items\": [{\"item_code\": \"10200103\", \"qty\": 3}]}"
}
```

**Response:**
```json
{
  "message": {
    "success_key": 1,
    "message": "Inventory check completed. Status: available",
    "customer": {
      "name": "SPACE FOR MEN",
      "customer_name": "SPACE FOR MEN"
    },
    "total_status": "available",
    "inventory_status": [
      {
        "item_code": "10200103",
        "item_name": "SHIRT NA CASUAL SHIRT",
        "requested_qty": 3,
        "actual_qty": 11.0,
        "available_qty": 1.0,
        "pending_orders": 10.0,
        "status": "insufficient",
        "message": "Available: 1.0, Requested: 3 (Actual: 11.0, Reserved: 10.0)"
      }
    ],
    "can_create_order": false
  }
}
```

---

## 🛒 Sales Order APIs

### 1. Create Sales Order
```http
POST /api/method/extra.api.create_sales_order
{
  "data": "{\"customer\": \"SPACE FOR MEN\", \"transaction_date\": \"2025-09-06\", \"delivery_date\": \"2025-09-13\", \"items\": [{\"item_code\": \"10200103\", \"qty\": 10, \"rate\": 500}]}"
}
```

**Parameters:**
- `customer` (required): Customer name
- `transaction_date` (optional): Order date (default: today)
- `delivery_date` (optional): Expected delivery date
- `items` (required): Array of items
  - `item_code` (required): Item code
  - `qty` (required): Quantity
  - `rate` (optional): Unit price
  - `uom` (optional): Unit of measure

**Success Response:**
```json
{
  "message": {
    "success_key": 1,
    "message": "Sales order created successfully",
    "sales_order": {
      "name": "EXT-SO-25-0002",
      "customer": "SPACE FOR MEN",
      "customer_name": "SPACE FOR MEN",
      "transaction_date": "2025-09-06",
      "status": "To Deliver and Bill",
      "grand_total": 5000.0
    }
  }
}
```

**Error Response (Insufficient Stock):**
```json
{
  "message": {
    "success_key": 0,
    "message": "Inventory validation failed",
    "inventory_validations": [
      {
        "item_code": "10200103",
        "requested_qty": 10,
        "available_qty": 1.0,
        "actual_qty": 11.0,
        "pending_orders": 10.0,
        "message": "Insufficient available stock for 10200103. Available: 1.0, Requested: 10"
      }
    ]
  }
}
```

### 2. Get Sales Orders
```http
GET /api/method/extra.api.get_sales_orders?customer_name=SPACE%20FOR%20MEN
```

**Parameters:**
- `customer_name` (optional): Filter by customer
- `order_status` (optional): Filter by status

**Response:**
```json
{
  "message": {
    "success_key": 1,
    "message": "Sales orders fetched successfully",
    "sales_orders": [
      {
        "name": "EXT-SO-25-0002",
        "customer": "SPACE FOR MEN",
        "transaction_date": "2025-09-06",
        "status": "To Deliver and Bill",
        "grand_total": 5000.0,
        "items": [
          {
            "item_code": "10200103",
            "item_name": "SHIRT NA CASUAL SHIRT",
            "qty": 10.0,
            "rate": 500.0,
            "amount": 5000.0
          }
        ]
      }
    ]
  }
}
```

### 3. Get Sales Order Status
```http
GET /api/method/extra.api.get_sales_order_status?sales_order_name=EXT-SO-25-0002
```

**Response:**
```json
{
  "message": {
    "success_key": 1,
    "sales_order": {
      "name": "EXT-SO-25-0002",
      "customer": "SPACE FOR MEN",
      "status": "To Deliver and Bill",
      "per_delivered": 0.0,
      "grand_total": 5000.0,
      "can_cancel": true,
      "can_close": true
    },
    "items": [
      {
        "item_code": "10200103",
        "ordered_qty": 10.0,
        "delivered_qty": 0.0,
        "pending_qty": 10.0,
        "current_stock": 11.0
      }
    ]
  }
}
```

### 4. Cancel Sales Order
```http
POST /api/method/extra.api.cancel_sales_order
{
  "sales_order_name": "EXT-SO-25-0002"
}
```

**Response:**
```json
{
  "message": {
    "success_key": 1,
    "message": "Sales order cancelled successfully",
    "sales_order": {
      "name": "EXT-SO-25-0002",
      "status": "Cancelled"
    },
    "freed_stock": [
      {
        "item_code": "10200103",
        "qty": 10.0,
        "warehouse": "Central Store - EAS"
      }
    ]
  }
}
```

### 5. Close Sales Order
```http
POST /api/method/extra.api.close_sales_order
{
  "sales_order_name": "EXT-SO-25-0002"
}
```

---

# 🚀 Quick API Reference

## 🔧 Quick Start

### 1. Authentication
```bash
curl -X POST "http://localhost:8000/api/method/login" \
  -H "Content-Type: application/json" \
  -d '{"usr": "administrator", "pwd": "@PPLE999"}' \
  -c cookies.txt
```

### 2. Use Session for All API Calls
```bash
curl -X GET "http://localhost:8000/api/method/extra.api.get_customers" \
  -H "Content-Type: application/json" \
  -b cookies.txt
```

---

## 📋 Essential APIs

### Customer Management
```bash
# Get all customers
GET /api/method/extra.api.get_customers?limit=50

# Search customers
POST /api/method/extra.api.search_customers
{"data": "{\"search_term\": \"john\", \"limit\": 20}"}
```

### Inventory Check
```bash
# Check actual stock
GET /api/method/extra.api.get_item_stock?item_code=10200103

# Check available stock (recommended)
GET /api/method/extra.api.get_projected_qty?item_code=10200103

# Validate before order
POST /api/method/extra.api.check_inventory_before_order
{"data": "{\"customer\": \"SPACE FOR MEN\", \"items\": [{\"item_code\": \"10200103\", \"qty\": 3}]}"}
```

### Sales Order Management
```bash
# Create order
POST /api/method/extra.api.create_sales_order
{"data": "{\"customer\": \"SPACE FOR MEN\", \"items\": [{\"item_code\": \"10200103\", \"qty\": 3, \"rate\": 500}]}"}

# Get orders
GET /api/method/extra.api.get_sales_orders?customer_name=SPACE%20FOR%20MEN

# Cancel order
POST /api/method/extra.api.cancel_sales_order
{"sales_order_name": "EXT-SO-25-0001"}
```

---

## 🔄 Mobile App Flow

```
1. LOGIN → Get session cookie
2. LOAD CUSTOMERS → Cache locally
3. SEARCH → Real-time as user types
4. CHECK STOCK → Before adding to cart
5. VALIDATE → Before order creation
6. CREATE ORDER → Submit to server
7. MANAGE ORDERS → View/Cancel as needed
```

---

## 📱 Response Structure

### Success Response
```json
{
  "message": {
    "success_key": 1,
    "message": "Operation successful",
    "data": {...}
  }
}
```

### Error Response
```json
{
  "message": {
    "success_key": 0,
    "message": "Error description",
    "error": "Technical details"
  }
}
```

---

## 🎯 Key Features

✅ **Stock Management**: Real-time available quantity considering pending orders  
✅ **Order Validation**: Pre-validate before creation to prevent errors  
✅ **Order Lifecycle**: Create → View → Cancel/Close with stock updates  
✅ **Customer Search**: Fast search across name, ID, and GSTIN  
✅ **Error Handling**: Consistent error responses for better UX  

---

## 📊 Example: Complete Order Flow

```bash
# 1. Check customer exists
curl -X POST "http://localhost:8000/api/method/extra.api.search_customers" \
  -b cookies.txt \
  -d '{"data": "{\"search_term\": \"SPACE FOR MEN\"}"}'

# 2. Check item availability
curl -X GET "http://localhost:8000/api/method/extra.api.get_projected_qty?item_code=10200103" \
  -b cookies.txt

# 3. Validate order before creation
curl -X POST "http://localhost:8000/api/method/extra.api.check_inventory_before_order" \
  -b cookies.txt \
  -d '{"data": "{\"customer\": \"SPACE FOR MEN\", \"items\": [{\"item_code\": \"10200103\", \"qty\": 3}]}"}'

# 4. Create order if validation passes
curl -X POST "http://localhost:8000/api/method/extra.api.create_sales_order" \
  -b cookies.txt \
  -d '{"data": "{\"customer\": \"SPACE FOR MEN\", \"items\": [{\"item_code\": \"10200103\", \"qty\": 3, \"rate\": 500}]}"}'
```

---

## 🔧 Development Tips

1. **Always use `check_inventory_before_order` before creating orders**
2. **Cache customer list locally for better performance**
3. **Use `get_projected_qty` for accurate stock display**
4. **Handle both success_key: 1 and success_key: 0 responses**
5. **Store session cookie securely in mobile app**

---

# 🔄 Recommended Mobile App Workflow

### 1. App Startup
```
1. Login user → Get session
2. Load customers → extra.api.get_customers
3. Cache customer list locally
```

### 2. Customer Search
```
1. User types → extra.api.search_customers
2. Show filtered results
3. Allow selection
```

### 3. Order Creation Flow
```
1. User selects items
2. Check stock → extra.api.check_inventory_before_order
3. If available → extra.api.create_sales_order
4. Show success/error message
```

### 4. Order Management
```
1. List orders → extra.api.get_sales_orders
2. View details → extra.api.get_sales_order_status
3. Cancel if needed → extra.api.cancel_sales_order
```

---

## ⚠️ Error Handling

All APIs return consistent error structure:
```json
{
  "message": {
    "success_key": 0,
    "message": "Error description",
    "error": "Technical error details"
  }
}
```

Common HTTP Status Codes:
- `200`: Success
- `401`: Authentication required
- `403`: Permission denied
- `500`: Server error

---

## 🧪 Testing with Postman

### 1. Import Environment
```json
{
  "base_url": "http://localhost:8000/api/method",
  "username": "administrator",
  "password": "@PPLE999"
}
```

### 2. Test Sequence
1. Login
2. Get customers
3. Check item stock
4. Create order
5. Check order status
6. Cancel order

---

# 📦 Mobile Developer Package

## 🎯 What Your Mobile Developer Gets:

✅ **9 Working APIs** - All tested and functional  
✅ **Complete Documentation** - Every endpoint explained  
✅ **Ready-to-use Code** - JavaScript integration class  
✅ **Postman Collection** - Import and test immediately  
✅ **Best Practices** - Mobile app architecture guidance  
✅ **Support Info** - Direct contact for technical help  

---

## 📱 Core APIs Available:

### **Customer Management (2 APIs):**
- Get customers (with pagination)
- Search customers (real-time)

### **Inventory Management (3 APIs):**
- Get actual stock
- Get available stock (considering reservations)
- Validate inventory before order

### **Sales Order Management (4 APIs):**
- Create sales order
- Get sales orders
- Get order status
- Cancel/close orders (with stock release)

---

## 🚀 How to Share with Mobile Developer:

You can send them:
1. **This README.md file** - Contains all documentation
2. **Server credentials**: administrator / @PPLE999
3. **Base URL**: `http://localhost:8000/api/method/`
4. **Postman Collection**: `Extra_ERPNext_Mobile_APIs.postman_collection.json`
5. **JavaScript Example**: `mobile_integration_example.js`

### 📁 Additional Files Available:
- `Extra_ERPNext_Mobile_APIs.postman_collection.json` - Ready-to-import Postman collection
- `mobile_integration_example.js` - Complete JavaScript/React Native integration class
- `sales_order_example.py` - Python testing examples

They can start testing immediately with the Postman collection and begin integration using the JavaScript examples!

---

## 📞 Support & Contact

### **Technical Support:**
- **Email:** sammish.thundiyil@gmail.com
- **System:** ERPNext Extra App v1.0.1
- **Server:** Extra apparel Store

### **Server Details:**
- **Base URL:** `http://localhost:8000/api/method/`
- **Authentication:** Session-based (recommended)
- **Test Account:** administrator / @PPLE999

### **API Endpoints Tested:**
- ✅ All customer APIs working
- ✅ All inventory APIs working  
- ✅ All sales order APIs working
- ✅ Stock reservation/release working
- ✅ Error handling implemented

---

## 🔄 Version History

### **v1.0.1 (September 2025)**
- Initial mobile API implementation
- Customer search functionality
- Real-time inventory management
- Sales order lifecycle management
- Stock reservation system
- Complete documentation package

---

## 🎉 Ready for Development!

All APIs are tested and working. The mobile developer can now:

1. **Import the Postman collection** for immediate testing
2. **Use the JavaScript example** as a starting point
3. **Follow the documentation** for complete implementation
4. **Contact support** for any technical questions

**Happy coding! 🚀**
  - WhatsApp integration settings (Print Format & Letterhead)
  - Role-based access control configuration
  - Warehouse configuration for transfers
  - Payment modification permissions

## 🔧 Installation

1. **Get the app:**
   ```bash
   cd frappe-bench
   bench get-app https://github.com/exvas/extra.git
   ```

2. **Install on site:**
   ```bash
   bench --site [site-name] install-app extra
   ```

3. **Migrate the site:**
   ```bash
   bench --site [site-name] migrate
   ```

## 📋 Configuration

### Payment Modification Setup
1. Navigate to **Extra Settings**
2. Set the **Payment Modification Role** (e.g., "Accounts User")
3. Optionally enable **Allow Administrator/System Manager to Modify Payments**
4. Save settings

### WhatsApp Integration Setup
1. Go to **Extra Settings**
2. Configure **WhatsApp Print Format** and **WhatsApp Letterhead**
3. Set **In-Transit Warehouse** for inventory transfers

## 🎯 Usage

### Modifying Payment Methods
1. Open a submitted Sales Invoice with POS profile
2. Users with configured role will see **"Modify Payment"** button
3. Click to open unified payment dialog
4. Modify payment methods as needed
5. System automatically handles GL entry cleanup

### Inventory Management
1. Use **Inventory Transfer** for stock movements
2. Process **Inventory Receipt** for incoming stock
3. Track transfers through in-transit warehouse

### Reports Access
Navigate to **Reports** section to access:
- Brand/Vendor margin analysis
- Enhanced sales registers
- Stock statements and summaries
- Financial reports and statements

## 🔐 Security Features

- **Role-Based Access Control**: Granular permission management
- **Secure Payment Modifications**: Server-side validation and GL integrity
- **Audit Trail**: Complete tracking of payment modifications
- **Error Handling**: Robust error management with proper rollback

## 🛠️ Technical Architecture

### Core Components
- **Advanced Payment Engine**: `unified_payment_override.py`
- **Unified Payment Override**: `unified_payment_override.js`
- **Permission System**: Role-based access through Extra Settings
- **Custom Doctypes**: 25+ custom doctypes for retail management
- **Enhanced Reports**: 15+ specialized reports with advanced features

### Database Design
- **Single Table Configuration**: Extra Settings for centralized config
- **Linked Entities**: Proper relationships between doctypes
- **Index Optimization**: Efficient querying for large datasets

## 📈 Advanced Features

### Data Science Integration
- **Vendor Performance Analytics**: ML-based vendor analysis
- **Sales Trend Prediction**: Forecasting capabilities
- **Margin Optimization**: Data-driven pricing insights

### API Integration
- **WhatsApp Messaging**: Automated invoice sharing
- **Custom Workflows**: Configurable business processes
- **Export Capabilities**: Multiple format support

## 🧪 Development

### File Structure
```
extra/
├── extra/
│   ├── doctype/           # Custom doctypes
│   ├── report/            # Custom reports  
│   ├── public/js/         # Frontend scripts
│   ├── doc_events/        # Document event handlers
│   └── fixtures/          # Initial data
├── hooks.py               # App configuration
└── README.md             # This file
```

### Key Files
- `unified_payment_override.py`: Payment modification backend
- `unified_payment_override.js`: Frontend payment dialog
- `extra_settings.py`: Configuration management
- `hooks.py`: ERPNext integration hooks

## 📞 Support

- **Email**: sammish.thundiyil@gmail.com
- **Publisher**: sammish
- **Repository**: [GitHub](https://github.com/exvas/extra)

## 📄 License

This project is licensed under the MIT License - see the [license.txt](license.txt) file for details.

## 🙏 Acknowledgments

Built on top of the excellent [ERPNext](https://erpnext.com) and [Frappe](https://frappe.io) frameworks.

---

**Version 1.0.1** - Production Ready Release with Role-Based Access Control