vignesh/seller_central_backend
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
seller_central_backend/documentation/forward_integration.md
vickytechkey 494975abc3
Some checks failed
Deploy Beta (NATIVE) / deploy (push) Failing after 24s
Details
feat: integrate Tradhox Shipping Microservice for forward and reverse logistics operations
2026-09-25 22:12:14 +05:30

22 KiB
Raw Permalink Blame History

Shadowfax Unified API (SFX) — Complete Forward Integration Document

Document Scope: End-to-End Technical Integration Guide for Shadowfax Logistics Platform Supported Models: Marketplace Seller Pickup & Warehouse Hub Dispatch API Version: Unified API v1 / v3 / v4 Document Status: Production Ready

1. Executive Summary & Architecture

Shadowfax (SFX) Unified API offers a single, standardized REST interface designed to streamline forward logistics operations across e-commerce marketplaces, brand storefronts, quick-commerce networks, and regional fulfillment hubs. The platform automates every stage of the shipment lifecycle—from pincode serviceability and pre-allocated AWB numbers to multi-location order placement, real-time shipment tracking, active escalation handling, digital proof of delivery (POD), dynamic COD QR codes, and real-time webhook callback notifications.

Operational Models Breakdown

  1. Marketplace Model (Seller Pickup & Delivery):
    • First Mile: Shadowfax delivery partners pick up shipments directly from distributed seller stores, retail outlets, or micro-warehouses.
    • Middle Mile: Shipments are routed via local Origin Hubs and linehaul Distribution Centers (DCs).
    • Last Mile: Delivered to the end customer address.
    • Reverse / RTS: If delivery fails after max attempts or customer rejection, the order triggers Return to Seller (RTS) and is returned to the origin pickup location.
  2. Warehouse Model (Hub Dispatch & Delivery):
    • First Mile / Linehaul: Shipments originate directly from centralized client warehouses or regional distribution hubs and are handed over to Shadowfax.
    • Last Mile: Processed through Destination Hubs and delivered to the end customer.
    • Reverse / RTO: If undeliverable, shipments enter Return to Origin (RTO) and return to the client warehouse.

Environments & Host URLs

Environment Base URL Purpose
Staging / Sandbox https://dale.staging.shadowfax.in Developer integration, QA testing & test pincodes (110009, 560077, 560007)
Production https://flash.shadowfax.in Live order processing & operational delivery management

2. Technical Glossary & Core Logistics Concepts

Facility Network Architecture

  • Distribution Center (DC): Large sorting facilities processing bulk intracity and intercity linehaul shipments.
  • Hub: Neighborhood-level delivery centers managing rider assignment for last-mile delivery and first-mile seller pickup.
  • Origin Hub: The initial Shadowfax facility receiving packages directly from sellers or micro-warehouses.
  • Origin DC: The regional distribution center receiving packages from Origin Hubs or client primary warehouses.
  • Destination DC: The sorting hub in the recipient city prior to local hub distribution.
  • Destination Hub: The final delivery hub from which last-mile riders execute customer delivery.
  • Via DC: Intermediate transit sorting hubs where manifest bags pass through without unbagging.

Logistics Identifiers & Artifacts

  • Air Waybill (AWB): Unique 10-14 digit tracking identification number assigned to every parcel.
  • Letter of Receipt (LOR): Formal digital acknowledgement issued during physical handover of bulk parcels.
  • Proof of Delivery (POD): Digital evidence (recipient signature, photo timestamp, or OTP) confirming delivery.
  • COD / Cash on Delivery: Collect-on-delivery payments collected via cash or dynamic UPI QR codes.

3. Authentication & Global HTTP Specifications

Shadowfax API uses HTTP Header Token Authentication. Production and Staging API tokens are provisioned by the Shadowfax Integration Team.

Mandatory Request Headers

Authorization: Token <YOUR_PROVISIONED_API_TOKEN>
Content-Type: application/json
Accept: application/json

Standard HTTP Status Codes

