vignesh/seller_central_backend
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
seller_central_backend/documentation/reverse_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

16 KiB
Raw Permalink Blame History

Shadowfax Reverse Pickup API (SFX) — Complete Reverse Integration Document

Document Scope: Technical Specification & Integration Guide for Shadowfax Reverse Logistics & Customer Return Platform Core Capability: Doorstep Pickups, Quality Check (QC) Enforcement, Warehouse Returns & Callback Synchronization API Version: Reverse API v1 / v2 / v3 / v4 Document Status: Production Ready

1. System Architecture & Reverse Logistics Overview

The Shadowfax (SFX) Reverse Pickup API enables e-commerce merchants, marketplace operators, and brand retailers to automate customer return pickups and doorstep Quality Checks (QC). Unlike forward delivery where parcels originate from seller/warehouse locations, reverse logistics manages customer doorstep pickups, item inspection, hub consolidation, linehaul transport, and final delivery back to the client's return warehouse.

Key Operational Capabilities

  1. Doorstep Customer Pickup: Delivery executive collects items directly from the customer's specified pickup address.
  2. Configurable Quality Check (QC): Executive verifies physical item condition, brand, serial/IMEI numbers, original packaging, and tags prior to accept/reject.
  3. Reverse Linehaul & Consolidation: Collected items are routed through Shadowfax Origin Hubs and linehaul Distribution Centers (DCs).
  4. Warehouse Return Delivery: Final delivery and digital handover of collected return inventory to client fulfillment centers.
  5. Real-time Callback Synchronization: Push webhooks notify client systems instantly upon pickup status change, QC pass/fail events, and warehouse delivery.

Environment Base URLs

Environment Base URL Purpose
Staging / Sandbox https://dale.staging.shadowfax.in Integration testing & test pincodes (110009, 560077, 560007)
Production https://flash.shadowfax.in Live reverse order creation & operational execution

2. Technical Glossary & Reverse Network Facilities

Facility Network Architecture

  • Pickup Customer Location: The customer residential or commercial address where the return item is collected.
  • Origin Hub: First Shadowfax local hub receiving the picked-up return item from the delivery rider.
  • Origin DC: Primary sorting Distribution Center processing reverse linehaul routing.
  • Destination DC: Sorting center located near the client return warehouse.
  • Destination Hub / Return Hub: Final Shadowfax hub executing bulk delivery back to the client warehouse.
  • Client Return Warehouse: Final destination facility where returned goods are handed over to the merchant.

Reverse Logistics Identifiers

  • Client Request ID / Order ID: Client's unique internal reference for the return request.
  • Reverse Air Waybill (AWB): Unique tracking number assigned to the reverse shipment.
  • QC Parameter: Inspection rules (e.g., brand check, IMEI match, unused status) defined per item.
  • Proof of Pickup (POP) / POD: Digital signature or photo timestamp confirming return item collection.

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 HTTP Headers

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

Standard HTTP Status Codes

HTTP Code Category Operational Meaning & Action
200 OK Success Request succeeded. Body contains request details or query results.
201 Created Success Reverse pickup request successfully created.
400 Bad Request Validation Error Missing mandatory field or invalid data type format.
401 Unauthorized Security Error Invalid or missing API token in Authorization header.
404 Not Found Resource Error Client Request ID or Reverse AWB number does not exist.
422 Unprocessable Business Rule Non-serviceable pickup pincode or duplicate client_request_id.
500 Server Error System Exception Downstream system unavailable; execute retry with exponential backoff.

4. Reverse Order Lifecycle & Quality Check (QC) Architecture

4.1 Reverse Pickup Lifecycle States

State Name Status Description Next Valid States
new Pickup request created in Shadowfax system; awaiting rider assignment. pickup_assigned, cancelled
pickup_assigned Rider assigned to visit customer address. picked_up, qc_failed, pickup_rescheduled, cancelled
pickup_rescheduled Customer requested alternate pickup date/time window. pickup_assigned, cancelled
picked_up Item passed QC checks and collected from customer; in transit to Origin Hub. in_transit
qc_failed Item failed doorstep QC checks (e.g. wrong brand, damaged item). Pickup rejected. Terminal State
in_transit Item moving between Shadowfax Hubs and linehaul DCs toward client warehouse. out_for_delivery_to_warehouse
out_for_delivery_to_warehouse Item assigned to rider for bulk handover at client return warehouse. delivered_to_warehouse, delivery_rescheduled
delivered_to_warehouse Return item verified and received at client warehouse. Terminal State
cancelled Reverse pickup request cancelled prior to pickup execution. Terminal State

4.2 Quality Check (QC) Enforcement Rules

