# 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
```http
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
```http
Content-Type: application/json
X-Shadowfax-Signature: <HMAC_SHA256_HASH>
```

### Webhook Standard Payload Schema
```json
{
  "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`)
```json
{
  "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
```json
{
  "client_code": "ACME_RETAIL",
  "count": 1
}
```

#### Sample Response Payload (`200 OK`)
```json
{
  "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
```json
{
  "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`)
```json
{
  "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
```json
{
  "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`)
```json
{
  "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
```json
{
  "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
```json
{
  "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`)
```json
{
  "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`.