Tradhox Shipping Microservice (shippingservice)

📌 Executive Overview

shippingservice is an enterprise-grade Django microservice and REST API Gateway that unifies and manages integrations with the Shadowfax (SFX) Logistics Platform. It provides a single, high-performance integration layer for all Tradhox services (e.g., seller_central_backend, marketplace platforms, order management systems).

Core Architecture & Capabilities

sequenceDiagram
    autonumber
    participant Client as Tradhox Microservice (e.g. seller_central_backend)
    participant Gateway as Shipping Microservice (shippingservice)
    participant DB as PostgreSQL (cisystem)
    participant SFX as Shadowfax Logistics Platform (SFX API)

    Client->>Gateway: POST /api/v1/forward/create-order/
    Gateway->>SFX: Forward Order Payload (v3/clients/orders/)
    SFX-->>Gateway: Response (AWB & Order Status)
    Gateway->>DB: Audit Log Entry (ActivityLog)
    Gateway-->>Client: Unified JSON Response (AWB & Status)
    
    SFX-->>Gateway: POST /api/webhook/ (Real-time AWB Status Callback)
    Gateway->>DB: Log Webhook Event

Key Features

• Forward Logistics: Pincode serviceability checks, pre-allocated AWB numbers, Marketplace seller pickup orders, Warehouse hub dispatch orders, V4 real-time tracking, order cancellations, support escalations, digital Proof of Delivery (POD), and dynamic doorstep COD UPI QR code generation.
• Reverse Logistics: Reverse pincode serviceability, reverse AWB pre-allocation, customer doorstep return requests with configurable Doorstep Quality Check (QC) rules (brand match, IMEI/serial number validation, physical condition, photo requirements), V4 reverse tracking, and Proof of Pickup (POP).
• Automated Audit Logging: Every outbound request to Shadowfax and every incoming webhook callback is stored in PostgreSQL (ActivityLog) capturing headers, request payload, status code, response time in ms, and response payload.
• Visual Testing Dashboard: Clean dark-mode web interface at /checker/ (Multi-Carrier Route Checker), /forward/, /reverse/, /label/, /logs/, and /webhooks/ for interactive debugging and live inspection.

---

🌐 Environments & Base URLs

Environment	Base URL	Database Target (cisystem)	Description
Beta / Staging	https://beta-shipping.tradhox.com	shippingservice_beta	Active sandbox environment for testing integrations
Production	https://shipping.tradhox.com	shippingservice_prod	Production environment linked to live carrier endpoints
Local Dev	http://localhost:8000	PostgreSQL (shippingservice_prod / local DB)	Local development instance

---

🚀 REST API Reference (/api/v1/)

External services consume these REST API endpoints using JSON payloads over HTTP/HTTPS.

---

0. Dynamic Carrier Allocation & Routing APIs

0.1 Check All Carrier Availability (First-Mile & Last-Mile)

Evaluate first-mile origin pickup hub and last-mile destination drop serviceability, COD availability, and freight rates across all integrated carriers (Shadowfax, Delhivery, Ekart) in parallel.

• Interactive UI: http://localhost:8000/checker/ (or https://beta-shipping.tradhox.com/checker/)
• Endpoint: POST /api/v1/carrier/check-availability/
• Request Body:

{
  "pickup_pincode": "560077",
  "drop_pincode": "110009",
  "payment_type": "Prepaid",
  "weight": 500,
  "use_mock": false
}

• Response (200 OK):

{
  "status": "success",
  "pickup_pincode": "560077",
  "drop_pincode": "110009",
  "payment_type": "Prepaid",
  "best_carrier": {
    "selected": true,
    "carrier": "DELHIVERY",
    "cost": 35.0,
    "reason": "Selected DELHIVERY as lowest cost carrier (Cost: ₹35.0)"
  },
  "carriers": {
    "SHADOWFAX": {
      "carrier": "SHADOWFAX",
      "serviceable": true,
      "cod_available": true,
      "estimated_cost": 60.0,
      "first_mile": {
        "serviceable": true,
        "pincode": "560077",
        "city": "Bengaluru",
        "state": "Karnataka",
        "hub_active": true,
        "message": "First-mile pickup serviceable in Bengaluru, Karnataka"
      },
      "last_mile": {
        "serviceable": true,
        "pincode": "110009",
        "city": "Delhi",
        "state": "Delhi",
        "cod_available": true,
        "message": "Last-mile delivery serviceable in Delhi, Delhi"
      }
    },
    "DELHIVERY": {
      "carrier": "DELHIVERY",
      "serviceable": true,
      "cod_available": true,
      "estimated_cost": 35.0,
      "first_mile": {
        "serviceable": true,
        "pincode": "560077",
        "city": "Bengaluru",
        "state": "Karnataka",
        "reverse_pickup": true,
        "message": "First-mile pickup serviceable in Bengaluru, Karnataka"
      },
      "last_mile": {
        "serviceable": true,
        "pincode": "110009",
        "city": "North Delhi",
        "state": "Delhi",
        "cod_available": true,
        "message": "Last-mile delivery serviceable in North Delhi, Delhi"
      }
    }
  }
}

