API Documentation
Integrate our powerful logistics {API} into your business systems for seamless parcel management and real-time tracking.
Getting Started
All API requests must include valid API credentials in the headers:
X-Secret-Key: YOUR_SECRET_KEY
Content-Type: application/json
Note: You need to obtain API credentials by registering with our service.
Use this base URL for all API requests:
Current rate limit: 2000 requests per minute per API key.
API Endpoints
GET
/merchant/profile - Get merchant profile
No request body required
Success Response
{
"success": true,
"data": {
"profile": {
"custom_id": "M123456",
"business": "Your Business Name",
"email": "contact@yourbusiness.com",
"phone": "+1234567890",
"address": "123 Business St, City",
"status": "active",
"created_at": "2025-10-20T10:30:00+00:00"
},
"statistics": {
"total_parcels": 150
}
},
"message": "Profile retrieved successfully",
"timestamp": "2025-10-20T10:30:00+00:00,
"status_code": 200
}
Raw PHP (cURL)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'http://forcescourier.com/dashboard/api/merchant/profile',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'X-API-Key: YOUR_API_KEY',
'X-Secret-Key: YOUR_SECRET_KEY',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
GET
/merchant/balance - Get merchant balance
No request body required
Success Response
{
"success": true,
"data": {
"current_balance": 1500.00,
"pending_amount": 250.00,
"available_balance": 1250.00,
"total_parcels": 42,
"merchant_info": {
"business_name": "Your Business Name",
"email": "contact@yourbusiness.com",
"phone": "+1234567890"
}
},
"message": "Balance information retrieved successfully",
"timestamp": "2025-10-20T10:30:00+00:00,
"status_code": 200
}
Raw PHP (cURL)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'http://forcescourier.com/dashboard/api/merchant/balance',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'X-API-Key: YOUR_API_KEY',
'X-Secret-Key: YOUR_SECRET_KEY',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
$result = json_decode($response, true);
// Access the processing balance
if ($result['success']) {
$processing_balance = $result['data']['processing_balance'];
echo "Processing Balance: " . $processing_balance;
} else {
echo "Error: " . $result['message'];
}
curl_close($curl);
?>
POST
/merchant/register - Register new merchant
Request Body
{
"business_name": "ABC Electronics", // Required
"owner_name": "John Smith", // Required
"email": "john@abcelectronics.com", // Required
"phone": "+1234567890", // Required
"password": "securePassword123", // Required
"address": "123 Business Ave, City", // Required
"website": "https://abcelectronics.com" // Optional
}
Success Response
{
"success": true,
"data": {
"merchant_id": 12345,
"business_name": "ABC Electronics",
"email": "john@abcelectronics.com",
"status": "pending_verification"
},
"message": "Merchant registered successfully. Please check your email for verification.",
"timestamp": "2025-10-20T10:30:00+00:00",
"status_code": 201
}
Raw PHP (cURL)
<?php
$data = json_encode([
'business_name' => 'ABC Electronics',
'owner_name' => 'John Smith',
'email' => 'john@abcelectronics.com',
'phone' => '+1234567890',
'password' => 'securePassword123',
'address' => '123 Business Ave, City',
'website' => 'https://abcelectronics.com'
]);
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'http://forcescourier.com/dashboard/api/merchant/register',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => $data,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Content-Length: ' . strlen($data)
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
POST
/auto/login/token - Generate auto-login token
Request Body
{
"user_id": 12345, // Required
"expires_in": 3600 // Optional - token expiration in seconds (default: 3600)
}
Success Response
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_at": "2025-10-20T11:30:00+00:00",
"user_id": 12345
},
"message": "Auto-login token generated successfully",
"timestamp": "2025-10-20T10:30:00+00:00",
"status_code": 200
}
Raw PHP (cURL)
<?php
$data = json_encode([
'user_id' => 12345,
'expires_in' => 3600
]);
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'http://forcescourier.com/dashboard/api/auto/login/token',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => $data,
CURLOPT_HTTPHEADER => [
'X-API-Key: YOUR_API_KEY',
'X-Secret-Key: YOUR_SECRET_KEY',
'Content-Type: application/json',
'Content-Length: ' . strlen($data)
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
GET
/auto/login/validate?token={token} - Validate token and login user
Query Parameters
token - The auto-login token to validate (Required)
Usage Example
Success Response
{
"success": true,
"data": {
"user_id": 12345,
"username": "johnsmith",
"email": "john@example.com",
"login_success": true
},
"message": "Token validated and user logged in successfully",
"timestamp": "2025-10-20T10:30:00+00:00",
"status_code": 200
}
Error Response (Invalid/Expired Token)
{
"success": false,
"message": "Invalid or expired token",
"error": "Token has expired or is invalid",
"timestamp": "2025-10-20T10:30:00+00:00",
"status_code": 401
}
Raw PHP (file_get_contents)
<?php
$token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
$context = stream_context_create([
'http' => [
'method' => 'GET',
'header' => [
'X-API-Key: YOUR_API_KEY',
'X-Secret-Key: YOUR_SECRET_KEY',
'Content-Type: application/json'
]
]
]);
$response = file_get_contents('http://forcescourier.com/dashboard/api/auto/login/validate?token=' . urlencode($token), false, $context);
$result = json_decode($response, true);
print_r($result);
?>
Parcels
POST
/parcels - Create a new parcel
Request Body
{
"merchant_order_id": "M123456", // Optional
"name": "John Doe", // Required
"phone": "+1234567890", // Required
"secondary_phone": "+0987654321", // Optional
"address": "123 Main St, City", // Required
"codPrice": 50, // Required
"weight": 1.5, // Required
"note": "Handle with care" // Optional
}
Success Response
{
"success": true,
"data": {
"merchant_order_id": "M123456",
"parcelID": "F10200226SCV",
"order_status": "pending",
"total_charge": 80.5
},
"message": "Parcel created successfully",
"timestamp": "2025-10-20T10:30:00+00:00,
"status_code": 201
}
Raw PHP (file_get_contents)
<?php
$data = json_encode([
'merchant_order_id' => 'M123456',
'name' => 'John Doe',
'phone' => '+1234567890',
'secondary_phone' => '+0987654321',
'address' => '123 Main St, City',
'codPrice' => 50,
'weight' => 1.5,
'note' => 'Handle with care'
]);
$context = stream_context_create([
'http' => [
'method' => 'POST',
'header' => [
'X-API-Key: YOUR_API_KEY',
'X-Secret-Key: YOUR_SECRET_KEY',
'Content-Type: application/json',
'Content-Length: ' . strlen($data)
],
'content' => $data
]
]);
$response = file_get_contents('http://forcescourier.com/dashboard/api/parcels', false, $context);
$result = json_decode($response, true);
print_r($result);
?>
POST
/parcels - Create multiple parcels (Bulk)
Request Body
{
"parcels": [
{
"merchant_order_id": "M123456", // Optional
"name": "John Doe", // Required
"phone": "+1234567890", // Required
"secondary_phone": "+0987654321", // Optional
"address": "123 Main St, City", // Required
"codPrice": 50, // Required
"weight": 1.5, // Required
"note": "Handle with care" // Optional
},
{
"merchant_order_id": "M789012", // Optional
"name": "Jane Smith", // Required
"phone": "+1234567891", // Required
"address": "456 Oak Ave, Town", // Required
"codPrice": 100, // Required
"weight": 2.0, // Required
"note": "Fragile item" // Optional
}
]
}
Success Response
{
"success": true,
"data": {
"total_parcels": 2,
"successful": 2,
"failed": 0,
"results": [
{
"index": 0,
"status": "success",
"trId": "F10200330ABC",
"message": "Parcel created successfully"
},
{
"index": 1,
"status": "success",
"trId": "F10200330XYZ,
"message": "Parcel created successfully"
}
]
},
"message": "Bulk operation completed: 2 successful, 0 failed",
"timestamp": "2025-10-20T10:30:00+00:00,
"status_code": 201
}
Raw PHP (cURL)
<?php
$data = json_encode([
'parcels' => [
[
'merchant_order_id' => 'M123456',
'name' => 'John Doe',
'phone' => '+1234567890',
'secondary_phone' => '+0987654321',
'address' => '123 Main St, City',
'codPrice => 50,
'weight => 1.5,
'note => 'Handle with care
],
[
'merchant_order_id => 'M789012,
'name => 'Jane Smith,
'phone => '+1234567891,
'address => '456 Oak Ave, Town,
'codPrice => 100,
'weight => 2.0,
'note => 'Fragile item
]
]
]);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'http://forcescourier.com/dashboard/api/parcels',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => $data,
CURLOPT_HTTPHEADER => array(
'X-API-Key: YOUR_API_KEY,
'X-Secret-Key: YOUR_SECRET_KEY,
'Content-Type: application/json
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
GET
/parcels - List all parcels
Query Parameters
None required
Success Response
{
"success": true,
"data": {
"parcels": [
{
"tracking_id": "TRK123456789",
"name": "John Doe",
"phone": "+1234567890",
"status": "pending",
"codPrice": 50,
"weight": 1.5
}
],
"merchant": {
"custom_id": "M123456",
"business": "Your Business Name"
},
"pagination": {
"current_page": 1,
"per_page": 10,
"total_items": 150,
"total_pages": 15,
"has_next": true,
"has_prev": false
}
},
"message": "Parcels retrieved successfully",
"timestamp": "2025-10-20T10:30:00+00:00,
"status_code": 200
}
Raw PHP (cURL)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'http://forcescourier.com/dashboard/api/parcels',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'X-API-Key: YOUR_API_KEY,
'X-Secret-Key: YOUR_SECRET_KEY,
'Content-Type: application/json
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
GET
/parcels/{tracking_id} - Get parcel details by tracking ID or merchant invoice
Path Parameters
tracking_id - The tracking ID of the parcel (optional if using merchant_invoice)
Query Parameters
merchant_invoice - The merchant's invoice number (optional if using tracking_id)
Note: You must provide either the tracking_id path parameter or the merchant_invoice query parameter, but not both.
Usage Examples
Track by Tracking ID:
Track by Merchant Invoice:
Success Response
{
"success": true,
"data": {
"trId": "F10200348ZAR",
"service_charge": 90,
"merchant_order_id": "SM789012",
"parcel_status": "Pending",
"payment_status": null
},
"message": "Parcel status retrieved successfully",
"timestamp": "2025-10-20T12:00:10+02:00,
"status_code": 200
}
Raw PHP (file_get_contents)
<?php
$tracking_id = 'TRK123456789';
$context = stream_context_create([
'http' => [
'method' => 'GET',
'header' => [
'X-API-Key: YOUR_API_KEY,
'X-Secret-Key: YOUR_SECRET_KEY,
'Content-Type: application/json
]
]
]);
$response = file_get_contents('http://forcescourier.com/dashboard/api/parcels/' . $tracking_id, false, $context);
$result = json_decode($response, true);
print_r($result);
?>
<?php
$merchant_invoice = 'SM789012';
$context = stream_context_create([
'http' => [
'method' => 'GET',
'header' => [
'X-API-Key: YOUR_API_KEY,
'X-Secret-Key: YOUR_SECRET_KEY,
'Content-Type: application/json
]
]
]);
$response = file_get_contents('http://forcescourier.com/dashboard/api/parcels?merchant_invoice=' . $merchant_invoice, false, $context);
$result = json_decode($response, true);
print_r($result);
?>
POST
/merchant/register - Register new merchant
Request Body
{
"business": "Merchant Business",
"email": "merchant@example.com",
"username": "merchantuser",
"number": "+1234567890",
"address": "123 Business St, City",
"password": "securepassword123",
"bk_number": "01712345678",
"bank_name": "ABC Bank",
"b_ac_name": "John Doe",
"b_ac_number": "1234567890123456",
"branch_number": "BR001",
"payment_media": "bkash",
"m_category": "regular"
}
Required Fields
business- Business name (string, required)email- Email address (string, required, valid email format)username- Username (string, required, alphanumeric and underscore only)number- Phone number (string, required, valid phone format)address- Business address (string, required)password- Password (string, required, minimum 6 characters)
Optional Fields
bk_number- Bkash number (string)bank_name- Bank name (string)b_ac_name- Bank account holder name (string)b_ac_number- Bank account number (string)branch_number- Bank branch number (string)payment_media- Payment method (string, default: 'bkash')m_category- Merchant category (string, default: 'regular')
Success Response
{
"success": true,
"data": {
"custom_id": "MABC123",
"business": "Merchant Business",
"email": "merchant@example.com",
"username": "merchantuser",
"api_key": "a1b2c3d4e5f67890_49ca4655d4ec384c76d8081ed25df0c1",
"secret_key": "z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0f_dd5dca3909a275d199de547c1525e40ad29a614dcd8fe0e7",
"created_at": "2025-10-20T10:30:00+00:00"
},
"message": "Merchant created successfully",
"timestamp": "2025-10-20T10:30:00+00:00",
"status_code": 201
}
Error Responses
{
"success": false,
"error": [
"Field 'business' is required",
"Invalid email format"
],
"message": "Validation failed",
"timestamp": "2025-10-20T10:30:00+00:00",
"status_code": 400
}
{
"success": false,
"error": "Username or email already exists",
"message": "Duplicate merchant",
"timestamp": "2025-10-20T10:30:00+00:00",
"status_code": 409
}
Raw PHP (cURL)
<?php
$curl = curl_init();
$merchantData = array(
'business' => 'Merchant Business',
'email' => 'merchant@example.com',
'username' => 'merchantuser',
'number' => '+1234567890',
'address' => '123 Business St, City',
'password' => 'securepassword123',
'bk_number' => '01712345678',
'bank_name' => 'ABC Bank',
'b_ac_name' => 'John Doe',
'b_ac_number' => '1234567890123456',
'branch_number' => 'BR001',
'payment_media' => 'bkash',
'm_category' => 'regular'
);
curl_setopt_array($curl, array(
CURLOPT_URL => 'http://forcescourier.com/dashboard/api/merchant/register',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode($merchantData),
CURLOPT_HTTPHEADER => array(
'X-API-Key: YOUR_API_KEY',
'X-Secret-Key: YOUR_SECRET_KEY',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
JavaScript (fetch)
const merchantData = {
business: 'Merchant Business',
email: 'merchant@example.com',
username: 'merchantuser',
number: '+1234567890',
address: '123 Business St, City',
password: 'securepassword123',
bk_number: '01712345678',
bank_name: 'ABC Bank',
b_ac_name: 'John Doe',
b_ac_number: '1234567890123456',
branch_number: 'BR001',
payment_media: 'bkash',
m_category: 'regular'
};
fetch('http://forcescourier.com/dashboard/api/merchant/register', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'X-Secret-Key': 'YOUR_SECRET_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify(merchantData)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
POST
/auto/login/token - Generate auto-login token
Request Body
{
"username": "merchant_username"
}
Parameters
username- Username to generate token for (string, required)
Note: You can only generate tokens for yourself or your child merchants.
Success Response
{
"success": true,
"data": {
"custom_id": 123,
"auto_login_token": "YzQ0NjI5ZTUwZmUzMTkzNjp1bmRlZmluZWQ6ZjJjZGRkMjY1YjUxNzE2NmRjZjA4NzE1ZjQ1ODI0MjU6Y2U1Y2E4ZjI4MjM5NTFmMjQ1NzM2MzFkMmYxZTY3NjI=",
"expires_at": "2025-10-20T11:30:00+00:00"
},
"message": "Auto-login token generated successfully",
"timestamp": "2025-10-20T10:30:00+00:00",
"status_code": 200
}
Error Responses
{
"success": false,
"error": "Unauthorized access to merchant",
"message": "You can only generate tokens for yourself",
"timestamp": "2025-10-20T10:30:00+00:00",
"status_code": 403
}
Raw PHP (cURL)
<?php
$curl = curl_init();
$tokenData = array(
'merchant_id' => 123
);
curl_setopt_array($curl, array(
CURLOPT_URL => 'http://forcescourier.com/dashboard/api/auto/login/token',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode($tokenData),
CURLOPT_HTTPHEADER => array(
'X-API-Key: YOUR_API_KEY',
'X-Secret-Key: YOUR_SECRET_KEY',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
GET
/auto/login/validate?token={token} - Validate token and login user
http://forcescourier.com/dashboard/api/handlers/auto_login_validate.php?token=ACTUAL_TOKEN_HERE
Validate an auto-login token and automatically log in the user.
Behavior
Upon successful validation, the system:
- Sets session variables for the authenticated merchant (
id,name,business,username,role) - Logs the auto-login event in the database
- Marks the token as used (one-time use)
- Redirects to the merchant dashboard if accessed directly in browser
URL Parameters
token- Auto-login token (string, required)
Success Response
{
"success": true,
"message": "Login successful",
"merchant": {
"id": 123,
"name": "Merchant Name",
"business": "Merchant Business",
"username": "merchantuser"
},
"redirect_url": "../../../dashboard/merchant_dashboard.php"
}
Error Responses
{
"success": false,
"message": "Invalid or expired token"
}
Direct Browser Usage
You can provide this link directly to users for one-click login:
<a href="http://forcescourier.com/dashboard/api/handlers/auto_login_validate.php?token=GENERATED_TOKEN">
Login to Your Account
</a>
Programmatic Usage
Or redirect users programmatically:
window.location.href = "http://forcescourier.com/dashboard/api/handlers/auto_login_validate.php?token=" + token;
Error Responses
All error responses follow this standard format:
{
"success": false,
"message": "Error description",
"error": "Detailed error information",
"timestamp": "2025-10-20T10:30:00+00:00,
"status_code": 400
}
Common HTTP Status Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Bad Request - Invalid request data |
| 401 | Unauthorized - Invalid or missing API credentials |
| 404 | Not Found - Endpoint not found |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Something went wrong on our end |