v1.0.0 API Docs · Developer Documentation

Courier Search API

কাস্টমারের ফোন নাম্বার দিয়ে এক ক্লিকে Steadfast, RedX, Pathao, Carrybee এবং Paperfly-এর লাইভ ডেলিভারি হিস্ট্রি এবং সাকসেস রেশিও জেনারেট করার অফিশিয়াল ডেভেলপার গাইড।

GETJSON responseBangladesh couriers

১. ক্রেডেনশিয়াল কানেকশন (Steadfast Setup)

আপনার রিকোয়েস্টে লাইভ Steadfast ফ্রড রিপোর্ট ডেটা অন্তর্ভুক্ত করার জন্য প্রথমে আপনার মার্চেন্ট প্যানেল ওজি-কানেক্টের সাথে লিঙ্ক করতে হবে।

ড্যাশবোর্ড সেটিংস পেজে যান: প্রথমে আপনার ব্রাউজারে ওজি-কানেক্টের সেটিংস প্যানেলটি ওপেন করুন: dash.hoorin.com/settings
কুরিয়ার কানেক্ট মেনু সিলেক্ট করুন: বাম পাশের ন্যাভিগেশন বার থেকে Courier Connect মেনুতে ক্লিক করুন।
Steadfast API Key সেভ করুন: সেখান থেকে Steadfast অপশনটি চুজ করে আপনার কুরিয়ার প্যানেলের Client ID এবং Secret Key ইনপুট দিয়ে সেভ সম্পন্ন করুন।

⚠️ মনে রাখবেন: যদি কুরিয়ার ক্রেডেনশিয়াল কানেক্ট করা না থাকে, তবে রেসপন্সের Steadfast ব্লকে লাইভ ডেটার পরিবর্তে কানেক্ট করার অ্যালার্ট মেসেজ পাঠানো হবে।

২. প্রোডাকশন এপিআই এন্ডপয়েন্ট (API Endpoint)

নিচের লাইভ ইউআরএল-এ GET মেথড ব্যবহার করে রিকোয়েস্ট পাঠান:

GET https://plugin.hoorin.com/courier/api/v1/search

লাইভ টেস্ট ইউআরএল উদাহরণ:

REQUEST URL

https://plugin.hoorin.com/courier/api/v1/search?apiKey=YOUR_API_KEY&searchTerm=01642444088

API key গোপন রাখুন। Public frontend code বা shared screenshot-এ আসল key দেবেন না।

৩. রিকোয়েস্ট কুয়েরি প্যারামিটারসমূহ (Parameters)

নিখুঁত ডেটা প্রসেসিংয়ের জন্য রিকোয়েস্ট ইউআরএল-এর সাথে নিচের প্যারামিটারগুলো পাস করুন:

Parameter	Required	Description
`apiKey`	Required	আপনার ওজি-কানেক্ট ড্যাশবোর্ড থেকে প্রাপ্ত ইউনিক অথেনটিকেশন এপিআই কী (API Key)।
`searchTerm`	Required	যে কাস্টমারের পার্সেল হিস্ট্রি চেক করতে চান তার ১১ ডিজিটের মোবাইল নাম্বার (যেমন: `01642444088`)।
`view`	Optional	ডিফল্ট ভ্যালু `full`। ফুল অবজেক্টের পরিবর্তে যদি সরাসরি সংক্ষিপ্ত সাকসেস সামারি টেক্সট চান, তবে ভ্যালু হিসেবে `ratio` পাস করুন।
`cache`	Optional	ডিফল্ট ভ্যালু `on`। আপনি যদি ক্যাশ বাইপাস করে সম্পূর্ণ লাইভ রিয়েল-টাইম কুরিয়ার সার্ভার থেকে ডেটা রিফ্রেশ করতে চান, তবে `cache=off` পাস করুন (এটি রেডিস রিড/রাইট সম্পূর্ণ স্কিপ করবে)।

EXAMPLE · CACHE BYPASS

https://plugin.hoorin.com/courier/api/v1/search?apiKey=YOUR_API_KEY&searchTerm=01642444088&cache=off

৪. ডেভলপার-ফ্রেন্ডলি JSON রেসপন্স (view=full)

ডিফল্টভাবে এপিআই অত্যন্ত সাজানো এবং সহজে ডট-নোটেশনে অ্যাক্সেসযোগ্য অবজেক্ট রিটার্ন করে:

RESPONSE (APPLICATION/JSON) · 200 OK