0.2 Smart Auto-Dispatch Order

Check multi-carrier availability and automatically dispatch order to the optimal serviceable carrier (with configurable preferred carrier and fallback).

• Endpoint: POST /api/v1/carrier/auto-dispatch/
• Request Body:

{
  "preferred_carrier": "SHADOWFAX",
  "allow_fallback": true,
  "use_mock": true,
  "payload": {
    "order_details": { "client_order_id": "ORD-AUTO-101", "actual_weight": 500, "payment_mode": "Prepaid" },
    "customer_details": { "name": "Customer Name", "phone": "9876543210", "pincode": "110009" },
    "pickup_details": { "name": "Warehouse Name", "pincode": "560077" }
  }
}

• Response (201 Created):

{
  "status": "success",
  "message": "Order created successfully via Shadowfax (Auto-Allocated)",
  "assigned_carrier": "SHADOWFAX",
  "selection_reason": "Selected SHADOWFAX as primary carrier",
  "data": {
    "client_order_id": "ORD-AUTO-101",
    "awb_number": "SFX175992831",
    "order_status": "new"
  }
}

---

1. Healthcheck

Check service availability and system health.

• Endpoint: GET /api/v1/health/
• Headers: Accept: application/json
• Response (200 OK):

{
  "status": "healthy",
  "service": "Shadowfax Shipping Microservice",
  "timestamp": 1790352623.926
}

---

2. Forward Logistics APIs

2.1 Check Pincode Serviceability

Determine if Shadowfax serves specified destination/pickup pincodes for Express delivery and COD.

• Endpoint: POST /api/v1/forward/serviceability/
• Request Body:

{
  "pincodes": "560077,110009",
  "service": "express",
  "env": "production",
  "use_mock": true
}

• Response (200 OK):

{
  "status": "success",
  "data": {
    "pincodes": [
      {
        "pincode": "560077",
        "city": "Bengaluru",
        "serviceable": true,
        "cod_available": true
      },
      {
        "pincode": "110009",
        "city": "New Delhi",
        "serviceable": true,
        "cod_available": true
      }
    ]
  }
}

---

2.2 Create Forward Delivery Order

Create a new forward delivery order (Marketplace Seller Pickup or Warehouse Hub Dispatch).

• Endpoint: POST /api/v1/forward/create-order/
• Request Body Example:

{
  "env": "production",
  "use_mock": true,
  "payload": {
    "order_details": {
      "client_order_id": "ORD-MKT-2026-101",
      "actual_weight": 750.0,
      "product_value": 1499.0,
      "payment_mode": "COD",
      "cod_amount": 1499.0,
      "order_type": "marketplace"
    },
    "customer_details": {
      "name": "Ananya Sharma",
      "phone": "9876543210",
      "address_line_1": "Flat 402, Sunshine Apartments",
      "pincode": "560038",
      "city": "Bengaluru",
      "state": "Karnataka"
    },
    "pickup_details": {
      "name": "StyleHub Retail Store",
      "phone": "9123456789",
      "address_line_1": "Plot 12, Industrial Area Phase 2",
      "pincode": "560077",
      "city": "Bengaluru",
      "state": "Karnataka"
    },
    "rts_details": {
      "name": "StyleHub Returns Center",
      "phone": "9123456789",
      "address_line_1": "Plot 12, Industrial Area Phase 2",
      "pincode": "560077",
      "city": "Bengaluru",
      "state": "Karnataka"
    },
    "product_details": [
      {
        "sku_name": "Wireless Noise Cancelling Earbuds",
        "sku_code": "SKU-EAR-001",
        "price": 1499.0,
        "quantity": 1
      }
    ]
  }
}

