Skyfleet API

The Skyfleet API is a JSON REST API. All endpoints are relative to the base URL below and require authentication (except the public tracking endpoint). Use it to check rates, create and book shipments, track parcels, reconcile COD and wallet, handle NDR/returns, and receive real-time webhook events.

Base URL:  https://api.skyfleetnow.com/api/v1
Content-Type: application/json

All requests and responses are UTF-8 JSON. Timestamps are ISO-8601 (UTC). Monetary values are in INR (₹) unless a field name ends in Paise. Weights are in grams, dimensions in centimetres.

Authenticate every request with an API key. Generate one in the dashboard under Settings → Developer → API Keys. The full key (sf_live_…) is shown once at creation — store it securely; you can revoke and re-create at any time. A key is scoped to your organization.

Send it in the X-API-Key header:

curl https://api.skyfleetnow.com/api/v1/wallet \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Keep keys server-side only — never ship them in a browser, mobile app, or public repo. Rotate immediately if exposed (revoke the old key, create a new one).

Every response uses a consistent envelope.

Success

{ "success": true, "data": { ... }, "message": "optional" }

Paginated list

{
  "success": true,
  "data": [ ... ],
  "meta": { "total": 120, "page": 1, "limit": 20, "totalPages": 6 }
}

List endpoints accept page (default 1) and limit (default 20).

Error

{ "success": false, "message": "Human-readable reason", "errors": { "field": ["..."] } }

• ShipmentStatus: CREATED, LABEL_GENERATED, PICKUP_SCHEDULED, PICKED_UP, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, DELIVERY_FAILED, RTO_INITIATED, RTO_IN_TRANSIT, RTO_DELIVERED, CANCELLED, LOST, DAMAGED
• PaymentMode: PREPAID, COD
• ShipmentType: FORWARD, REVERSE, EXCHANGE
• NdrAction: REATTEMPT, RTO, CHANGE_ADDRESS, CONTACT_CUSTOMER

POST /shipments creates a draft (status CREATED, no AWB, no charge). Booking a draft (assigning a courier + AWB) is gated:

• Your organization's KYC must be APPROVED (else 403).
• A wallet must be configured (else 402); prepaid wallets must cover the freight.

Complete KYC and top up your wallet in the dashboard before booking via API.

curl https://api.skyfleetnow.com/api/v1/rates/calculate -X POST \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{
    "pickupPincode": "110011",
    "dropPincode": "400001",
    "weightGrams": 500,
    "paymentMode": "PREPAID",
    "lengthCm": 20, "breadthCm": 15, "heightCm": 10,
    "invoiceValue": 1499
  }'

// 200 → data: [
  {
    "courier": "Delhivery Surface", "carrierId": "delhivery-surface",
    "zone": "METRO", "chargeableWeightGrams": 500,
    "baseRate": 46.61, "codCharge": 0, "gstAmount": 12.05,
    "totalCharge": 78.95, "eddDays": 3, "isAvailable": true
  }
]

curl https://api.skyfleetnow.com/api/v1/shipments -X POST \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{
    "shipmentType": "FORWARD",
    "paymentMode": "COD",
    "orderReferenceNumber": "ORD-1042",
    "invoiceValue": 1499,
    "codAmount": 1499,
    "pickup": {
      "name": "Acme Warehouse", "phone": "9876543210",
      "address": "Plot 4, Industrial Area", "city": "New Delhi",
      "state": "Delhi", "pincode": "110011"
    },
    "drop": {
      "name": "Ravi Kumar", "phone": "9812345678",
      "address": "12 MG Road", "city": "Mumbai",
      "state": "Maharashtra", "pincode": "400001"
    },
    "packages": [{
      "weightGrams": 500, "lengthCm": 20, "breadthCm": 15, "heightCm": 10,
      "items": [{ "name": "Cotton T-Shirt", "sku": "TS-01", "quantity": 1, "unitPrice": 1499 }]
    }]
  }'

// 201 → data: { "shipment": { "id": "...", "status": "CREATED", ... } }