HTTP Code Category Meaning & Operational Handling
200 OK Success Request succeeded. Response body contains order status or payload data.
201 Created Success Order created or AWB generated successfully.
400 Bad Request Client Error Schema validation failure or missing mandatory fields. Check field types.
401 Unauthorized Security Error Missing or invalid API Token in Authorization header.
404 Not Found Resource Error AWB number or Order ID does not exist in Shadowfax system.
422 Unprocessable Business Error Non-serviceable pincode, duplicate client_order_id, or invalid state transition.
500 Server Error System Error Downstream system unavailable; execute exponential backoff retry.

4. Order Lifecycle & State Transitions

4.1 Marketplace Order Lifecycle States

State Name Status Description Next Valid States
new Order created in Shadowfax system; awaiting seller pickup assignment. pickup_assigned, cancelled
pickup_assigned Rider assigned for seller pickup. pickup_rescheduled, picked_up, pickup_cancelled
pickup_rescheduled Seller requested pickup deferral / pickup hold. pickup_assigned, pickup_cancelled
picked_up Package collected from seller; in transit to Origin Hub. in_transit
in_transit Moving between Origin Hub, DCs, and Destination Hub. out_for_delivery
out_for_delivery Package with last-mile delivery rider for customer attempt. delivered, delivery_rescheduled, rts_initiated
delivery_rescheduled Delivery attempt failed or customer requested date change. out_for_delivery, rts_initiated
delivered Package successfully delivered to customer. Terminal State
cancelled Order cancelled prior to pickup. Terminal State
rts_initiated Return to Seller initiated after max delivery attempts or rejection. rts_in_transit
rts_in_transit Package returning to seller location. rts_out_for_delivery
rts_out_for_delivery Rider out to hand over returned package back to seller. rts_delivered
rts_delivered Package successfully handed back to seller. Terminal State

4.2 Warehouse Order Lifecycle States

State Name Status Description Next Valid States
new Order created for warehouse fulfillment. in_transit, cancelled
in_transit In transit from client warehouse to destination hub. out_for_delivery
out_for_delivery Package out for customer delivery attempt. delivered, delivery_rescheduled, rto_initiated
delivery_rescheduled Customer requested alternate delivery slot or delivery hold. out_for_delivery, rto_initiated
delivered Successfully delivered to customer. Terminal State
cancelled Order cancelled before dispatch. Terminal State
rto_initiated Return to Origin initiated. rto_in_transit
rto_in_transit Package moving back to client warehouse. rto_delivered
rto_delivered Package returned and verified at client warehouse. Terminal State

5. Push Callback API (Webhooks)

Shadowfax provides real-time event notifications via HTTP POST webhooks pushed directly to the client's configured endpoint whenever a shipment transitions state.

Webhook Request Headers

Content-Type: application/json
X-Shadowfax-Signature: <HMAC_SHA256_HASH>

Webhook Standard Payload Schema

{
  "client_order_id": "ORD-2026-99012",
  "awb_number": "SFX10928374651",
  "status": "out_for_delivery",
  "sub_status": "out_for_delivery",
  "remarks": "Package out for delivery with rider Rajesh (Ph: +919876543210)",
  "reason_code": "",
  "timestamp": "2026-09-25T14:30:00Z",
  "location": {
    "latitude": 12.9716,
    "longitude": 77.5946,
    "city": "Bengaluru"
  },
  "attempt_count": 1,
  "pickup_details": {
    "pickup_id": "PICKUP-8812",
    "name": "Acme Electronics Hub"
  }
}

Webhook Event State Mappings

Webhook status Marketplace State Equivalent Warehouse State Equivalent Trigger Event
pickup_assigned pickup_assigned N/A Pickup executive assigned to seller.
picked_up picked_up N/A Package scanned at seller location.
in_transit in_transit in_transit Package arrived or departed DC/Hub.
out_for_delivery out_for_delivery out_for_delivery Package scanned onto rider runsheet.
delivered delivered delivered Successful delivery to customer.
delivery_rescheduled delivery_rescheduled delivery_rescheduled Delivery attempt deferred with reason code.
rts_initiated rts_initiated N/A Return to seller triggered.
rto_initiated N/A rto_initiated Return to origin warehouse triggered.

