Delivesy
API Documentation

Delivesy API Reference

Integrate shipping capabilities into your application with our REST APIs. Create shipments, track orders, and manage logistics programmatically.

Quick Start
Get up and running in minutes
Authentication
Secure your API requests
Webhooks
Real-time event notifications

Quick Start

The Delivesy API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL
https://api.delivesy.com/v1
Example Request
Using cURL to create a shipment
curl -X POST https://api.delivesy.com/v1/shipments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_pincode": "560001",
    "destination_pincode": "400001",
    "weight": 0.5,
    "cod_amount": 1000,
    "customer": {
      "name": "Rahul Sharma",
      "phone": "+919876543210",
      "address": "123 MG Road, Mumbai"
    }
  }'

Authentication

The Delivesy API uses API keys to authenticate requests. You can view and manage your API keys in the merchant dashboard under Settings → API Integration.

API Key Types
Test
Test Mode Keys
Start with dlv_test_. Use for development and testing.
Live
Live Mode Keys
Start with dlv_live_. Use for production shipments.
Making Authenticated Requests
Authorization: Bearer dlv_test_your_api_key_here

Rate Calculator

Calculate shipping rates from multiple courier partners before creating a shipment.

POST /v1/rates/calculate
POST
Get rates from available courier partners
{
  "origin_pincode": "560001",
  "destination_pincode": "400001",
  "weight": 0.5,
  "dimensions": {
    "length": 10,
    "width": 10,
    "height": 5
  },
  "payment_mode": "COD",
  "cod_amount": 1000
}
Parameters
origin_pincodeRequired
Pickup pincode
string
destination_pincodeRequired
Delivery pincode
string
weightRequired
Package weight in kg
number
dimensions
Package dimensions in cm
object
payment_mode
COD or Prepaid
string
cod_amount
COD amount if applicable
number

Create Shipment

Create a new shipment and generate AWB and shipping label.

POST /v1/shipments
POST
Create a new shipment order
{
  "order_id": "ORD-12345",
  "courier_id": "bluedart",
  "payment_mode": "COD",
  "cod_amount": 1000,
  "pickup_address_id": "addr_abc123",
  "customer": {
    "name": "Rahul Sharma",
    "phone": "+919876543210",
    "email": "rahul@example.com",
    "address": "123 MG Road",
    "city": "Mumbai",
    "state": "Maharashtra",
    "pincode": "400001"
  },
  "package": {
    "weight": 0.5,
    "length": 10,
    "width": 10,
    "height": 5,
    "contents": "Books"
  }
}

Track Order

Get real-time tracking information for a shipment.

GET /v1/shipments/:awb/track
GET
Retrieve tracking details by AWB number
{
  "success": true,
  "data": {
    "awb": "DEL2024001234",
    "status": "Out for Delivery",
    "current_location": "Mumbai Hub",
    "estimated_delivery": "2024-12-20T18:00:00Z",
    "events": [
      {
        "status": "Booked",
        "location": "Bangalore",
        "timestamp": "2024-12-18T10:00:00Z"
      },
      {
        "status": "In Transit",
        "location": "Mumbai Hub",
        "timestamp": "2024-12-19T15:30:00Z"
      },
      {
        "status": "Out for Delivery",
        "location": "Mumbai Hub",
        "timestamp": "2024-12-20T09:00:00Z"
      }
    ]
  }
}

Webhooks

Receive real-time notifications about shipment status changes. Configure webhook URLs in your dashboard.

Webhook Events
shipment.createdShipment has been created
shipment.pickedPackage picked up from origin
shipment.in_transitPackage is in transit
shipment.out_for_deliveryOut for delivery
shipment.deliveredSuccessfully delivered
shipment.rtoReturn to origin initiated
shipment.ndrNon-delivery report
Webhook Payload Example
{
  "event": "shipment.delivered",
  "timestamp": "2024-12-20T15:30:00Z",
  "data": {
    "awb": "DEL2024001234",
    "shipment_id": "SHP123456789",
    "status": "Delivered",
    "delivered_at": "2024-12-20T15:30:00Z",
    "delivered_to": "Rahul Sharma",
    "cod_collected": true,
    "cod_amount": 1000
  }
}

Error Codes

Delivesy uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes
200
OK
Request succeeded
400
Bad Request
Invalid request parameters
401
Unauthorized
Invalid or missing API key
404
Not Found
Resource not found
429
Too Many Requests
Rate limit exceeded
500
Internal Server Error
Something went wrong on our end