• Response (201 Created):

{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "client_order_id": "ORD-MKT-2026-101",
    "awb_number": "SFX9928374102",
    "order_status": "new"
  }
}

---

2.3 Track Forward Order (V4 API)

Track order lifecycle and rider details using an AWB number.

• Endpoint: GET /api/v1/forward/track/?awb=SFX9928374102
• Response (200 OK):

{
  "status": "success",
  "data": {
    "awb_number": "SFX9928374102",
    "current_status": "out_for_delivery",
    "rider_details": {
      "name": "Rajesh Kumar",
      "phone": "+919876543210"
    },
    "tracking_history": [
      {
        "status": "new",
        "timestamp": "2026-09-25T08:00:00Z",
        "location": "Origin Hub"
      },
      {
        "status": "out_for_delivery",
        "timestamp": "2026-09-25T14:00:00Z",
        "location": "Destination Hub"
      }
    ]
  }
}

---

2.4 Cancel Order

Cancel an unfulfilled forward delivery order.

• Endpoint: POST /api/v1/forward/cancel/
• Request Body:

{
  "payload": {
    "client_order_id": "ORD-MKT-2026-101",
    "awb_number": "SFX9928374102",
    "reason": "Customer requested cancellation prior to pickup"
  }
}

• Response (200 OK):

{
  "status": "success",
  "message": "Order cancelled"
}

---

3. Reverse Logistics APIs

3.1 Check Reverse Serviceability

Verify if reverse pick-up is supported for customer locations.

• Endpoint: POST /api/v1/reverse/serviceability/
• Request Body:

{
  "pincodes": "560103,110009"
}

• Response (200 OK):

{
  "status": "success",
  "data": {
    "pincodes": [
      {
        "pincode": "560103",
        "reverse_pickup_available": true
      }
    ]
  }
}

---

3.2 Create Reverse Pickup Request (Doorstep QC)

Initiate a reverse return pickup request with Quality Check enforcement.

• Endpoint: POST /api/v1/reverse/create-request/
• Request Body Example:

{
  "env": "staging",
  "use_mock": true,
  "payload": {
    "client_request_id": "REV-ORD-2026-8801",
    "actual_weight": 500.0,
    "product_value": 2999.0,
    "pickup_details": {
      "name": "Kavita Reddy",
      "phone": "9876501234",
      "address_line_1": "Apartment 102, Green Glen Layout",
      "pincode": "560103",
      "city": "Bengaluru",
      "state": "Karnataka"
    },
    "return_details": {
      "name": "Tradhox Central Returns Hub",
      "phone": "9811004455",
      "address_line_1": "Logistics Park Warehouse 4B",
      "pincode": "560077",
      "city": "Bengaluru",
      "state": "Karnataka"
    },
    "qc_details": {
      "qc_check": true,
      "brand_name": "SoundCore",
      "item_name": "Over-Ear Headphones Black",
      "serial_number": "SN-9988112233",
      "image_required": true
    }
  }
}

• Response (201 Created):

{
  "status": "success",
  "message": "Reverse pickup request created",
  "data": {
    "client_request_id": "REV-ORD-2026-8801",
    "awb_number": "SFX-REV-99182736",
    "status": "new"
  }
}

---

3.3 Update QC Specifications

Update Quality Check parameters (e.g. mandatory IMEI/serial number or QC flag) prior to rider arrival.

• Endpoint: PUT /api/v1/reverse/update-qc/
• Request Body:

{
  "payload": {
    "client_request_id": "REV-ORD-2026-8801",
    "qc_check": true,
    "serial_number": "SN-9988112244"
  }
}

• Response (200 OK):

{
  "status": "success",
  "message": "QC Flag updated"
}

---

3.4 Track Reverse Pickup Request

Track reverse pickup status and QC verification results.

• Endpoint: GET /api/v1/reverse/track/?client_request_id=REV-ORD-2026-8801
• Response (200 OK):

{
  "status": "success",
  "data": {
    "client_request_id": "REV-ORD-2026-8801",
    "current_status": "picked_up",
    "qc_status": "PASSED"
  }
}

---

4. Real-Time Webhook Callback Endpoint

Shadowfax posts real-time order status updates (e.g. picked_up, out_for_delivery, delivered, rts, cancelled) to this endpoint.

• Endpoint URL to register with Shadowfax: https://beta-shipping.tradhox.com/api/webhook/ (or https://shipping.tradhox.com/api/webhook/)
• HTTP Method: POST
• Payload Format:

