SDK for Steadfast Courier API - Bangladesh
npm install @dreygur/steadfast-apiNode.js SDK for Steadfast Courier API - Bangladesh's courier service.
``bash`
npm install steadfast-courier
`typescript
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,
});
`
`typescript`
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) |
---
#### createOrder(order: OrderData): Promise
Create a single delivery order.
`typescript
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: 'john@example.com',
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
Create multiple orders at once (max 500 per request).
`typescript
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});${res.invoice} failed: ${res.message}
} else {
console.log();`
}
});
---
#### getStatusByConsignmentId(id: number): Promise
`typescript`
const status = await client.getStatusByConsignmentId(123456);
console.log(status.delivery_status);
#### getStatusByInvoice(invoice: string): Promise
`typescript`
const status = await client.getStatusByInvoice('INV-001');
console.log(status.delivery_status);
#### getStatusByTrackingCode(code: string): Promise
`typescript`
const status = await client.getStatusByTrackingCode('SF123456789');
console.log(status.delivery_status);
#### getTrackingUrl(trackingCode: string): string
Get the public tracking URL for a shipment.
`typescript`
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 |
---
#### getBalance(): Promise
Get current account balance.
`typescriptBalance: ${balance.current_balance} BDT
const balance = await client.getBalance();
console.log();`
---
#### getPayments(): Promise
Get all payment records.
`typescriptPayment #${p.id}: ${p.amount} BDT (${p.status})
const payments = await client.getPayments();
payments.forEach((p) => {
console.log();`
});
#### getPayment(id: number): Promise
Get payment details with associated consignments.
`typescriptAmount: ${payment.amount} BDT
const payment = await client.getPayment(123);
console.log();Method: ${payment.method}
console.log();- ${c.invoice}: ${c.cod_amount} BDT
payment.consignments?.forEach((c) => {
console.log();`
});
---
#### getPoliceStations(): Promise
Get list of police stations for address reference.
`typescript${s.name} - ${s.district}, ${s.division}
const stations = await client.getPoliceStations();
stations.forEach((s) => {
console.log();`
});
---
#### fraudCheck(phone: string): Promise
Check customer's delivery history and reliability score.
`typescript
const check = await client.fraudCheck('01712345678');
console.log(Total Orders: ${check.total_parcels});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}
console.log();`
---
#### createReturnRequest(data: ReturnRequestData): Promise
Create a return request. Must provide at least one identifier.
`typescript`
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
`typescript`
const returnReq = await client.getReturnRequest(123);
console.log(returnReq.status);
#### getAllReturnRequests(): Promise
`typescript${r.id}: ${r.status}
const returns = await client.getAllReturnRequests();
returns.forEach((r) => console.log());`
---
Steadfast sends webhook notifications for order status updates.
#### SteadFast.parseWebhook(body: unknown): WebhookPayload | null
Parse and validate incoming webhook payload.
`typescript
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 |
---
All methods throw SteadFastError on failure.
`typescript
import { SteadFast, SteadFastError } from 'steadfast-courier';
try {
await client.createOrder(orderData);
} catch (error) {
if (error instanceof SteadFastError) {
console.error(Error: ${error.message});Status Code: ${error.statusCode}
console.error();Response:
console.error(, error.response);`
}
}
---
Validate inputs before making API calls.
`typescript
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);
}
`
---
All types are exported:
`typescript``
import type {
SteadFastConfig,
OrderData,
OrderResponse,
BulkOrderResponse,
Consignment,
StatusResponse,
BalanceResponse,
FraudCheckResponse,
ReturnRequestData,
ReturnRequest,
Payment,
PaymentConsignment,
PoliceStation,
WebhookPayload,
} from 'steadfast-courier';
---
MIT