Shadowfax riders perform doorstep QC based on criteria supplied in the order payload:

  1. Brand & Model Match: Verifies item brand name and model match order manifest.
  2. Serial / IMEI Verification: Matches 15-digit mobile IMEI or product serial number.
  3. Physical Damage Inspection: Checks for cracks, dents, water damage, or missing components.
  4. Tag / Packaging Verification: Confirms original brand tags/box are intact if required.
  5. Doorstep Image Capture: Rider uploads photo proof of item condition during pickup.

5. Push Callback API (Webhooks)

Shadowfax notifies client systems in real time whenever a reverse pickup transitions state.

Webhook Request Headers

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

Webhook Standard Payload Schema

{
  "client_request_id": "REV-ORD-2026-8801",
  "awb_number": "SFX-REV-99182736",
  "status": "picked_up",
  "sub_status": "qc_passed",
  "remarks": "Item passed physical QC and picked up by rider Ramesh",
  "reason_code": "",
  "qc_result": {
    "qc_passed": true,
    "brand_matched": true,
    "imei_matched": true,
    "serial_number": "SN-9988112233",
    "images": [
      "https://cdn.shadowfax.in/qc/photos/REV-ORD-2026-8801_1.jpg"
    ]
  },
  "timestamp": "2026-09-25T15:10:00Z"
}

6. API Endpoints Reference & Complete Technical Specifications

6.1 Reverse Pincode Serviceability API

HTTP Method: GET
Endpoint Path: /v1/clients/serviceability/?service=reverse&page={page}&count={count}&pincodes={pincodes}
Description: Verifies if customer pickup pincodes are active for reverse pickup operations.

Query Parameters

Parameter Type Required Description
service String Yes Pass "reverse" for reverse pickup serviceability query.
pincodes String No Comma-separated 6-digit Indian pincodes to check.
page Integer No Page number for paginated results (Default: 1).
count Integer No Records per page (Default: 100).

Sample Response Payload (200 OK)

{
  "status": "success",
  "data": {
    "total_count": 1,
    "pincodes": [
      {
        "pincode": "560077",
        "city": "Bengaluru",
        "state": "Karnataka",
        "reverse_pickup_available": true,
        "max_weight_grams": 5000.0
      }
    ]
  }
}

6.2 Reverse AWB Generation API

HTTP Method: POST
Endpoint Path: /v3/clients/orders/generate_awb/
Description: Pre-allocates tracking numbers for reverse pickup shipments.

Sample Request Payload

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

Sample Response Payload (200 OK)

{
  "status": "success",
  "data": {
    "awb_numbers": [
      "SFX-REV-99182736"
    ]
  }
}

6.3 Reverse Pickup Request Creation API

HTTP Method: POST
Endpoint Path: /v3/clients/requests
Description: Creates a customer doorstep pickup request with embedded QC parameters.

Request Payload Parameter Matrix

1. Root Level & Order Identification
Field Name Type Required Description
client_request_id String Yes Client internal unique return request identifier.
awb_number String No Pre-allocated reverse AWB number. Auto-generated if omitted.
actual_weight Number Yes Expected weight of return item in grams.
product_value Number Yes Invoice price of item being returned in INR.
pickup_date String No Scheduled pickup date format YYYY-MM-DD.
2. pickup_details (Customer Location)
Field Name Type Required Description
name String Yes Customer full name.
phone String Yes 10-digit mobile number of customer.
address_line_1 String Yes Customer street address and flat/house number.
pincode String Yes 6-digit serviceable pickup pincode.
city String Yes Pickup city.
state String Yes Pickup state.
3. return_details (Client Warehouse Destination)
Field Name Type Required Description
name String Yes Warehouse return hub name.
phone String Yes Contact phone number of return warehouse.
address_line_1 String Yes Warehouse street address.
pincode String Yes 6-digit warehouse pincode.
city String Yes Warehouse city.
state String Yes Warehouse state.
4. qc_details Object (Quality Check Instructions)
Field Name Type Required Description
qc_check Boolean Yes true to enforce doorstep QC inspection.
brand_name String No Expected brand name on item label.
item_name String Yes SKU name / description.
serial_number String No Expected product serial or IMEI number.
image_required Boolean No true if rider must take photo proof during QC.

Complete Reverse Pickup Request Payload Example

{
  "client_request_id": "REV-ORD-2026-8801",
  "awb_number": "SFX-REV-99182736",
  "actual_weight": 500.0,
  "product_value": 2999.0,
  "pickup_details": {
    "name": "Kavita Reddy",
    "phone": "9876501234",
    "address_line_1": "Apartment 102, Green Glen Layout",
    "address_line_2": "Bellandur",
    "pincode": "560103",
    "city": "Bengaluru",
    "state": "Karnataka"
  },
  "return_details": {
    "name": "Acme Central Returns Warehouse",
    "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
  }
}

Sample Response Payload (201 Created)

{
  "status": "success",
  "message": "Reverse pickup request created successfully",
  "data": {
    "client_request_id": "REV-ORD-2026-8801",
    "awb_number": "SFX-REV-99182736",
    "status": "new",
    "created_at": "2026-09-25T15:00:00Z"
  }
}

