Steadfast Courier SDK

Node.js SDK for Steadfast Courier API - Bangladesh's courier service.

Installation

npm install steadfast-courier

Quick Start

import { SteadFast } from 'steadfast-courier';

const client = new SteadFast({
  apiKey: 'your-api-key',
  secretKey: 'your-secret-key',
});

const order = await client.createOrder({
  invoice: 'INV-001',
  recipient_name: 'John Doe',
  recipient_phone: '01712345678',
  recipient_address: 'Dhaka, Bangladesh',
  cod_amount: 500,
});

API Reference

Constructor

new SteadFast(config: SteadFastConfig)

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | apiKey | string | Yes | Your Steadfast API key | | secretKey | string | Yes | Your Steadfast secret key | | baseUrl | string | No | Custom API base URL (default: https://portal.packzy.com/api/v1) |

Orders

createOrder(order: OrderData): Promise<OrderResponse>

Create a single delivery order.

const response = await client.createOrder({
  invoice: 'INV-001',
  recipient_name: 'John Doe',
  recipient_phone: '01712345678',
  recipient_address: 'House 1, Road 1, Dhanmondi, Dhaka',
  cod_amount: 1500,
  // Optional fields
  alternative_phone: '01812345678',
  recipient_email: '[email protected]',
  note: 'Call before delivery',
  item_description: '2x T-Shirt',
  delivery_type: 0, // 0 = Home Delivery, 1 = Point Delivery
});

console.log(response.consignment?.tracking_code);

OrderData Fields:

| Field | Type | Required | Description | |-------|------|----------|-------------| | invoice | string | Yes | Your unique invoice/order ID | | recipient_name | string | Yes | Customer name | | recipient_phone | string | Yes | Customer phone (11 digits) | | recipient_address | string | Yes | Full delivery address | | cod_amount | number | Yes | Cash on delivery amount | | alternative_phone | string | No | Alternative contact number | | recipient_email | string | No | Customer email | | note | string | No | Delivery instructions | | item_description | string | No | Package contents description | | deliver_within | string | No | Expected delivery timeframe | | total_lot | number | No | Number of packages | | delivery_type | 0 | 1 | No | 0 = Home, 1 = Point delivery |

createBulkOrders(orders: OrderData[]): Promise<BulkOrderResponse[]>

Create multiple orders at once (max 500 per request).

const orders = [
  {
    invoice: 'INV-001',
    recipient_name: 'John Doe',
    recipient_phone: '01712345678',
    recipient_address: 'Dhaka',
    cod_amount: 500,
  },
  {
    invoice: 'INV-002',
    recipient_name: 'Jane Doe',
    recipient_phone: '01812345678',
    recipient_address: 'Chittagong',
    cod_amount: 750,
  },
];

const responses = await client.createBulkOrders(orders);

responses.forEach((res) => {
  if (res.status === 'success') {
    console.log(`${res.invoice}: ${res.tracking_code}`);
  } else {
    console.log(`${res.invoice} failed: ${res.message}`);
  }
});

Tracking

getStatusByConsignmentId(id: number): Promise<StatusResponse>

const status = await client.getStatusByConsignmentId(123456);
console.log(status.delivery_status);

getStatusByInvoice(invoice: string): Promise<StatusResponse>

const status = await client.getStatusByInvoice('INV-001');
console.log(status.delivery_status);

getStatusByTrackingCode(code: string): Promise<StatusResponse>

const status = await client.getStatusByTrackingCode('SF123456789');
console.log(status.delivery_status);

getTrackingUrl(trackingCode: string): string

Get the public tracking URL for a shipment.

const url = client.getTrackingUrl('SF123456789');
console.log(url); // https://steadfast.com.bd/t/SF123456789

Delivery Status Values:

| Status | Description | |--------|-------------| | pending | Order received, not yet picked up | | in_review | Under review | | hold | On hold | | cancelled | Cancelled | | delivered | Successfully delivered | | partial_delivered | Partially delivered | | unknown | Unknown status |

Balance

getBalance(): Promise<BalanceResponse>

Get current account balance.

const balance = await client.getBalance();
console.log(`Balance: ${balance.current_balance} BDT`);

Payments

getPayments(): Promise<Payment[]>

Get all payment records.

const payments = await client.getPayments();
payments.forEach((p) => {
  console.log(`Payment #${p.id}: ${p.amount} BDT (${p.status})`);
});

getPayment(id: number): Promise<Payment>

Get payment details with associated consignments.

const payment = await client.getPayment(123);
console.log(`Amount: ${payment.amount} BDT`);
console.log(`Method: ${payment.method}`);
payment.consignments?.forEach((c) => {
  console.log(`- ${c.invoice}: ${c.cod_amount} BDT`);
});

Police Stations

getPoliceStations(): Promise<PoliceStation[]>

Get list of police stations for address reference.

const stations = await client.getPoliceStations();
stations.forEach((s) => {
  console.log(`${s.name} - ${s.district}, ${s.division}`);
});

Fraud Check

fraudCheck(phone: string): Promise<FraudCheckResponse>

Check customer's delivery history and reliability score.

const check = await client.fraudCheck('01712345678');

console.log(`Total Orders: ${check.total_parcels}`);
console.log(`Delivered: ${check.total_delivered}`);
console.log(`Cancelled: ${check.total_cancelled}`);
console.log(`Success Rate: ${check.success_ratio}%`);
console.log(`Fraud Reports: ${check.total_fraud_reports.length}`);

Return Requests

createReturnRequest(data: ReturnRequestData): Promise<ReturnRequest>

Create a return request. Must provide at least one identifier.

const returnReq = await client.createReturnRequest({
  consignment_id: 123456,
  // OR invoice: 'INV-001',
  // OR tracking_code: 'SF123456789',
  reason: 'Customer refused delivery',
  status: 'pending',
});

Status Values: pending | approved | processing | completed | cancelled

getReturnRequest(id: number): Promise<ReturnRequest>

const returnReq = await client.getReturnRequest(123);
console.log(returnReq.status);

getAllReturnRequests(): Promise<ReturnRequest[]>

const returns = await client.getAllReturnRequests();
returns.forEach((r) => console.log(`${r.id}: ${r.status}`));

Webhooks

Steadfast sends webhook notifications for order status updates.

SteadFast.parseWebhook(body: unknown): WebhookPayload | null

Parse and validate incoming webhook payload.

import { SteadFast } from 'steadfast-courier';

// Express.js example
app.post('/webhook/steadfast', (req, res) => {
  const payload = SteadFast.parseWebhook(req.body);

  if (!payload) {
    return res.status(400).send('Invalid payload');
  }

  console.log(`Order ${payload.invoice} is now ${payload.status}`);

  // Handle status updates
  switch (payload.status_type) {
    case 'delivered':
      // Mark order as delivered
      break;
    case 'cancelled':
      // Handle cancellation
      break;
  }

  res.sendStatus(200);
});

WebhookPayload Fields:

| Field | Type | Description | |-------|------|-------------| | consignment_id | number | Steadfast consignment ID | | tracking_code | string | Tracking code | | invoice | string | Your invoice ID | | status | string | Status message | | status_type | string | Status category (see below) | | updated_at | string | Update timestamp | | cod_amount | number | COD amount (optional) | | delivery_fee | number | Delivery fee (optional) | | note | string | Notes (optional) |

Status Types:

| Type | Description | |------|-------------| | pending | Order is pending | | delivered_approval_pending | Delivered, awaiting approval | | partial_delivered_approval_pending | Partially delivered, awaiting approval | | cancelled_approval_pending | Cancelled, awaiting approval | | delivered | Confirmed delivered | | partial_delivered | Confirmed partial delivery | | cancelled | Confirmed cancelled | | hold | On hold | | in_review | Under review | | unknown | Unknown status |

Error Handling

All methods throw SteadFastError on failure.

import { SteadFast, SteadFastError } from 'steadfast-courier';

try {
  await client.createOrder(orderData);
} catch (error) {
  if (error instanceof SteadFastError) {
    console.error(`Error: ${error.message}`);
    console.error(`Status Code: ${error.statusCode}`);
    console.error(`Response:`, error.response);
  }
}

Validation Utilities

Validate inputs before making API calls.

import { validate } from 'steadfast-courier';

// Validate Bangladesh phone number (01XXXXXXXXX)
validate.phone('01712345678'); // true
validate.phone('1234567890');  // false

// Validate invoice
validate.invoice('INV-001'); // true
validate.invoice('');        // false

// Validate COD amount
validate.codAmount(500);  // true
validate.codAmount(-10);  // false

// Validate entire order - returns array of errors
const errors = validate.order({
  invoice: 'INV-001',
  recipient_name: 'John',
  recipient_phone: '01712345678',
  recipient_address: 'Dhaka',
  cod_amount: 500,
});

if (errors.length > 0) {
  console.log('Validation errors:', errors);
}

TypeScript

All types are exported:

import type {
  SteadFastConfig,
  OrderData,
  OrderResponse,
  BulkOrderResponse,
  Consignment,
  StatusResponse,
  BalanceResponse,
  FraudCheckResponse,
  ReturnRequestData,
  ReturnRequest,
  Payment,
  PaymentConsignment,
  PoliceStation,
  WebhookPayload,
} from 'steadfast-courier';

License

MIT