# Steadfast Courier API — cURL Reference

**Base URL:** `https://portal.packzy.com/api/v1`

Replace `YOUR_API_KEY` and `YOUR_SECRET_KEY` with your credentials in every request.

---

## Authentication Headers

All requests require these headers:

| Header | Value |
|---|---|
| `Api-Key` | Your API key from Steadfast |
| `Secret-Key` | Your secret key from Steadfast |
| `Content-Type` | `application/json` |

---

## Orders

### 1. Place a Single Order

**POST** `/create_order`

**Request:**
```bash
curl -X POST "https://portal.packzy.com/api/v1/create_order" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": "Aa12-das4",
    "recipient_name": "John Smith",
    "recipient_phone": "01234567890",
    "recipient_address": "Fla# A1, House# 17/1, Road# 3/A, Dhanmondi, Dhaka-1209",
    "cod_amount": 1060,
    "note": "Deliver within 3PM",
    "delivery_type": 0,
    "item_description": "T-shirt x2",
    "total_lot": 1
  }'
```

**Response:**
```json
{
  "status": 200,
  "message": "Consignment has been created successfully.",
  "consignment": {
    "consignment_id": 1424107,
    "invoice": "Aa12-das4",
    "tracking_code": "15BAEB8A",
    "recipient_name": "John Smith",
    "recipient_phone": "01234567890",
    "recipient_address": "Fla# A1, House# 17/1, Road# 3/A, Dhanmondi, Dhaka-1209",
    "cod_amount": 1060,
    "status": "in_review",
    "note": "Deliver within 3PM",
    "created_at": "2021-03-21T07:05:31.000000Z",
    "updated_at": "2021-03-21T07:05:31.000000Z"
  }
}
```

> `invoice` must be unique. `cod_amount` ≥ 0. `delivery_type`: `0` = home delivery, `1` = hub pickup.

---

### 2. Bulk Order Create

**POST** `/create_order/bulk-order`

**Request:**
```bash
curl -X POST "https://portal.packzy.com/api/v1/create_order/bulk-order" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "[
      {
        \"invoice\": \"230822-1\",
        \"recipient_name\": \"John Doe\",
        \"recipient_address\": \"House 44, Road 2/A, Dhanmondi, Dhaka 1209\",
        \"recipient_phone\": \"01711111111\",
        \"cod_amount\": 500,
        \"note\": \"Handle with care\"
      },
      {
        \"invoice\": \"230822-2\",
        \"recipient_name\": \"Jane Doe\",
        \"recipient_address\": \"Flat 5, Block C, Mirpur, Dhaka\",
        \"recipient_phone\": \"01822222222\",
        \"cod_amount\": 750,
        \"note\": null
      }
    ]"
  }'
```

**Response (success):**
```json
[
  {
    "invoice": "230822-1",
    "recipient_name": "John Doe",
    "recipient_address": "House 44, Road 2/A, Dhanmondi, Dhaka 1209",
    "recipient_phone": "01711111111",
    "cod_amount": "500.00",
    "note": "Handle with care",
    "consignment_id": 11543968,
    "tracking_code": "B025A038",
    "status": "success"
  },
  {
    "invoice": "230822-2",
    "recipient_name": "Jane Doe",
    "recipient_address": "Flat 5, Block C, Mirpur, Dhaka",
    "recipient_phone": "01822222222",
    "cod_amount": "750.00",
    "note": null,
    "consignment_id": 11543969,
    "tracking_code": "B025A1DC",
    "status": "success"
  }
]
```

**Response (error):**
```json
{
  "data": [
    {
      "invoice": "230822-1",
      "recipient_name": "John Doe",
      "recipient_address": "House 44, Road 2/A, Dhanmondi, Dhaka 1209",
      "recipient_phone": "01711111111",
      "cod_amount": "0.00",
      "note": null,
      "consignment_id": null,
      "tracking_code": null,
      "status": "error"
    }
  ]
}
```

> `data` is a JSON-encoded string. Maximum 500 items per request.

---

## Delivery Status

### 3. Check Status by Consignment ID

**GET** `/status_by_cid/{id}`

**Request:**
```bash
curl -X GET "https://portal.packzy.com/api/v1/status_by_cid/1424107" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
```

**Response:**
```json
{
  "status": 200,
  "delivery_status": "in_review"
}
```

> Replace `1424107` with your `consignment_id`.

---

