418 lines
No EOL
16 KiB
Markdown
418 lines
No EOL
16 KiB
Markdown
# 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`. |