create_wb_kpi_cards

app.py

@@ -269,10 +269,10 @@ def create_interface():
         Monitor your marketplace performance and predict inventory needs with AI-powered analytics.
         
         **Features:**
-        - 📊 Sales performance analysis
-        - 📦 Inventory forecasting
-        - ⚠️ Stockout risk alerts
-        - 📈 Interactive dashboards
+        - 📊 Sales performance analysis with automatic return detection
+        - 📦 Inventory forecasting with AI-powered predictions
+        - ⚠️ Stockout risk alerts and notifications
+        - 📈 Interactive dashboards with commission analysis
         """)
         
         # API Token Configuration

wildberries_client.py

@@ -449,9 +449,18 @@ class WildberriesAPI:
             raise WildberriesAPIError(f"Failed to fetch orders data: {str(e)}")
     
     def _process_sales_data(self, df: pd.DataFrame) -> pd.DataFrame:
-        """Process and clean sales data from API response (v1 sales endpoint)"""
+        """
+        Process and clean sales data from API response (v1 sales endpoint)
+        
+        Handles all 28 fields from the official Wildberries Sales API:
+        - Geographic: warehouseName, warehouseType, countryName, oblastOkrugName, regionName  
+        - Product: supplierArticle, nmId, barcode, category, subject, brand, techSize
+        - Financial: finishedPrice (used as total_price), totalPrice (original_price), discountPercent, spp, paymentSaleAmount, forPay, priceWithDisc
+        - Operational: incomeID, isSupply, isRealization, saleID, sticker, gNumber, srid
+        - Temporal: date, lastChangeDate
+        """
         
-        # Column mapping based on actual sales API response structure
+        # Column mapping based on official Wildberries Sales API schema (v1)
         column_mapping = {
             'date': 'sale_date',
             'lastChangeDate': 'last_change_date',
@@ -470,12 +479,12 @@ class WildberriesAPI:
             'incomeID': 'income_id',
             'isSupply': 'is_supply',
             'isRealization': 'is_realization',
-            'totalPrice': 'total_price',  # Already total price per item
+            'finishedPrice': 'total_price',  # Final price with all discounts applied
+            'totalPrice': 'original_price',  # Original price without discounts
             'discountPercent': 'discount_percent',
             'spp': 'spp_discount',
             'paymentSaleAmount': 'payment_sale_amount',
             'forPay': 'amount_for_pay',  # What seller receives
-            'finishedPrice': 'finished_price',
             'priceWithDisc': 'price_with_discount',
             'saleID': 'sale_id',
             'sticker': 'sticker',
@@ -496,8 +505,8 @@ class WildberriesAPI:
         
         # Convert numeric columns
         numeric_columns = [
-            'total_price', 'discount_percent', 'spp_discount', 'payment_sale_amount',
-            'amount_for_pay', 'finished_price', 'price_with_discount', 'income_id'
+            'product_id', 'total_price', 'original_price', 'discount_percent', 'spp_discount', 
+            'payment_sale_amount', 'amount_for_pay', 'price_with_discount', 'income_id'
         ]
         for col in numeric_columns:
             if col in df.columns:
@@ -512,13 +521,36 @@ class WildberriesAPI:
             else:
                 df['product_name'] = 'Unknown Product'
         
-        # Add quantity (each row represents 1 item sale/return)
+        # Identify returns using saleID prefix (R********* = return, S********* = sale)
+        if 'sale_id' in df.columns:
+            df['is_return'] = df['sale_id'].astype(str).str.startswith('R')
+            return_count = df['is_return'].sum()
+            sale_count = (~df['is_return']).sum()
+            logger.info(f"Identified {return_count} returns and {sale_count} sales based on saleID")
+        else:
+            # Fallback to negative total_price detection if saleID not available
+            if 'total_price' in df.columns:
+                df['is_return'] = df['total_price'] < 0
+                logger.warning("saleID not available, using total_price < 0 for return detection")
+            else:
+                df['is_return'] = False
+        
+        # Add quantity with proper sign (negative for returns)
         df['quantity'] = 1
+        df.loc[df['is_return'], 'quantity'] = -1  # Returns have negative quantity
+        
+        # Apply return logic to financial fields (make returns negative for accounting)
+        return_mask = df['is_return']
+        financial_fields = ['total_price', 'original_price', 'amount_for_pay', 'payment_sale_amount', 'price_with_discount']
+        for field in financial_fields:
+            if field in df.columns:
+                # Make returns negative if they're not already (some APIs might already send negative values)
+                df.loc[return_mask & (df[field] > 0), field] = -df.loc[return_mask & (df[field] > 0), field]
         
         # Calculate commission (difference between total_price and amount_for_pay)
+        # This will be negative for returns, which is correct for accounting
         if 'total_price' in df.columns and 'amount_for_pay' in df.columns:
             df['sales_commission'] = df['total_price'] - df['amount_for_pay']
-            # Handle negative commissions (returns)
             df['sales_commission'] = df['sales_commission'].fillna(0)
         
         # Add sale_amount for compatibility (use amount_for_pay as seller's net amount)
@@ -532,10 +564,9 @@ class WildberriesAPI:
         if 'current_stock' not in df.columns:
             df['current_stock'] = 0
         
-        # Filter out negative total_price (returns) if needed for analysis
-        # Note: Keep returns for complete data, but mark them
-        if 'total_price' in df.columns:
-            df['is_return'] = df['total_price'] < 0
+        # Add transaction type for clarity
+        if 'transaction_type' not in df.columns:
+            df['transaction_type'] = df['is_return'].map({True: 'Return', False: 'Sale'})
         
         logger.info(f"Processed {len(df)} sales records")