### 4. Check Status by Invoice ID

**GET** `/status_by_invoice/{invoice}`

**Request:**
```bash
curl -X GET "https://portal.packzy.com/api/v1/status_by_invoice/Aa12-das4" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
```

**Response:**
```json
{
  "status": 200,
  "delivery_status": "in_review"
}
```

> Replace `Aa12-das4` with your invoice value.

---

### 5. Check Status by Tracking Code

**GET** `/status_by_trackingcode/{trackingCode}`

**Request:**
```bash
curl -X GET "https://portal.packzy.com/api/v1/status_by_trackingcode/15BAEB8A" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
```

**Response:**
```json
{
  "status": 200,
  "delivery_status": "in_review"
}
```

> Replace `15BAEB8A` with your `tracking_code`.

---

## Balance

### 6. Check Current Balance

**GET** `/get_balance`

**Request:**
```bash
curl -X GET "https://portal.packzy.com/api/v1/get_balance" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
```

**Response:**
```json
{
  "status": 200,
  "current_balance": 0
}
```

---

## Return Requests

### 7. Create Return Request

**POST** `/create_return_request`

**Request:**
```bash
curl -X POST "https://portal.packzy.com/api/v1/create_return_request" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consignment_id": 1424107,
    "reason": "Customer refused delivery"
  }'
```

**Response:**
```json
{
  "id": 1,
  "user_id": 1,
  "consignment_id": 10000042,
  "reason": "Customer refused delivery",
  "status": "pending",
  "created_at": "2025-07-30T23:11:45.000000Z",
  "updated_at": "2025-07-30T23:11:45.000000Z"
}
```

> Use one of `consignment_id`, `invoice`, or `tracking_code`. `reason` is optional.
> Return status values: `pending`, `approved`, `processing`, `completed`, `cancelled`

---

### 8. Get Single Return Request

**GET** `/get_return_request/{id}`

**Request:**
```bash
curl -X GET "https://portal.packzy.com/api/v1/get_return_request/1" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
```

**Response:**
```json
{
  "id": 1,
  "user_id": 1,
  "consignment_id": 10000042,
  "reason": "Customer refused delivery",
  "status": "pending",
  "created_at": "2025-07-30T23:11:45.000000Z",
  "updated_at": "2025-07-30T23:11:45.000000Z"
}
```

> Replace `1` with the return request ID.

---

### 9. Get All Return Requests

**GET** `/get_return_requests`

**Request:**
```bash
curl -X GET "https://portal.packzy.com/api/v1/get_return_requests" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
```

**Response:**
```json
[
  {
    "id": 1,
    "user_id": 1,
    "consignment_id": 10000042,
    "reason": "Customer refused delivery",
    "status": "pending",
    "created_at": "2025-07-30T23:11:45.000000Z",
    "updated_at": "2025-07-30T23:11:45.000000Z"
  }
]
```

---

## Payments

### 10. Get Payments

**GET** `/payments`

**Request:**
```bash
curl -X GET "https://portal.packzy.com/api/v1/payments" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
```

**Response:**
```json
{
  "status": 200,
  "payments": []
}
```

---

### 11. Get Single Payment with Consignments

**GET** `/payments/{payment_id}`

**Request:**
```bash
curl -X GET "https://portal.packzy.com/api/v1/payments/42" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
```

**Response:**
```json
{
  "status": 200,
  "payment": {
    "id": 42,
    "consignments": []
  }
}
```

> Replace `42` with your `payment_id`.

---

## Misc

### 12. Get Police Stations

**GET** `/police_stations`

**Request:**
```bash
curl -X GET "https://portal.packzy.com/api/v1/police_stations" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
```

**Response:**
```json
{
  "status": 200,
  "data": []
}
```

---

## Delivery Status Reference

| Status | Description |
|---|---|
| `pending` | Not delivered or cancelled yet |
| `delivered_approval_pending` | Delivered, awaiting admin approval |
| `partial_delivered_approval_pending` | Partially delivered, awaiting approval |
| `cancelled_approval_pending` | Cancelled, awaiting admin approval |
| `unknown_approval_pending` | Unknown pending — contact support |
| `delivered` | Delivered, balance added |
| `partial_delivered` | Partially delivered, balance added |
| `cancelled` | Cancelled, balance updated |
| `hold` | Consignment is held |
| `in_review` | Order placed, waiting for review |
| `unknown` | Unknown status — contact support |