6. Endpoints Reference & Full API Specifications

6.1 Serviceability API

HTTP Method: GET
Endpoint Path: /v1/clients/serviceability/?service={service}&page={page}&count={count}&pincodes={pincodes}
Description: Fetches list of serviceable pincodes or verifies if a specific destination pincode is active for delivery/pickup.

Query Parameters

Parameter Type Required Description
service String No Service filter (e.g. express, surface, reverse).
pincodes String No Comma-separated list of 6-digit Indian pincodes to query.
page Integer No Page number for paginated pincode index (Default: 1).
count Integer No Number of records per page (Default: 100, Max: 1000).

Sample Response Payload (200 OK)

{
  "status": "success",
  "message": "Serviceability retrieved successfully",
  "data": {
    "total_count": 2,
    "page": 1,
    "pincodes": [
      {
        "pincode": "560077",
        "city": "Bengaluru",
        "state": "Karnataka",
        "serviceable": true,
        "pickup_available": true,
        "delivery_available": true,
        "cod_available": true,
        "prepaid_available": true
      },
      {
        "pincode": "110009",
        "city": "New Delhi",
        "state": "Delhi",
        "serviceable": true,
        "pickup_available": true,
        "delivery_available": true,
        "cod_available": true,
        "prepaid_available": true
      }
    ]
  }
}

6.2 AWB Generation API

HTTP Method: POST
Endpoint Path: /v3/clients/generate_marketplace_awb/
Description: Pre-allocates a Shadowfax AWB tracking number prior to creating the complete order payload.

Sample Request Payload

{
  "client_code": "ACME_RETAIL",
  "count": 1
}

Sample Response Payload (200 OK)

{
  "status": "success",
  "data": {
    "awb_numbers": [
      "SFX9928374102"
    ]
  }
}

6.3 Marketplace Order Creation API (Seller Pickup Model)

HTTP Method: POST
Endpoint Path: /v3/clients/orders/
Description: Creates a seller pickup request and customer delivery order in a single API call.

Request Payload Parameter Matrix

1. order_details Object
Field Name Type Required Validation & Description
client_order_id String Yes Client internal order ID (Must be unique across system).
awb_number String No Pre-generated Shadowfax AWB number. Auto-generated if omitted.
actual_weight Number Yes Weight of shipment in grams (e.g. 500.0).
volumetric_weight Number No Volumetric weight in grams (L * W * H) / 5000 (Default: 0.0).
product_value Number Yes Total invoice product value in INR excluding tax.
payment_mode String Yes Payment type: "Prepaid" or "COD".
cod_amount Number Yes COD amount to collect from recipient (0 if Prepaid).
promised_delivery_date String No Expected delivery date format YYYY-MM-DD.
2. customer_details Object
Field Name Type Required Validation & Description
name String Yes Recipient full name.
phone String Yes 10-digit mobile number of recipient.
address_line_1 String Yes Building, street, flat number.
address_line_2 String No Landmark, locality.
pincode String Yes 6-digit serviceable delivery pincode.
city String Yes Destination city.
state String Yes Destination state.
3. pickup_details Object
Field Name Type Required Validation & Description
name String Yes Seller / Store / Warehouse name.
phone String Yes 10-digit contact mobile number of seller.
address_line_1 String Yes Seller warehouse address.
pincode String Yes 6-digit origin pickup pincode.
city String Yes Origin city.
state String Yes Origin state.
4. rts_details Object (Return to Seller)
Field Name Type Required Validation & Description
name String Yes Return contact name.
phone String Yes Return contact phone number.
address_line_1 String Yes Return seller address.
pincode String Yes 6-digit return pincode.
5. product_details Array Items
Field Name Type Required Validation & Description
sku_name String Yes Item title or product name.
sku_code String Yes Merchant SKU code.
price Number Yes Individual SKU price.
quantity Integer Yes Quantity of items.

Complete Marketplace Request Payload Example

