Tradhox Shipping Microservice Integration Report

📌 Executive Summary

We have successfully integrated the Tradhox Shipping Microservice (shippingservice / Shadowfax SFX Gateway) into the Seller Central Backend (seller_central_backend). This integration powers:

Delivery Pickup (Forward Logistics): Pre-allocated AWB numbers, forward pincode serviceability checks, order fulfillment dispatch, real-time V4 shipment tracking, and order cancellations.
Customer Return Pickup (Reverse Logistics): Doorstep return requests, reverse pincode serviceability, Quality Check (QC) rules enforcement (brand, IMEI/serial number validation, photo requirements), reverse V4 shipment tracking, and QC specification updates.

🏗️ Architecture & Implementation Overview

sequenceDiagram
    autonumber
    participant Seller as Seller Central Frontend / User
    participant SCB as Seller Central Backend (seller_central_backend)
    participant Gateway as Shipping Microservice (shippingservice)
    participant SFX as Shadowfax Logistics Platform

    rect rgb(240, 248, 255)
    Note over Seller, SFX: Delivery Pickup (Forward Logistics) Flow
    Seller->>SCB: POST /api/orders/{id}/accept/
    SCB->>Gateway: POST /api/v1/forward/create-order/
    Gateway->>SFX: Forward Order Payload (v3/clients/orders/)
    SFX-->>Gateway: Response (AWB & Status)
    Gateway-->>SCB: AWB Number & Status
    SCB-->>Seller: Updated Order (Carrier: Shadowfax, Tracking AWB)
    end

    rect rgb(255, 245, 238)
    Note over Seller, SFX: Customer Return Pickup (Reverse Logistics with Doorstep QC)
    Seller->>SCB: POST /api/returns/{id}/action/ (action: "Approved")
    SCB->>Gateway: POST /api/v1/reverse/create-request/
    Gateway->>SFX: Reverse Request + QC Details (v3/clients/requests)
    SFX-->>Gateway: Response (Reverse AWB)
    Gateway-->>SCB: Reverse AWB & Pickup Status
    SCB-->>Seller: Updated Return Request (Returning AWB, In Transit)
    end

🛠️ Key Files Created & Modified

File	Type	Key Responsibilities
`api/shipping_client.py`	Client Service	Gateway client connecting to `shippingservice` REST API endpoints (`/api/v1/forward/` & `/api/v1/reverse/`). Includes offline mock fallback handling.
`api/shipping_views.py`	API Views	Standalone REST API endpoints for shipping serviceability checks, tracking, cancellation, and QC specification updates.
`api/views.py`	Core ViewSets	Enhanced `OrderViewSet` and `ReturnRequestViewSet` to automatically dispatch delivery pickups on order acceptance and return pickups on return approval.
`api/urls.py`	Routing	Registered new `/api/shipping/` endpoint routes.
`config/settings.py`	Configuration	Added environment configuration settings for `SHIPPING_SERVICE_URL`, `SHIPPING_SERVICE_TOKEN`, `SHIPPING_USE_MOCK`, and `SHIPPING_ENV`.
`api/test_shipping.py`	Automated Tests	Comprehensive test suite verifying client calls, viewset actions, and standalone shipping endpoints.

🚀 API Endpoints Overview

1. Integrated ViewSet Actions

Order ViewSet (`/api/orders/`)

POST /api/orders/{id}/accept/: Accepts an order and automatically creates a delivery pickup order via shippingservice. Returns allocated AWB number and updates status to Ready to Ship with carrier Shadowfax Logistics.
POST /api/orders/{id}/create_pickup/: Explicit endpoint for creating or retrying a delivery pickup request.
GET /api/orders/{id}/track/: Live forward shipment tracking using order AWB number.
POST /api/orders/{id}/cancel_pickup/: Cancels unfulfilled delivery pickup request.

Return Request ViewSet (`/api/returns/`)

POST /api/returns/{id}/action/ (with {"action": "Approved"}): Approves a customer return request and automatically triggers a doorstep return pickup request with Quality Check (QC). Sets status = 'In Transit' and assigns returning_tracking AWB.
POST /api/returns/{id}/create_return_pickup/: Explicit endpoint for triggering customer return pickup with custom pickup/return/QC details.
GET /api/returns/{id}/track/: Live return shipment tracking and doorstep QC verification status.
PUT /api/returns/{id}/update_qc/: Updates doorstep QC parameters (serial/IMEI number, brand name, physical condition checks) prior to rider arrival.

2. Standalone Shipping APIs (`/api/shipping/`)

Method	Path	Description
`GET`	`/api/shipping/health/`	Service health check for shipping microservice.
`POST`	`/api/shipping/forward/serviceability/`	Forward delivery & express serviceability check for pincodes.
`POST`	`/api/shipping/forward/create-pickup/`	Direct delivery pickup creation.
`GET`	`/api/shipping/forward/track/?awb=...`	Direct forward shipment tracking.
`POST`	`/api/shipping/forward/cancel/`	Cancel forward delivery shipment.
`POST`	`/api/shipping/reverse/serviceability/`	Customer return pincode serviceability check.
`POST`	`/api/shipping/reverse/create-pickup/`	Direct customer return pickup creation.
`GET`	`/api/shipping/reverse/track/?client_request_id=...`	Direct customer return shipment tracking.
`PUT`	`/api/shipping/reverse/update-qc/`	Update doorstep QC parameters for a return.

🧪 Verification & Testing Results

Ran full automated test suite using pytest:

venv/bin/python -m pytest api/tests.py api/test_shipping.py

Output:

======================= 18 passed, 3 warnings in 13.90s ========================

All 18 tests passed cleanly.

6 KiB Raw Blame History