Required: shipmentType, paymentMode, invoiceValue, pickup, drop, packages (≥1, each with weight + dimensions + items). codAmount is required for COD. orderReferenceNumber must be unique among live orders — a duplicate returns 409 unless you pass "allowDuplicate": true. You can reference a saved pickup with pickupAddressId instead of an inline pickup object.

curl https://api.skyfleetnow.com/api/v1/shipments/SHIP_ID/book -X POST \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{ "carrierBrand": "DELHIVERY" }'   // optional; omit to auto-allocate

// 200 → data: { "id": "...", "awbNumber": "...", "status": "LABEL_GENERATED", ... }

curl https://api.skyfleetnow.com/api/v1/public/track/DL1234567890

// 200 → data: {
  "awbNumber": "DL1234567890", "status": "OUT_FOR_DELIVERY",
  "courier": "Delhivery", "customerName": "Ravi K.",
  "timeline": { "orderedAt": "...", "pickedUpAt": "...", "deliveredAt": null, "expectedDeliveryDate": "..." },
  "events": [ { "status": "OUT_FOR_DELIVERY", "description": "...", "location": "Mumbai", "eventTime": "..." } ]
}

For most integrations, prefer webhooks over polling — you get pushed a status event the moment it changes.

curl https://api.skyfleetnow.com/api/v1/ndr/action -X POST \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{
    "ndrEventId": "NDR_ID",
    "action": "REATTEMPT",          // or RTO | CHANGE_ADDRESS | CONTACT_CUSTOMER
    "preferredDate": "2026-07-12",
    "notes": "Customer will be home after 5pm"
  }'

curl https://api.skyfleetnow.com/api/v1/rvp/from-forward -X POST \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{
    "forwardAwb": "DL1234567890",   // or "forwardShipmentId"
    "isQcRequired": false,
    "reasonForReturn": "Size mismatch"
  }'

// → returns a REVERSE shipment draft; book it to schedule the pickup.

Instead of polling, subscribe to events and Skyfleet will POST them to your URL the moment they happen. Create and manage endpoints in the dashboard under Settings → Webhooks (set a URL, pick events, get a signing secret).

Events

shipment.created            shipment.out_for_delivery
shipment.label_generated    shipment.delivered
shipment.picked_up          shipment.delivery_failed
shipment.in_transit         shipment.rto_delivered
shipment.cancelled

Payload

POST <your-url>
Headers:
  X-Skyfleet-Event: shipment.delivered
  X-Skyfleet-Signature: <hmac-sha256 hex of the raw body>
  X-Skyfleet-Delivery-Attempt: 1

Body:
{
  "event": "shipment.delivered",
  "timestamp": "2026-07-08T09:15:00.000Z",
  "data": {
    "awbNumber": "DL1234567890",
    "orderReferenceNumber": "ORD-1042",
    "status": "DELIVERED",
    "courier": "Delhivery",
    "..." : "..."
  }
}

Verify the signature

Compute an HMAC-SHA256 of the raw request body using your endpoint's secret and compare (constant-time) to the X-Skyfleet-Signature header. Reject if they differ.

// Node.js (Express)
import crypto from "crypto";

app.post("/skyfleet-webhook", express.raw({ type: "*/*" }), (req, res) => {
  const expected = crypto.createHmac("sha256", process.env.SKYFLEET_WEBHOOK_SECRET)
    .update(req.body)                    // raw Buffer, not parsed JSON
    .digest("hex");
  const got = req.headers["x-skyfleet-signature"];
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(String(got)))) {
    return res.status(401).end();
  }
  const event = JSON.parse(req.body.toString());
  // ... handle event.event / event.data ...
  res.sendStatus(200);                   // 2xx = acknowledged
});

Respond 2xx to acknowledge. Non-2xx, timeouts, and network errors are retried with backoff (4xx is treated as a caller bug and not retried). Every attempt is logged in Settings → Webhooks → Deliveries, where you can inspect and manually retry.