{
  "order_type": "marketplace",
  "order_details": {
    "client_order_id": "ORD-MKT-2026-101",
    "awb_number": "SFX9928374102",
    "actual_weight": 750.0,
    "volumetric_weight": 800.0,
    "product_value": 1499.0,
    "payment_mode": "COD",
    "cod_amount": 1499.0
  },
  "customer_details": {
    "name": "Ananya Sharma",
    "phone": "9876543210",
    "address_line_1": "Flat 402, Sunshine Apartments",
    "address_line_2": "Indiranagar 10th Main",
    "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
    }
  ]
}

Sample Response Payload (201 Created)

{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "client_order_id": "ORD-MKT-2026-101",
    "awb_number": "SFX9928374102",
    "order_status": "new",
    "created_at": "2026-09-25T14:35:00Z"
  }
}

6.4 Warehouse Order Creation API (Hub Dispatch Model)

HTTP Method: POST
Endpoint Path: /v3/clients/orders/
Description: Creates a delivery order for shipments dispatched directly from a client warehouse or hub.

Complete Warehouse Request Payload Example

{
  "order_type": "warehouse",
  "order_details": {
    "client_order_id": "ORD-WH-2026-505",
    "awb_number": "SFX8817263541",
    "actual_weight": 1200.0,
    "product_value": 3500.0,
    "payment_mode": "Prepaid",
    "cod_amount": 0.0
  },
  "customer_details": {
    "name": "Vikram Mehta",
    "phone": "9988776655",
    "address_line_1": "House 14, Civil Lines",
    "pincode": "110054",
    "city": "New Delhi",
    "state": "Delhi"
  },
  "rto_details": {
    "name": "Central Warehouse North",
    "phone": "9811002233",
    "address_line_1": "Warehouse Complex Hub 3",
    "pincode": "110042",
    "city": "New Delhi",
    "state": "Delhi"
  },
  "product_details": [
    {
      "sku_name": "Mechanical Keyboard RGB",
      "sku_code": "SKU-KB-102",
      "price": 3500.0,
      "quantity": 1
    }
  ]
}

6.5 Single Order Tracking API (V4)

HTTP Method: GET
Endpoint Path: /v4/clients/orders/{awb_number}/track/
Description: Retrieves comprehensive tracking timeline, current location, rider details, and status for a shipment.

Sample Response Payload (200 OK)

{
  "status": "success",
  "data": {
    "client_order_id": "ORD-MKT-2026-101",
    "awb_number": "SFX9928374102",
    "current_status": "out_for_delivery",
    "expected_delivery_date": "2026-09-25",
    "rider_details": {
      "name": "Rajesh Kumar",
      "phone": "+919876543210"
    },
    "tracking_history": [
      {
        "status": "new",
        "location": "Bengaluru Hub",
        "timestamp": "2026-09-24T10:00:00Z",
        "remarks": "Order created"
      },
      {
        "status": "picked_up",
        "location": "StyleHub Store",
        "timestamp": "2026-09-24T14:30:00Z",
        "remarks": "Package picked up from seller"
      },
      {
        "status": "in_transit",
        "location": "Bengaluru Main DC",
        "timestamp": "2026-09-24T19:00:00Z",
        "remarks": "Arrived at sorting DC"
      },
      {
        "status": "out_for_delivery",
        "location": "Indiranagar Hub",
        "timestamp": "2026-09-25T08:30:00Z",
        "remarks": "Assigned to rider for delivery"
      }
    ]
  }
}

6.6 Bulk Order Tracking API (V4)

HTTP Method: POST
Endpoint Path: /v4/clients/bulk_track/
Description: Fetches current tracking status for up to 50 AWB numbers in a single request.

Sample Request Payload

{
  "awb_numbers": [
    "SFX9928374102",
    "SFX8817263541"
  ]
}

6.7 Order Cancellation API

HTTP Method: POST
Endpoint Path: /v3/clients/orders/cancel/
Description: Cancels a pending order prior to rider pickup or warehouse dispatch.

Sample Request Payload

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

6.8 Escalation & Support Ticket API