6.4 Reverse Order Cancellation API

HTTP Method: POST
Endpoint Path: /v2/clients/requests/mark_cancel
Description: Cancels a pending customer pickup request before rider execution.

Sample Request Payload

{
  "client_request_id": "REV-ORD-2026-8801",
  "reason": "Customer withdrew return request"
}

6.5 Single Pickup Request Tracking API (V4)

HTTP Method: GET
Endpoint Path: /v4/clients/requests/{client_request_id}
Description: Retrieves tracking timeline, rider contact, QC status, and location for a reverse pickup.

Sample Response Payload (200 OK)

{
  "status": "success",
  "data": {
    "client_request_id": "REV-ORD-2026-8801",
    "awb_number": "SFX-REV-99182736",
    "current_status": "picked_up",
    "qc_status": "PASSED",
    "rider_details": {
      "name": "Ramesh Kumar",
      "phone": "+919876543210"
    },
    "tracking_history": [
      {
        "status": "new",
        "timestamp": "2026-09-25T15:00:00Z",
        "remarks": "Reverse pickup requested"
      },
      {
        "status": "pickup_assigned",
        "timestamp": "2026-09-25T15:15:00Z",
        "remarks": "Assigned to rider Ramesh"
      },
      {
        "status": "picked_up",
        "timestamp": "2026-09-25T16:00:00Z",
        "remarks": "Item passed QC check and collected from customer"
      }
    ]
  }
}

6.6 Bulk Pickup Request Tracking API (V4)

HTTP Method: POST
Endpoint Path: /v4/clients/requests/bulk_query
Description: Batch queries status for up to 50 reverse pickup requests.

Sample Request Payload

{
  "client_request_ids": [
    "REV-ORD-2026-8801",
    "REV-ORD-2026-8802"
  ]
}

6.7 Update QC Flag API

HTTP Method: PUT
Endpoint Path: /v2/clients/requests/update_qc/
Description: Updates QC verification flags or serial number requirements prior to pickup attempt.

Sample Request Payload

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

6.8 Proof of Pickup / POD API

HTTP Method: GET
Endpoint Path: /v1/clients/pod_details/?client_request_id={client_request_id}
Description: Retrieves digital signature image URL and customer OTP verification status for completed pickups.

Sample Response Payload (200 OK)

{
  "status": "success",
  "data": {
    "client_request_id": "REV-ORD-2026-8801",
    "pickup_timestamp": "2026-09-25T16:00:00Z",
    "signature_url": "https://cdn.shadowfax.in/pop/signatures/REV-ORD-2026-8801.png",
    "qc_photos": [
      "https://cdn.shadowfax.in/qc/photos/REV-ORD-2026-8801_1.jpg"
    ],
    "otp_verified": true
  }
}

7. Appendix: Standard Reverse Remark & QC Fail Codes Catalog

Shadowfax returns standardized remark and reason codes during reverse pickup exceptions.

7.1 Quality Check (QC) Failure Reason Codes

Reason Code Description Customer & System Handling
QC_FAIL_BRAND_MISMATCH Item brand does not match order manifest. Re-check customer item or reject return request.
QC_FAIL_SERIAL_MISMATCH Serial/IMEI number on item differs from manifest. Verify original order invoice serial number.
QC_FAIL_DAMAGED_ITEM Item exhibits physical damage not recorded in return request. Notify merchant customer support.
QC_FAIL_MISSING_ACC Accessories/chargers missing from return package. Inform customer to provide complete box contents.
QC_FAIL_USED_ITEM Item shows clear signs of usage (tags removed). Reject return per merchant policy.

7.2 Customer Delay & Intention (CID) Codes

Reason Code Description Action
CID_CUST_UNAVAILABLE Customer not available at pickup address. Reschedule for next business day.
CID_ITEM_NOT_PACKED Customer item not packed or ready for handoff. Reschedule pickup window.
CID_CUST_REFUSED Customer changed mind and refused to hand over item. Trigger cancellation workflow.

7.3 On-Hold & Unreachable Remark Codes

Reason Code Description Action
NC_PHONE_UNREACHABLE Rider unable to reach customer phone. Trigger automated SMS/WhatsApp call-back link.
NC_ADDRESS_INCOMPLETE Customer address untraceable by rider. Request customer address update via client UI.

8. Integration Walkthrough & Next Steps

  1. API Token Setup: Request Reverse API Token from Shadowfax Integration Team.
  2. Webhook Registration: Configure HTTPS endpoint for receiving reverse state callbacks (picked_up, qc_failed, delivered_to_warehouse).
  3. Sandbox Testing: Create test pickup request \rightarrow Execute simulated QC pass/fail \rightarrow Receive Webhooks \rightarrow Retrieve POD.
  4. Go-Live Readiness: Transition endpoint URL to Production host https://flash.shadowfax.in.