{
  "success": true,
  "overall": {
    "verified_total_parcels": 25,
    "verified_delivered_parcels": 25,
    "verified_cancelled_parcels": 0,
    "overall_score": 98.8,
    "summary_text": "High Delivery Rate"
  },
  "couriers": {
    "steadfast": {
      "type": "ratio",
      "enabled": true,
      "delivery_rate": 94,
      "cancellation_rate": 5,
      "status": "success",
      "details": []
    },
    "redx": {
      "type": "ratio",
      "enabled": false,
      "delivery_rate": null,
      "cancellation_rate": null,
      "status": "disabled",
      "details": [
        "This courier is currently under maintenance/upgrade. It will be activated automatically when maintenance is complete."
      ]
    },
    "pathao": {
      "type": "count",
      "enabled": true,
      "total_parcels": 24,
      "delivered_parcels": 24,
      "cancelled_parcels": 0,
      "delivery_rate": 100,
      "cancellation_rate": 0,
      "status": "success",
      "details": []
    },
    "carrybee": {
      "type": "count",
      "enabled": true,
      "total_parcels": 1,
      "delivered_parcels": 1,
      "cancelled_parcels": 0,
      "delivery_rate": 100,
      "cancellation_rate": 0,
      "status": "success",
      "details": []
    },
    "paperfly": {
      "type": "count",
      "enabled": true,
      "total_parcels": 0,
      "delivered_parcels": 0,
      "cancelled_parcels": 0,
      "delivery_rate": 0,
      "cancellation_rate": 0,
      "status": "no_data",
      "details": []
    }
  }
}

type: ratio

Steadfast/RedX source-এর delivery rate ভিত্তিক ফল। Count-based verified totals-এ অন্তর্ভুক্ত হয় না।

type: count

Courier-এর parcel count দেয়। এই courier-গুলোর total ও delivered count overall verified totals-এ যোগ হয়।

Overall score

Count-based courier-গুলোর verified delivery rate-এর ওজন ৮০%, আর সফল ratio-based courier-গুলোর গড় delivery rate-এর ওজন ২০%। কোনো একটি group-এর data না থাকলে অন্য group-এর score ব্যবহার হয়। Summary threshold: ৯০ বা বেশি High, ৭০–৮৯.৯৯ Moderate, ৭০-এর কম Low।

৫. স্যাম্পল রেসপন্স (view=ratio)

আপনার যদি শুধুমাত্র একটি সংক্ষিপ্ত সামারি অবজেক্ট বা মেসেজের প্রয়োজন হয়, তবে ইউআরএল-এ view=ratio পাস করতে পারেন:

REQUEST URL (RATIO VIEW)

https://plugin.hoorin.com/courier/api/v1/search?apiKey=YOUR_API_KEY&searchTerm=01642444088&view=ratio

RESPONSE (APPLICATION/JSON) · 200 OK

{
  "success": true,
  "summary": "Overall Delivery Rate: 98.8% (High Delivery Rate)",
  "score": 98.8,
  "verified_total": 25,
  "verified_delivered": 25
}

৬. Courier status ও fields

Field / status	Meaning
`enabled`	Courier lookup চালু আছে কি না। Boolean `true`/`false`।
`status: success`	Courier থেকে সফলভাবে usable data এসেছে।
`status: no_data`	Lookup হয়েছে, কিন্তু ঐ নাম্বারে কোনো parcel history পাওয়া যায়নি।
`status: disabled`	কুরিয়ারটি সাময়িকভাবে বন্ধ বা মেইনটেন্যান্সে রয়েছে।
`status: temporarily_busy`	সার্ভার সাময়িকভাবে ব্যস্ত; পরে আবার request দিন।
`details`	Courier-এর অতিরিক্ত তথ্য, report details বা status/error message-এর array।

৭. কোড ইন্টিগ্রেশন স্যাম্পল (Code Examples)

আপনার প্রোজেক্টে সহজে ইন্টিগ্রেট করার জন্য নিচের পপুলার ল্যাঙ্গুয়েজের উদাহরণগুলো অনুসরণ করুন:

JavaScript (Fetch API)

JAVASCRIPT

const apiKey = 'YOUR_API_KEY';
const phoneNumber = '01642444088';

fetch(`https://plugin.hoorin.com/courier/api/v1/search?apiKey=${apiKey}&searchTerm=${phoneNumber}`)
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log('Overall Score:', data.overall.overall_score);
      console.log('Pathao Parcels:', data.couriers.pathao.total_parcels);
    } else {
      console.error('Error:', data.error);
    }
  })
  .catch(err => console.error(err));

PHP (cURL)

PHP

<?php
$apiKey = "YOUR_API_KEY";
$phone = "01642444088";
$url = "https://plugin.hoorin.com/courier/api/v1/search?apiKey={$apiKey}&searchTerm={$phone}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if (isset($data['success']) &&$data['success']) {
    echo "Summary: " . $data['overall']['summary_text'] . "\n";
    echo "Score: " . $data['overall']['overall_score'] . "%\n";
} else {
    echo "Error: " . ($data['error'] ?? 'Unknown error');
}
?>

৮. Error responses

Request parameter বা account validation ব্যর্থ হলে endpoint courier result-এর বদলে প্রয়োজনীয় HTTP status কোডসহ error object ফেরত পাঠায়:

MISSING PARAMETERS · 400 BAD REQUEST

{
  "success": false,
  "error": "Missing Params"
}

INVALID API KEY · 401 UNAUTHORIZED

{
  "success": false,
  "error": "Invalid Key"
}

API key ও phone number query string-এ পাঠানো হয়—server log, browser history এবং analytics-এ এগুলো সংরক্ষিত হতে পারে। Key নিরাপদে ব্যবহার করুন।