HTTP Method: POST
Endpoint Path: /v1/clients/support/issue/
Description: Raises operational support tickets directly to Shadowfax ground control team.

Issue Categories Available

  • DELAYED_DELIVERY: Delivery SLA breached or delayed.
  • EXPEDITE_PICKUP: Urgent seller pickup required.
  • DELIVERY_DISPUTE: Customer disputes status marked delivered.
  • ADDRESS_UPDATE: Correcting destination address/phone.

Sample Request Payload

{
  "awb_number": "SFX9928374102",
  "category": "EXPEDITE_PICKUP",
  "description": "Seller store closing early today at 4 PM, please pick up by 3 PM."
}

6.9 Proof of Delivery (POD) API

HTTP Method: POST
Endpoint Path: /v1/clients/pod_details/
Description: Retrieves digital signature image URL, photo proof, or OTP verification details for delivered shipments.

Sample Response Payload (200 OK)

{
  "status": "success",
  "data": {
    "awb_number": "SFX9928374102",
    "delivery_timestamp": "2026-09-25T11:45:00Z",
    "signature_url": "https://cdn.shadowfax.in/pod/signatures/SFX9928374102.png",
    "photo_proof_url": "https://cdn.shadowfax.in/pod/photos/SFX9928374102.jpg",
    "receiver_name": "Ananya Sharma",
    "otp_verified": true
  }
}

6.10 Dynamic QR Code Generation API (V2)

HTTP Method: POST
Endpoint Path: /v2/clients/generate_qr_code/
Description: Generates dynamic UPI payment QR code strings for Cash-on-Delivery collection at customer doorstep.

Sample Response Payload (200 OK)

{
  "status": "success",
  "data": {
    "awb_number": "SFX9928374102",
    "cod_amount": 1499.0,
    "qr_code_string": "upi://pay?pa=shadowfax@icici&pn=Shadowfax&am=1499.00&tr=SFX9928374102&tn=COD%20Payment",
    "qr_code_image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

7. Appendix: Standard Reason & Remark Codes Catalog

Shadowfax uses standardized numerical and string remark codes during exception events. Client system webhooks should parse these codes for automated business logic.

7.1 Delivery On-Hold Remark Codes

Reason Code Code Description Suggested Operational Handling
OH_ADDR_INCOMPLETE Customer address incomplete or missing landmark. Trigger SMS/WhatsApp to customer to update address.
OH_CUST_UNAVAILABLE Customer not available at address. Reschedule for next business day automatically.
OH_COD_NOT_READY Customer requested delivery when cash/UPI ready. Reschedule delivery date per customer request.
OH_PINCODE_UNMAPPED Destination pincode out of delivery hub zone. Trigger escalation ticket to reassign hub.

7.2 Pickup On-Hold Remark Codes

Reason Code Code Description Suggested Operational Handling
PU_STORE_CLOSED Seller store/warehouse closed during pickup attempt. Notify seller contact via alert.
PU_ITEM_NOT_READY Shipment packaging incomplete at seller end. Reschedule seller pickup window.
PU_ADDR_NOT_FOUND Seller pickup address untraceable. Verify pickup coordinates and phone number.

7.3 Cancellation Reason Codes

Reason Code Code Description Originator
CAN_CLIENT_REQ Order cancelled by client system via API. Client
CAN_SELLER_DENIED Seller denied stock availability during pickup. Seller
CAN_EXCEEDED_ATTEMPTS Max delivery attempts reached (RTS/RTO triggered). Courier

8. Summary & Next Steps for Integration

  1. Credential Setup: Obtain Staging API Token and test pincode list from Shadowfax Integration Team.
  2. Webhook Endpoint Registration: Configure HTTPS POST Webhook listener and verify HMAC signature parsing.
  3. End-to-End Sandbox Testing: Execute Pincode Check \rightarrow Order Creation \rightarrow Tracking \rightarrow Webhook Receive \rightarrow POD retrieval flow.
  4. Go-Live Readiness Review: Obtain sign-off from Shadowfax Logistics Operations for Production URL switch.