{
  "client_order_id": "ORD-MKT-2026-101",
  "awb_number": "SFX9928374102",
  "status": "delivered",
  "sub_status": "delivered_to_customer",
  "remarks": "Package handed to customer Ananya Sharma",
  "timestamp": "2026-09-25T15:30:00Z"
}

• Response (200 OK):

{
  "status": "success",
  "message": "Webhook logged",
  "log_id": 142
}

---

5. Audit Log Export API

Export recent API transactions and webhook logs for internal monitoring and auditing.

• Endpoint: GET /api/v1/logs/?service=FORWARD&q=ORD-MKT
• Response (200 OK):

{
  "count": 1,
  "logs": [
    {
      "id": 1,
      "service_type": "FORWARD",
      "action_name": "API: Create Order",
      "endpoint_url": "https://dale.staging.shadowfax.in/v3/clients/orders/",
      "http_method": "POST",
      "response_status_code": 201,
      "execution_time_ms": 3.2,
      "status": "SUCCESS",
      "timestamp": "2026-09-25T15:45:00Z"
    }
  ]
}

---

💻 Microservice Integration Client Examples

Python (requests) Example

import requests

# Set microservice target base URL
SHIPPING_SERVICE_URL = "https://beta-shipping.tradhox.com"

def create_shipping_order(order_id, recipient_name, recipient_phone, address, pincode, amount):
    url = f"{SHIPPING_SERVICE_URL}/api/v1/forward/create-order/"
    payload = {
        "env": "staging",
        "use_mock": False,  # Set False to hit live Shadowfax APIs
        "payload": {
            "order_details": {
                "client_order_id": order_id,
                "actual_weight": 500.0,
                "product_value": amount,
                "payment_mode": "COD",
                "cod_amount": amount,
                "order_type": "marketplace"
            },
            "customer_details": {
                "name": recipient_name,
                "phone": recipient_phone,
                "address_line_1": address,
                "pincode": pincode,
                "city": "Bengaluru",
                "state": "Karnataka"
            },
            "pickup_details": {
                "name": "Main Warehouse",
                "phone": "9900112233",
                "address_line_1": "Warehouse Hub 12",
                "pincode": "560077",
                "city": "Bengaluru",
                "state": "Karnataka"
            }
        }
    }
    
    response = requests.post(url, json=payload, timeout=10)
    response.raise_for_status()
    return response.json()

# Example invocation:
res = create_shipping_order("ORD-SELLER-9988", "Rohan Verma", "9876543210", "12 Main St", "560038", 1299.0)
print("AWB Allocated:", res["data"]["awb_number"])

Node.js (axios) Example

const axios = require('axios');

const BASE_URL = 'https://beta-shipping.tradhox.com';

async function trackShipment(awbNumber) {
  try {
    const response = await axios.get(`${BASE_URL}/api/v1/forward/track/`, {
      params: { awb: awbNumber }
    });
    console.log('Shipment Status:', response.data.data.current_status);
    return response.data;
  } catch (error) {
    console.error('Tracking Error:', error.response?.data || error.message);
  }
}

trackShipment('SFX9928374102');

---

🖥️ Web UI Inspection Hubs

The microservice provides an interactive web dashboard for human operators and engineers:

• Forward Logistics Hub: https://beta-shipping.tradhox.com/forward/
• Reverse Logistics Hub: https://beta-shipping.tradhox.com/reverse/
• Activity & Audit Logs: https://beta-shipping.tradhox.com/logs/
• Webhook Simulator & Inspector: https://beta-shipping.tradhox.com/webhooks/

---

⚙️ Local Development & Operations Setup

1. Environment Requirements

• Python 3.10+
• PostgreSQL 16
• Nginx & Gunicorn (for EC2 deployment)

2. Local Setup Steps

# Clone repository
git clone https://pipeline.tradhox.com/vignesh/shippingservice.git
cd shippingservice

# Set up virtual environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run migrations
python manage.py migrate

# Start development server
python manage.py runserver 0.0.0.0:8000

3. CI/CD Deployment Flow

Deployments to Beta (beta-shipping.tradhox.com) are automatically triggered upon pushing to the beta branch via Forgejo runner (.forgejo/workflows/beta.yml). The workflow connects via SSH to Beta EC2 (16.113.57.127), runs migrations, updates static files, and restarts shippingservice-beta.service.