spree_delhivery 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '05580fdecdbb22dca647a7f073e15bae3ccc34a15b563fbced26b05f384d3b82'
+  data.tar.gz: a4dee0340ac7ac8587ec7df82ed266999369f080ae658216a42307f45d1753fe
+SHA512:
+  metadata.gz: 1563cee16ea41246edf09ea656a80fb1420796c69e6758c6b7b4a51d8a49715787f9fa9bfb16e3df933d298b56ad1250c9b87fa57d4af10f1902fecd10d6fc2b
+  data.tar.gz: 2a0cd1fd6fc233f5301903934b4e56ab67c094e63874c407b984385e18fdc7916a92afa0fe35ca3e9fc8d1863c9bb50925348f14f4d67578da5b523276069052

data/README.md

@@ -0,0 +1,175 @@
+# Spree Delhivery Integration
+
+<img width="300" height="auto" alt="delhivery Header" src="https://github.com/user-attachments/assets/c3fb2919-a732-4719-905a-54d202380703" /><br>
+
+This extension provides a comprehensive integration between **Spree Commerce** and **Delhivery Logistics**. It streamlines your shipping workflow by allowing you to generate waybills, schedule pickups, print labels, and track shipments directly from the Spree Admin panel. It also enhances the customer experience with a storefront delivery availability widget.
+
+## 🚀 Key Features
+
+### 📦 Admin Logistics & Fulfillment
+* **Live Shipping Rates:** Automatically calculates shipping costs based on product weight (volumetric vs actual) and distance.
+* **One-Click Manifesting:** Generate Delhivery Waybills and tracking numbers directly from the Shipment card.
+* **Label Printing:** Download and print official PDF shipping labels (AWB).
+* **Pickup Scheduling:** Schedule carrier pickups for specific dates and times directly from the Admin UI.
+* **Tracking Sync:** Real-time status updates (e.g., *In Transit, Out for Delivery, Delivered, RTO*) displayed with color-coded badges.
+* **Cancellation:** Void/Cancel waybills before pickup directly from Spree.
+
+### 📍 Warehouse Management (Geolocation)
+* **Interactive Map:** Upgraded Stock Location form with a **Leaflet.js** map.
+* **Pinpoint Accuracy:** Search for cities or drag the pin to set precise Latitude/Longitude for accurate pickup calculations.
+* **Auto-Fill:** Automatically captures coordinates to ensure accurate logistics routing.
+
+### 🛍️ Storefront Experience (PDP Widget)
+* **Delivery Checker:** Users can enter their Pincode to check serviceability.
+* **Smart Location Detection:** improved logic to detect and display **"City, District, State"** (e.g., *Bardoli, Surat, Gujarat*) instead of just the post office name.
+* **Estimated Delivery Date (EDD):** Shows dynamic delivery dates based on Delhivery TAT API.
+* **Countdown Timer:** "Order within 2 hrs 30 mins for delivery by Tuesday" logic.
+* **Customizable UI:** Admin controls for widget colors, headings, and placeholder text.
+
+---
+
+## 🛠 Installation
+
+1. Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'spree_delhivery', github: 'umeshravani/spree_delhivery'
+```
+2. Install the Gem:
+
+```ruby
+bundle install
+```
+3. Run the installation generator:
+
+   • This installs migrations.<br>
+   • Runs migrations (optional).<br>
+   • Seeds Shipping Methods: Automatically creates "Delhivery Surface" and "Delhivery Express" shipping methods with correct preferences.
+
+```ruby
+bundle exec rails g spree_delhivery:install
+```
+<br>
+
+ ## ⚙️ Configuration
+ 
+ ### 1. General Settings
+  
+  Go to Admin Panel -> Integrations -> Delhivery.
+  
+<img width="279" height="332" alt="Integrations Page" src="https://github.com/user-attachments/assets/3da6c1be-92b3-410c-ab00-f0bb27e79099" /><br>
+  
+
+  • API Token: Enter your Delhivery API Token (masked for security).
+
+  • Production Mode: Check this box for live shipments. Uncheck for Sandbox/Testing.
+
+  • Pickup Location: Crucial. This must match the exact warehouse name registered in your Delhivery Dashboard.
+
+  • Unit Mapping: Select how your store stores Weight (kg/lbs) and Dimensions (cm/in) so the calculator converts them correctly for the API.<br>
+
+  <img width="500" height="auto" alt="Integration Settings Delhivery" src="https://github.com/user-attachments/assets/d74ff3ca-13c2-4ff4-9465-2f7e483a9955" /><br>
+
+
+  ### 2. Shipping Methods
+  
+   If you didn't seed them during install, create a Shipping Method in Admin -> Shipping -> Shipping Methods:
+
+  • Calculator: Select Delhivery Live Rate.
+
+  • Service Mode: Enter Surface or Express.
+
+  • Tracking URL: https://www.delhivery.com/track/package/:tracking <br>
+
+  <img width="800" height="auto" alt="Shipping Methods (Auto Added)" src="https://github.com/user-attachments/assets/017a6fda-3059-4bfc-97aa-29f21674e1b4" /><br>
+
+
+  ### 3. Widget Configuration
+  
+  Go to Admin -> Content -> Page Blocks -> Delhivery EDD.
+
+  • Customize the Heading, Button Text, and Colors.
+
+  • Set the Cutoff Time (e.g., 2:00 PM) to control the "Order within..." countdown timer.<br>
+
+  <img width="800" height="auto" alt="Delhivery EDD Widget" src="https://github.com/user-attachments/assets/8802836d-ad0c-4ccb-9bad-629a508322ae" /><br>
+
+
+ ## 🖥️ Usage Guide
+ 
+  ### Fulfillment Workflow (Admin)
+  
+  1. Navigate to Orders -> Order # -> Shipments.
+
+  2. You will see the unified Delhivery Toolbar on the shipment card.
+
+  3. Ship: Click "Ship with Delhivery". This generates the AWB.
+
+  4. Print: Click the Printer icon to get the PDF label.
+
+  5. Pickup: Click the Truck icon to open the Schedule Pickup Modal. Select date/time and confirm.
+
+  6. Track: Click the Refresh icon to pull the latest status from Delhivery.<br>
+
+  
+  <img width="800" height="auto" alt="Orders Page (Unshipped Order)" src="https://github.com/user-attachments/assets/1c1527b3-4096-4b26-a594-5ebe3f528677" /><br>
+
+  <img width="800" height="560" alt="Shipped Order (Orders Page)" src="https://github.com/user-attachments/assets/9dc19710-e5b9-4e69-a862-ea7d02d1cb13" /><br>
+
+
+ ### Storefront Widget
+ 
+  To display the Pincode checker on your product page, add this helper to your products/show view file:
+
+  1. Find your Partial file Example: 
+  ```
+    'app/views/themes/default/spree/page_sections/_product_details.html.erb'
+  ```
+Note: If you dont find this file inside your spree's directory, You can [Download](https://github.com/spree/spree/blob/df400d3557c244ec3829f175a27f3990cdeb2452/storefront/app/views/themes/default/spree/page_sections/_product_details.html.erb#L4) this directly from Spree's Github and place it exactly inside your Spree's directory
+
+  2. Place this Rendering Code:
+  
+   ```ruby
+    <% when 'Spree::PageBlocks::Products::DelhiveryEdd' %>
+    <%= block.render(self, product: product) %> 
+   ```
+  3. Exactly below this part:
+   ```
+    <% when 'Spree::PageBlocks::Products::Description' %>
+   ```
+
+ ## 🧩 Technical Details
+ 
+ • Maps: Uses OpenStreetMap + Leaflet.js (No Google Maps API key required).
+
+
+ • Turbo Support: Fully compatible with Turbo Drive; map re-initializes correctly on page transitions.
+
+
+ • Styling: Uses Tailwind CSS utility classes matching Spree's default admin theme.
+
+
+ • Calculations: Handles volumetric weight calculation (L x W x H) / 5000 automatically based on your unit settings.<br>
+
+ <img width="800" height="auto" alt="Stock Locations Page (Delhivery Settings)" src="https://github.com/user-attachments/assets/729f5abf-afe7-430f-87ef-93a52997e0c4" /><br>
+
+
+ ## 🛒 Checkout Page Auto-Calculation
+ 
+ Eliminate guesswork and undercharging for shipping. This extension integrates directly into the Spree Checkout flow (Delivery Step) to provide accurate costs instantly.
+
+ • Live API Calls: As soon as a customer enters their shipping address, the calculator queries the Delhivery API for real-time rates based on the specific source and destination pincodes.
+
+ • Volumetric Weight Logic: Automatically calculates (Length x Width x Height) / 5000 and compares it against the actual weight. The API requests the rate based on whichever is higher, ensuring you never lose money on bulky, lightweight items.
+
+ • Performance Caching: Rate responses are cached for 15 minutes to ensure fast page loads and prevent hitting API rate limits during high traffic.
+
+ • Handling Fee Support: Easily add a fixed handling/packing fee on top of the live carrier rate via the Shipping Method preferences.<br>
+ 
+ <br><img width="800" height="auto" alt="Checkout Page (Auto Calculate Shipping Costs)" src="https://github.com/user-attachments/assets/aa983ad0-638a-4140-971f-f1f56dead652" />
+
+
+
+ ## 🤝 Contributing
+ 
+   Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration.

data/Rakefile

@@ -0,0 +1,21 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+require 'spree/testing_support/extension_rake'
+
+RSpec::Core::RakeTask.new
+
+task :default do
+  if Dir['spec/dummy'].empty?
+    Rake::Task[:test_app].invoke
+    Dir.chdir('../../')
+  end
+  Rake::Task[:spec].invoke
+end
+
+desc 'Generates a dummy app for testing'
+task :test_app do
+  ENV['LIB_NAME'] = 'spree_delhivery'
+  Rake::Task['extension:test_app'].invoke
+end

data/app/assets/config/spree_delhivery_manifest.js

@@ -0,0 +1,4 @@
+//= link_tree ../images
+//= link_tree ../../javascript/spree_delhivery/controllers .js
+//= link_tree ../../../vendor/javascript .js
+//= link_tree ../../../vendor/stylesheets .css

data/app/assets/images/payment_icons/delhivery.svg

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 38 24" width="38" height="24" aria-labelledby="pi-payu">
+  <path opacity=".07" d="M35 0H3C1.3 0 0 1.3 0 3v18c0 1.7 1.4 3 3 3h32c1.7 0 3-1.3 3-3V3c0-1.7-1.4-3-3-3"/>
+  <path fill="#fff" d="M35 1c1.1 0 2 .9 2 2v18c0 1.1-.9 2-2 2H3c-1.1 0-2-.9-2-2V3c0-1.1.9-2 2-2z"/>
+  <style>.st0{opacity:7.000000e-02;enable-background:new}.st1{fill:#fff}</style>
+  <path class="st0" d="M35 0H3C1.3 0 0 1.3 0 3v18c0 1.7 1.4 3 3 3h32c1.7 0 3-1.3 3-3V3c0-1.7-1.4-3-3-3"/>
+  <path class="st1" d="M35 1c1.1 0 2 .9 2 2v18c0 1.1-.9 2-2 2H3c-1.1 0-2-.9-2-2V3c0-1.1.9-2 2-2z"/>
+  <path class="st0" d="M35 0H3C1.3 0 0 1.3 0 3v18c0 1.7 1.4 3 3 3h32c1.7 0 3-1.3 3-3V3c0-1.7-1.4-3-3-3"/>
+  <path class="st1" d="M35 1c1.1 0 2 .9 2 2v18c0 1.1-.9 2-2 2H3c-1.1 0-2-.9-2-2V3c0-1.1.9-2 2-2z"/>
+  <path d="M 10.73 6.106 C 10.73 5.449 11.262 4.917 11.917 4.917 L 26.172 4.917 C 26.827 4.917 27.359 5.449 27.359 6.106 L 10.73 6.106 Z M 19.044 15.609 C 20.873 15.609 22.016 13.628 21.102 12.045 C 20.678 11.31 19.894 10.856 19.044 10.856 C 17.216 10.856 16.073 12.837 16.987 14.421 C 17.411 15.155 18.195 15.609 19.044 15.609 Z" style="stroke-width: 50; fill: rgb(228, 77, 75);"/>
+  <path d="M 9.542 8.48 C 9.542 7.824 10.073 7.293 10.73 7.293 L 27.359 7.293 C 28.016 7.293 28.547 7.824 28.547 8.48 L 28.547 17.983 C 28.547 18.64 28.016 19.172 27.359 19.172 L 10.73 19.172 C 10.073 19.172 9.542 18.64 9.542 17.983 L 9.542 8.48 Z M 13.106 8.48 C 13.106 9.794 12.041 10.856 10.73 10.856 L 10.73 15.609 C 12.041 15.609 13.106 16.672 13.106 17.983 L 24.983 17.983 C 24.983 16.672 26.048 15.609 27.359 15.609 L 27.359 10.856 C 26.048 10.856 24.983 9.794 24.983 8.48 L 13.106 8.48 Z" style="stroke-width: 50; fill: rgb(35, 31, 32);"/>
+</svg>

data/app/assets/images/payment_icons/delhivery_cod.svg

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 38 24" width="38" height="24" aria-labelledby="pi-payu">
+  <path opacity=".07" d="M35 0H3C1.3 0 0 1.3 0 3v18c0 1.7 1.4 3 3 3h32c1.7 0 3-1.3 3-3V3c0-1.7-1.4-3-3-3"/>
+  <path fill="#fff" d="M35 1c1.1 0 2 .9 2 2v18c0 1.1-.9 2-2 2H3c-1.1 0-2-.9-2-2V3c0-1.1.9-2 2-2z"/>
+  <style>.st0{opacity:7.000000e-02;enable-background:new}.st1{fill:#fff}</style>
+  <path class="st0" d="M35 0H3C1.3 0 0 1.3 0 3v18c0 1.7 1.4 3 3 3h32c1.7 0 3-1.3 3-3V3c0-1.7-1.4-3-3-3"/>
+  <path class="st1" d="M35 1c1.1 0 2 .9 2 2v18c0 1.1-.9 2-2 2H3c-1.1 0-2-.9-2-2V3c0-1.1.9-2 2-2z"/>
+  <path class="st0" d="M35 0H3C1.3 0 0 1.3 0 3v18c0 1.7 1.4 3 3 3h32c1.7 0 3-1.3 3-3V3c0-1.7-1.4-3-3-3"/>
+  <path class="st1" d="M35 1c1.1 0 2 .9 2 2v18c0 1.1-.9 2-2 2H3c-1.1 0-2-.9-2-2V3c0-1.1.9-2 2-2z"/>
+  <path d="M 10.73 6.106 C 10.73 5.449 11.262 4.917 11.917 4.917 L 26.172 4.917 C 26.827 4.917 27.359 5.449 27.359 6.106 L 10.73 6.106 Z M 19.044 15.609 C 20.873 15.609 22.016 13.628 21.102 12.045 C 20.678 11.31 19.894 10.856 19.044 10.856 C 17.216 10.856 16.073 12.837 16.987 14.421 C 17.411 15.155 18.195 15.609 19.044 15.609 Z" style="stroke-width: 50; fill: rgb(228, 77, 75);"/>
+  <path d="M 9.542 8.48 C 9.542 7.824 10.073 7.293 10.73 7.293 L 27.359 7.293 C 28.016 7.293 28.547 7.824 28.547 8.48 L 28.547 17.983 C 28.547 18.64 28.016 19.172 27.359 19.172 L 10.73 19.172 C 10.073 19.172 9.542 18.64 9.542 17.983 L 9.542 8.48 Z M 13.106 8.48 C 13.106 9.794 12.041 10.856 10.73 10.856 L 10.73 15.609 C 12.041 15.609 13.106 16.672 13.106 17.983 L 24.983 17.983 C 24.983 16.672 26.048 15.609 27.359 15.609 L 27.359 10.856 C 26.048 10.856 24.983 9.794 24.983 8.48 L 13.106 8.48 Z" style="stroke-width: 50; fill: rgb(35, 31, 32);"/>
+</svg>

data/app/controllers/spree/admin/delhivery_controller.rb

@@ -0,0 +1,190 @@
+module Spree
+  module Admin
+    class DelhiveryController < Spree::Admin::BaseController
+      # Skip load_shipment for create_pickup because that action uses a StockLocation ID
+      before_action :load_shipment, except: [:create_pickup]
+
+      def create_pickup
+        stock_id = params[:id]
+        @stock_location = if stock_id.to_s.start_with?('stl_') && Spree::StockLocation.respond_to?(:find_by_prefix_id)
+                            Spree::StockLocation.find_by_prefix_id(stock_id)
+                          else
+                            Spree::StockLocation.find(stock_id)
+                          end
+        
+        service = SpreeDelhivery::PickupService.new(@stock_location, count: 5)
+        result = service.call
+
+        if result.success?
+          flash[:success] = result.message
+        else
+          flash[:error] = "Pickup Failed: #{result.message}"
+        end
+        
+        # Turbo Fix for seamless UI updates
+        redirect_to spree.edit_admin_stock_location_path(@stock_location), status: :see_other
+      end
+  
+      def create_manifest
+        sender = SpreeDelhivery::ShipmentSender.new(@shipment)
+        result = sender.call
+
+        if result.success?
+          # Force the shipment from 'pending' directly to 'shipped' on a successful API response
+          ActiveRecord::Base.transaction do
+            @shipment.update_columns(
+              state: 'shipped',
+              shipped_at: @shipment.shipped_at || Time.current
+            )
+            # Log all inventory units out of warehouse stock management
+            @shipment.inventory_units.where.not(state: 'shipped').update_all(state: 'shipped')
+            # Trigger downstream order pipeline status calculations
+            @shipment.order.updater.update
+          end
+
+          flash[:success] = "Shipment Manifested! Waybill: #{@shipment.delhivery_waybill}"
+        else
+          flash[:error] = "Delhivery Error: #{result.error}"
+        end
+
+        # Turbo Fix
+        redirect_to spree.edit_admin_order_path(@shipment.order), status: :see_other
+      end
+
+      def delhivery_cancel
+        result = SpreeDelhivery::ShipmentCanceler.new(@shipment).call
+
+        if result.success?
+          flash[:success] = "Shipment Waybill Voided Successfully."
+        else
+          flash[:error] = "Delhivery Error: #{result.error}"
+        end
+
+        # Turbo Fix
+        redirect_to spree.edit_admin_order_path(@shipment.order), status: :see_other
+      end
+
+      def download_label
+        if @shipment.delhivery_label_url.present?
+          redirect_to @shipment.delhivery_label_url, allow_other_host: true
+        else
+          client = SpreeDelhivery::Client.new
+          label_res = client.fetch_label(@shipment.delhivery_waybill)
+          
+          if label_res['packages'].present? && label_res['packages'][0]['pdf_download_link'].present?
+             url = label_res['packages'][0]['pdf_download_link']
+             @shipment.update(delhivery_label_url: url)
+             redirect_to url, allow_other_host: true
+          else
+             flash[:error] = "Label not generated yet. Please try again later."
+             redirect_to spree.edit_admin_order_path(@shipment.order), status: :see_other
+          end
+        end
+      end
+      
+      def sync_tracking
+        result = SpreeDelhivery::ShipmentTracker.new(@shipment).call
+        current_status = result.status.to_s.upcase
+
+        raw_data_string = result.data.inspect.upcase if result.data
+        
+        is_cancelled = current_status.include?("CANCEL") || 
+                       current_status.include?("VOID") || 
+                       (raw_data_string && (raw_data_string.include?("CANCEL") || raw_data_string.include?("VOID")))
+
+        if is_cancelled
+          ActiveRecord::Base.transaction do
+            @shipment.update_columns(
+              delhivery_waybill: nil, tracking: nil, tracking_status: "CANCELLED",
+              state: "ready", shipped_at: nil
+            )
+            @shipment.inventory_units.update_all(state: "on_hand")
+            @shipment.order.updater.update
+          end
+
+          flash[:success] = "Remote cancellation detected. Waybill cleared and shipment reset to Ready."
+          redirect_to spree.edit_admin_order_path(@shipment.order), status: :see_other
+          return
+        end
+
+        # THE COD AUTO-CAPTURE ENGINE
+        is_delivered = current_status.include?("DELIVERED") || 
+                       (raw_data_string && raw_data_string.include?("DELIVERED"))
+
+        if is_delivered
+          ActiveRecord::Base.transaction do
+            # Find any pending COD payments on this order and capture them
+            @shipment.order.payments.valid.where(state: ['pending', 'checkout']).each do |payment|
+              if payment.payment_method&.type == 'Spree::PaymentMethod::DelhiveryCod'
+                payment.capture!
+                Rails.logger.info "[Delhivery] Auto-captured COD Payment #{payment.number} for Order #{@shipment.order.number}"
+              end
+            end
+            
+            # Crash Prevention: Spree doesn't natively support a 'delivered' state-machine path.
+            # We explicitly update columns to avoid NoMethodError on deliver!
+            @shipment.update_columns(
+              state: 'shipped',
+              tracking_status: 'DELIVERED',
+              shipped_at: @shipment.shipped_at || Time.current
+            )
+            
+            # Cleanly verify inventory states match deployment metrics
+            @shipment.inventory_units.where.not(state: 'shipped').update_all(state: 'shipped')
+            
+            # Force downstream state engine recalculations (Clears "Balance Due" badge to green Paid)
+            @shipment.order.updater.update
+          end
+
+          flash[:success] = "Shipment Delivered! COD Payment automatically captured and reconciled."
+          redirect_to spree.edit_admin_order_path(@shipment.order), status: :see_other
+          return
+        end
+
+        # STANDARD TRACKING UPDATE
+        if result.success?
+          @shipment.update_column(:tracking_status, current_status)
+          flash[:success] = "Status Updated: #{current_status}"
+        else
+          flash[:error] = "Tracking Error: #{result.error || current_status}"
+        end
+        
+        # Turbo Fix
+        redirect_to spree.edit_admin_order_path(@shipment.order), status: :see_other
+      end
+
+      private
+
+      def load_shipment
+        shipment_param = params[:shipment_id] || params[:id]
+        Rails.logger.info "--- [DELHIVERY DEBUG] Processing ID: #{shipment_param} ---"
+      
+        @shipment = nil
+      
+        if shipment_param.to_s.start_with?('ful_')
+          if Spree::Shipment.respond_to?(:find_by_prefix_id)
+            @shipment = Spree::Shipment.find_by_prefix_id(shipment_param)
+          else
+            Rails.logger.error "--- [DELHIVERY WARNING] 'find_by_prefix_id' method is missing! ---"
+          end
+        end
+      
+        @shipment ||= Spree::Shipment.find_by(number: shipment_param)
+      
+        if @shipment.nil? && shipment_param.to_s.match?(/\A\d+\z/)
+          @shipment = Spree::Shipment.find_by(id: shipment_param)
+        end
+      
+        if @shipment.nil?
+          Rails.logger.error "--- [DELHIVERY ERROR] No Shipment found for: #{shipment_param} ---"
+          flash[:error] = "Shipment not found for ID: #{shipment_param}"
+          redirect_to spree.admin_orders_path, status: :see_other
+        end
+      rescue => e
+        Rails.logger.error "--- [DELHIVERY FATAL] #{e.class}: #{e.message} ---"
+        flash[:error] = "An unexpected error occurred: #{e.message}"
+        redirect_to spree.admin_orders_path, status: :see_other
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/delhivery_returns_controller.rb

@@ -0,0 +1,82 @@
+module Spree
+  module Admin
+    class DelhiveryReturnsController < Spree::Admin::BaseController
+      
+      def create_pickup
+        @return_auth = Spree::ReturnAuthorization.find(params[:id])
+        
+        # 1. Validation: Warehouse Name
+        if @return_auth.stock_location.delhivery_warehouse_name.blank?
+          flash[:error] = "Delhivery Warehouse Name is missing in Stock Location settings."
+          redirect_back(fallback_location: admin_order_return_authorizations_path(@return_auth.order))
+          return
+        end
+
+        # 2. Capture Options from Modal
+        extra_options = {
+          brand: params[:brand],
+          category: params[:category]
+        }
+
+        begin
+          client = SpreeDelhivery::Client.new
+          
+          # 3. Call Service
+          # Note: Ensure your client.rb's create_return_request accepts the second argument (options)
+          response = client.create_return_request(@return_auth, extra_options)
+
+          # 4. Normalize Response
+          resp = response.is_a?(HTTParty::Response) ? response.parsed_response : response
+          Rails.logger.info "Delhivery Return Response: #{resp.inspect}"
+
+          # 5. Success Check
+          is_success = false
+          
+          # Check 'packages' array (Standard Delhivery Response)
+          if resp['packages'].present? && resp['packages'].is_a?(Array)
+             first_pkg = resp['packages'].first
+             # Success if status is 'Success' OR if we got a valid waybill number
+             if first_pkg['status'] == 'Success' || first_pkg['waybill'].to_s.length > 5
+               is_success = true
+             end
+          end
+
+          if is_success
+             waybill = resp['packages'].first['waybill']
+             ref_id = resp['packages'].first['ref_id']
+             
+             # Update Database
+             @return_auth.update_columns(
+               delhivery_waybill: waybill,
+               delhivery_ref_id: ref_id
+             )
+             
+             flash[:success] = "Reverse Pickup Scheduled! Waybill: #{waybill}"
+          else
+             # 6. Granular Error Handling
+             error_text = "Unknown Error"
+             
+             if resp['detail'].present?
+                error_text = "Auth/Permission Error: #{resp['detail']}"
+             elsif resp['rmk'].present?
+                error_text = resp['rmk'] 
+             elsif resp['packages'].present? && resp['packages'].first
+                pkg = resp['packages'].first
+                error_text = pkg['remarks'] || pkg['status'] || "Package Error"
+             elsif resp['error'].present?
+                error_text = resp['error'].to_s
+             end
+             
+             flash[:error] = "Delhivery Error: #{error_text}"
+          end
+
+        rescue StandardError => e
+          flash[:error] = "Connection Exception: #{e.message}"
+        end
+
+        redirect_back(fallback_location: admin_order_return_authorizations_path(@return_auth.order))
+      end
+
+    end
+  end
+end

data/app/controllers/spree/admin/fulfillments_controller.rb

@@ -0,0 +1,117 @@
+module Spree
+  module Admin
+    class FulfillmentsController < Spree::Admin::BaseController
+      before_action :load_order_and_shipment
+
+      def new
+        # 1. Fetch available shipping rates for the dropdown
+        @available_methods = Spree::ShippingMethod.all.filter_map do |method|
+          begin
+            rate = @shipment.shipping_rates.find_by(shipping_method_id: method.id)
+            cost = rate&.cost || method.calculator.compute(@shipment) || 0
+            display_cost = Spree::Money.new(cost, currency: @order.currency).to_s
+            
+            { id: method.id, name: method.name, cost: cost, display_cost: display_cost }
+          rescue NotImplementedError, StandardError
+            nil
+          end
+        end
+
+        # 2. Pre-calculate Live Delhivery Payload Diagnostics for the UI Audit Box
+        if defined?(Spree::Integrations::Delhivery) && Spree::Integrations::Delhivery.active.exists?
+          @integration = Spree::Integrations::Delhivery.active.first
+          
+          # Compute Weight
+          raw_weight = @shipment.line_items.sum { |li| (li.variant.weight || 0) * li.quantity }
+          raw_weight = 0.5 if raw_weight.zero?
+          @weight_unit = @integration.preferred_store_weight_unit || 'kg'
+          @weight_in_grams = case @weight_unit
+                             when 'kg' then raw_weight * 1000
+                             when 'lbs' then raw_weight * 453.592
+                             when 'g' then raw_weight
+                             else raw_weight * 1000
+                             end.to_i
+
+          # Compute Volumetric Dimensions (Stacking Rule)
+          max_l = 0; max_w = 0; total_h = 0
+          @shipment.line_items.each do |line_item|
+            v = line_item.variant
+            q = line_item.quantity
+            max_l = [max_l, (v.depth || 10).to_f].max
+            max_w = [max_w, (v.width || 10).to_f].max
+            total_h += ((v.height || 10).to_f * q)
+          end
+
+          @dim_unit = @integration.preferred_store_dimension_unit || 'cm'
+          @dims_cm = [max_l, max_w, total_h].map do |val|
+            case @dim_unit
+            when 'cm' then val
+            when 'in' then val * 2.54
+            when 'm' then val * 100
+            when 'mm' then val / 10.0
+            else val
+            end.round(1)
+          end
+
+          # Auto-assign packaging recommendation baseline
+          # Delhivery Flyers are restricted to small sizes and weights under 2kg (2000g)
+          @recommended_packaging = (@weight_in_grams > 2000 || @dims_cm[0] > 30 || @dims_cm[1] > 30) ? "Carton Box" : "Flyer"
+        end
+        
+        render layout: false
+      end
+
+      def create
+        if params[:shipping_method_id].present?
+          new_method = Spree::ShippingMethod.find_by(id: params[:shipping_method_id])
+          if new_method && new_method.id != @shipment.selected_shipping_rate&.shipping_method_id
+            new_rate = @shipment.shipping_rates.find_or_initialize_by(shipping_method_id: new_method.id)
+            if new_rate.new_record?
+              new_rate.cost = new_method.calculator.compute(@shipment) || 0
+              new_rate.save!
+            end
+            @shipment.shipping_rates.update_all(selected: false)
+            new_rate.update_column(:selected, true)
+            @shipment.update_column(:cost, new_rate.cost)
+            @order.update_with_updater!
+          end
+        end
+
+        if params[:fulfillment_type] == 'manual'
+          ActiveRecord::Base.transaction do
+            @shipment.update_columns(
+              tracking: params[:tracking_number],
+              state: 'shipped',
+              shipped_at: @shipment.shipped_at || Time.current
+            )
+            @shipment.inventory_units.where.not(state: 'shipped').update_all(state: 'shipped')
+            @order.updater.update
+          end
+          Spree::ShipmentMailer.shipped_email(@shipment.id).deliver_later rescue nil
+          carrier_name = @shipment.reload.selected_shipping_rate&.name || "Manual Carrier"
+          flash[:success] = "Tracking updated successfully via #{carrier_name}."
+          redirect_to spree.edit_admin_order_path(@order), status: :see_other
+
+        elsif params[:fulfillment_type] == 'delhivery'
+          # Production Feature: Track layout type form input if selected manually
+          if params[:delhivery_packaging_type].present?
+            # Store package selection if custom meta columns exist on your shipment
+            @shipment.update_column(:delhivery_response_data, (@shipment.delhivery_response_data || {}).merge(selected_packaging: params[:delhivery_packaging_type]))
+          end
+          redirect_to spree.delhivery_manifest_admin_shipment_path(@shipment), status: :temporary_redirect
+        else
+          flash[:error] = "Invalid fulfillment type selected."
+          redirect_to spree.edit_admin_order_path(@order), status: :see_other
+        end
+      end
+
+      private
+
+      def load_order_and_shipment
+        @order = Spree::Order.find_by!(number: params[:order_id])
+        # Accommodate direct collection scoping lookups
+        @shipment = @order.shipments.find_by(number: params[:shipment_id]) || Spree::Shipment.find_by!(number: params[:shipment_id])
+      end
+    end
+  end
+end