API ম্যানেজমেন্ট

ISPbills-এর বিস্তৃত REST API মোবাইল অ্যাপ্লিকেশন পরিচালনা করে। এর মাধ্যমে বাইরের সিস্টেম ও কাস্টম ড্যাশবোর্ড যুক্ত করা এবং বিভিন্ন কাজ স্বয়ংক্রিয় করা যায়। এই নির্দেশিকায় ক্রেডেনশিয়াল ম্যানেজমেন্ট, অথেনটিকেশন, API v1 ও v2-এর সব endpoint এবং webhook কনফিগার করার পদ্ধতি দেওয়া হয়েছে।

---

API client

API client তৈরি করা

1. sidebar-এর Integrations → API Management মেনুতে যান।
2. Create API Client বাটনে ক্লিক করুন।
3. client-টি সহজে চেনা যায় এমন একটি name দিন (যেমন, “Mobile App”, “Custom Dashboard”, “Billing CRM”)।
4. v1 client-এর API token ও refresh token পেতে Generate Token বাটনে ক্লিক করুন।
5. v2 client-এর Client ID ও Client Secret স্বয়ংক্রিয়ভাবে তৈরি হবে।
6. সব credential সঙ্গে সঙ্গে কপি করে নিরাপদে রাখুন—secret value শুধু একবারই দেখানো হয়।

API client পরিচালনা করা

API Management পৃষ্ঠা থেকে আপনি যা করতে পারবেন:

• সক্রিয় সব API client, সেগুলোর ধরন (v1 বা v2) ও তৈরির তারিখ দেখতে পারবেন।
• credential ফাঁস হলে token ও secret আবার তৈরি বা পরিবর্তন করতে পারবেন।
• API client মুছে তার access বাতিল করতে পারবেন।
• দীর্ঘদিন ব্যবহার না হওয়া integration শনাক্ত করতে সর্বশেষ ব্যবহারের সময় দেখতে পারবেন।

---

অথেনটিকেশন

ISPbills দুটি authentication flow সমর্থন করে—প্রতিটি API version-এর জন্য একটি করে।

API v1 — Bearer Token

login endpoint-এ credential পাঠিয়ে token নিন। এরপর প্রতিটি request-এ token-টি দিন:

POST /api/auth/login
Content-Type: application/json
Accept: application/json

{
  "email": "[email protected]",
  "password": "your_password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "def50200abc123..."
}

পরের request-গুলোতে token-টি এভাবে দিন:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Token refresh করা

access token-এর মেয়াদ শেষ হওয়ার আগেই refresh token দিয়ে নতুন token pair নিন:

POST /api/auth/refresh
Content-Type: application/json
Accept: application/json

{
  "refresh_token": "def50200abc123..."
}

Response-এ নতুন access_token ও refresh_token পাওয়া যাবে।

API v2 — Client Credentials (OAuth 2.0)

API v2-তে client-credentials flow ব্যবহার করা হয়। অল্প সময়ের জন্য কার্যকর access token পেতে Client ID ও Client Secret পাঠান:

POST /api/v2/auth/token
Content-Type: application/json
Accept: application/json

{
  "client_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "client_secret": "sVn8K4pQ...xZ2mW"
}

রেসপন্স:

{
  "access_token": "v2_eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "bearer",
  "expires_in": 1800
}

সব v2 request-এর Authorization header-এ token-টি দিন:

Authorization: Bearer v2_eyJhbGciOiJSUzI1NiIsInR5cCI6...

Token বাতিল করা

মেয়াদ শেষ হওয়ার আগেই token বাতিল করতে (যেমন, নিরাপত্তাজনিত কোনো ঘটনার সময়):

POST /api/v2/auth/revoke
Authorization: Bearer v2_eyJhbGciOiJSUzI1NiIsInR5cCI6...

204 No Content response পেলে বুঝবেন token সফলভাবে বাতিল হয়েছে।

---

পেজিনেশন

বড় ফলাফল সেট ফেরত দিতে পারে এমন সকল তালিকা এন্ডপয়েন্ট কোয়েরি প্যারামিটারের মাধ্যমে কার্সর-ভিত্তিক পেজিনেশন সমর্থন করে।

প্যারামিটার	ধরন	ডিফল্ট	বিবরণ
page	integer	1	প্রাপ্ত করার পৃষ্ঠা নম্বর।
per_page	integer	20	প্রতি পৃষ্ঠায় রেকর্ড সংখ্যা (সর্বোচ্চ 100)।

উদাহরণ অনুরোধ:

GET /api/v2/customers?page=2&per_page=50
Authorization: Bearer YOUR_TOKEN

পেজিনেটেড রেসপন্স এনভেলপ:

{
  "data": [ ... ],
  "meta": {
    "current_page": 2,
    "per_page": 50,
    "total": 523,
    "last_page": 11
  }
}

---

ত্রুটি পরিচালনা

API v1 এবং v2 উভয়ে সামঞ্জস্যপূর্ণ ত্রুটি রেসপন্স ফেরত দেয়। ত্রুটিগুলো স্ট্যান্ডার্ড HTTP স্ট্যাটাস কোড ব্যবহার করে এবং একটি স্ট্রাকচার্ড JSON বডি অন্তর্ভুক্ত করে।

ত্রুটি রেসপন্স ফরম্যাট

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "email": ["The email field is required."],
      "package_id": ["The selected package is invalid."]
    }
  }
}

সাধারণ স্ট্যাটাস কোড

স্ট্যাটাস কোড	অর্থ	সাধারণ কারণ
400	Bad Request	ত্রুটিপূর্ণ JSON বা অনুপস্থিত প্রয়োজনীয় ফিল্ড।
401	Unauthorized	অনুপস্থিত, মেয়াদোত্তীর্ণ বা অবৈধ টোকেন।
403	Forbidden	বৈধ টোকেন কিন্তু অপর্যাপ্ত অনুমতি।
404	Not Found	রিসোর্সটি বিদ্যমান নেই বা মুছে ফেলা হয়েছে।
422	Unprocessable Entity	ভ্যালিডেশন ব্যর্থ — error.details পরীক্ষা করুন।
429	Too Many Requests	রেট লিমিট অতিক্রম — নিচে রেট লিমিট দেখুন।
500	Internal Server Error	অপ্রত্যাশিত সার্ভার-সাইড ব্যর্থতা।

---

API v1 রেফারেন্স

সকল v1 endpoint /api/v1 prefix-সহ এবং POST /api/auth/login-এর মাধ্যমে পাওয়া valid Bearer token প্রয়োজন।

ড্যাশবোর্ড

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v1/dashboard	ড্যাশবোর্ড সারসংক্ষেপ
GET	/v1/noc/dashboard	NOC ড্যাশবোর্ড

গ্রাহক

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v1/customers	সকল গ্রাহক তালিকা (পেজিনেটেড)
POST	/v1/customers	নতুন গ্রাহক তৈরি
GET	/v1/customers/{id}	ID দ্বারা একটি গ্রাহক প্রাপ্ত করুন
POST	/v1/customers/{id}/action	একটি অ্যাকশন সম্পাদন করুন (স্থগিত, সক্রিয় ইত্যাদি)

উদাহরণ — গ্রাহক তৈরি:

POST /api/v1/customers
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "Rafiq Ahmed",
  "email": "[email protected]",
  "phone": "01712345678",
  "package_id": 5,
  "address": "House 12, Road 7, Dhanmondi, Dhaka",
  "connection_type": "pppoe"
}

রেসপন্স (201 Created):

{
  "data": {
    "id": 1042,
    "name": "Rafiq Ahmed",
    "email": "[email protected]",
    "phone": "01712345678",
    "package": "Premium 50 Mbps",
    "status": "active",
    "created_at": "2026-04-10T08:15:00Z"
  }
}

বিলিং

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v1/invoices	সকল ইনভয়েস তালিকা
GET	/v1/bills	সকল বিল তালিকা
GET	/v1/subscriptions	সকল সাবস্ক্রিপশন তালিকা
GET	/v1/payments	সকল পেমেন্ট তালিকা

নেটওয়ার্ক

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v1/routers	সকল রাউটার তালিকা
GET	/v1/olts	সকল OLT তালিকা

মনিটরিং

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v1/monitoring/ubiquiti	Ubiquiti ডিভাইস স্ট্যাটাস
GET	/v1/monitoring/cambium	Cambium ডিভাইস স্ট্যাটাস
GET	/v1/monitoring/access-logs	ডিভাইস অ্যাক্সেস লগ
GET	/v1/monitoring/onus	ONU তালিকা
GET	/v1/monitoring/status-checks	অবকাঠামো স্ট্যাটাস চেক
GET	/v1/monitoring/zabbix	Zabbix মনিটরিং ডেটা

SMS

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v1/sms/history	SMS ডেলিভারি ইতিহাস
GET	/v1/sms/balance	বর্তমান SMS ব্যালেন্স
POST	/v1/sms/send	একটি SMS পাঠান

উদাহরণ — SMS পাঠানো:

POST /api/v1/sms/send
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "phone": "01712345678",
  "message": "Your monthly invoice of 1,200 BDT has been generated. Please pay before April 20."
}

রেসপন্স (200 OK):

{
  "data": {
    "message_id": "sms_8a3f2c",
    "status": "queued",
    "phone": "01712345678"
  }
}

অপারেটর

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v1/operators	সকল অপারেটর তালিকা
POST	/v1/operators	নতুন অপারেটর তৈরি
PUT	/v1/operators/{id}	একটি অপারেটর আপডেট
POST	/v1/operators/{id}/suspend	একটি অপারেটর স্থগিত
POST	/v1/operators/{id}/fund	অপারেটরে তহবিল যোগ

VPN

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v1/vpn/accounts	VPN অ্যাকাউন্ট তালিকা
GET	/v1/vpn/accounts/{account}/config	VPN কনফিগ ফাইল ডাউনলোড

লগ

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v1/logs/router	রাউটার লগ
GET	/v1/logs/hotspot	হটস্পট লগ
GET	/v1/logs/ppp-auth	PPP প্রমাণীকরণ লগ
GET	/v1/logs/auto-suspension	স্বয়ংক্রিয় স্থগিতকরণ লগ

রিচার্জ কার্ড

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v1/recharge-cards	সকল রিচার্জ কার্ড তালিকা

---

API v2 রেফারেন্স

সকল v2 endpoint /api/v2 prefix-সহ। Authentication উপরে বর্ণিত client-credentials flow ব্যবহার করে। V2 endpoint-এ per-client rate limit-ও প্রযোজ্য।

প্রমাণীকরণ

মেথড	এন্ডপয়েন্ট	বিবরণ
POST	/v2/auth/token	একটি অ্যাক্সেস টোকেন প্রাপ্ত করুন
POST	/v2/auth/revoke	একটি অ্যাক্সেস টোকেন প্রত্যাহার করুন

গ্রাহক

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v2/customers	গ্রাহক তালিকা (পেজিনেটেড)
POST	/v2/customers	একটি গ্রাহক তৈরি
GET	/v2/customers/{id}	একটি গ্রাহক প্রাপ্ত করুন
PUT	/v2/customers/{id}	একটি গ্রাহক আপডেট
DELETE	/v2/customers/{id}	একটি গ্রাহক মুছুন
GET	/v2/customers/{id}/bills	গ্রাহকের বিল
GET	/v2/customers/{id}/payments	গ্রাহকের পেমেন্ট
GET	/v2/customers/{id}/subscriptions	গ্রাহকের সাবস্ক্রিপশন
GET	/v2/customers/{id}/usage	গ্রাহকের ব্যবহার পরিসংখ্যান

উদাহরণ — গ্রাহক তৈরি:

POST /api/v2/customers
Authorization: Bearer v2_YOUR_TOKEN
Content-Type: application/json

{
  "name": "Fatima Begum",
  "email": "[email protected]",
  "phone": "01898765432",
  "package_id": 12,
  "address": "Apt 4B, Gulshan Tower, Dhaka",
  "connection_type": "fiber",
  "onu_mac": "AA:BB:CC:DD:EE:FF"
}

রেসপন্স (201 Created):

{
  "data": {
    "id": 2087,
    "name": "Fatima Begum",
    "email": "[email protected]",
    "phone": "01898765432",
    "package": {
      "id": 12,
      "name": "Fiber 100 Mbps"
    },
    "connection_type": "fiber",
    "status": "active",
    "created_at": "2026-04-12T14:22:00Z",
    "updated_at": "2026-04-12T14:22:00Z"
  }
}

উদাহরণ — গ্রাহক আপডেট:

PUT /api/v2/customers/2087
Authorization: Bearer v2_YOUR_TOKEN
Content-Type: application/json

{
  "package_id": 15,
  "address": "Suite 6A, Banani Heights, Dhaka"
}

রেসপন্স (200 OK):

{
  "data": {
    "id": 2087,
    "name": "Fatima Begum",
    "package": {
      "id": 15,
      "name": "Fiber 200 Mbps"
    },
    "address": "Suite 6A, Banani Heights, Dhaka",
    "status": "active",
    "updated_at": "2026-04-13T09:05:00Z"
  }
}

বিলিং

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v2/billing/bills	সকল বিল তালিকা
POST	/v2/billing/bills	একটি বিল তৈরি
GET	/v2/billing/bills/{id}	একটি বিল প্রাপ্ত করুন
PUT	/v2/billing/bills/{id}	একটি বিল আপডেট
DELETE	/v2/billing/bills/{id}	একটি বিল মুছুন
GET	/v2/billing/payments	সকল পেমেন্ট তালিকা

উদাহরণ — বিল তৈরি:

POST /api/v2/billing/bills
Authorization: Bearer v2_YOUR_TOKEN
Content-Type: application/json

{
  "customer_id": 2087,
  "amount": 1500,
  "currency": "BDT",
  "due_date": "2026-05-01",
  "description": "Monthly subscription — Fiber 200 Mbps (May 2026)"
}

রেসপন্স (201 Created):

{
  "data": {
    "id": 8431,
    "customer_id": 2087,
    "amount": 1500,
    "currency": "BDT",
    "status": "unpaid",
    "due_date": "2026-05-01",
    "description": "Monthly subscription — Fiber 200 Mbps (May 2026)",
    "created_at": "2026-04-15T00:00:00Z"
  }
}

প্যাকেজ

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v2/packages	সকল প্যাকেজ তালিকা

নেটওয়ার্ক

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v2/network/routers	সকল রাউটার তালিকা
GET	/v2/network/olts	সকল OLT তালিকা
GET	/v2/network/onus	সকল ONU তালিকা
GET	/v2/network/pools	সকল IP পুল তালিকা

মনিটরিং

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v2/monitoring/zabbix/hosts	Zabbix হোস্ট
GET	/v2/monitoring/zabbix/problems	Zabbix সক্রিয় সমস্যা
GET	/v2/monitoring/devices	ডিভাইস স্ট্যাটাস ওভারভিউ
GET	/v2/monitoring/status-checks	অবকাঠামো স্ট্যাটাস চেক

SMS

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v2/sms/balance	বর্তমান SMS ব্যালেন্স
POST	/v2/sms/send	একজন প্রাপককে SMS পাঠান
POST	/v2/sms/broadcast	একাধিক প্রাপককে SMS ব্রডকাস্ট

উদাহরণ — SMS পাঠানো:

POST /api/v2/sms/send
Authorization: Bearer v2_YOUR_TOKEN
Content-Type: application/json

{
  "phone": "01712345678",
  "message": "Dear customer, your payment of 1,500 BDT has been received. Thank you!"
}

রেসপন্স (200 OK):

{
  "data": {
    "message_id": "sms_v2_e4c19b",
    "status": "queued",
    "phone": "01712345678",
    "credits_used": 1,
    "credits_remaining": 4820
  }
}

উদাহরণ — SMS ব্রডকাস্ট:

POST /api/v2/sms/broadcast
Authorization: Bearer v2_YOUR_TOKEN
Content-Type: application/json

{
  "phones": ["01712345678", "01898765432", "01611223344"],
  "message": "Scheduled maintenance tonight from 02:00–04:00 AM. Service may be briefly interrupted."
}

VPN

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v2/vpn/accounts	VPN অ্যাকাউন্ট তালিকা
GET	/v2/vpn/accounts/{id}/config	VPN কনফিগ ফাইল ডাউনলোড

ওয়েবহুক (শুধুমাত্র v2)

মেথড	এন্ডপয়েন্ট	বিবরণ
GET	/v2/webhooks	সকল ওয়েবহুক তালিকা
POST	/v2/webhooks	একটি ওয়েবহুক তৈরি
PUT	/v2/webhooks/{id}	একটি ওয়েবহুক আপডেট
DELETE	/v2/webhooks/{id}	একটি ওয়েবহুক মুছুন

---

ওয়েবহুক

ওয়েবহুক ISPbills-কে আপনার বাহ্যিক সিস্টেমে রিয়েল-টাইম ইভেন্ট বিজ্ঞপ্তি পুশ করতে দেয়। API পোলিং করার পরিবর্তে, একটি সাবস্ক্রাইব করা ইভেন্ট ঘটলে আপনার সার্ভার একটি HTTP POST অনুরোধ পায়।

ওয়েবহুক সেটআপ

অ্যাডমিন প্যানেলের মাধ্যমে:

1. Integrations → API Management → Webhooks-এ যান।
2. Add Webhook Endpoint ক্লিক করুন।
3. আপনার সার্ভার এন্ডপয়েন্টের URL লিখুন যা ওয়েবহুক পেলোড গ্রহণ করবে।
4. আপনি যে ইভেন্ট সাবস্ক্রাইব করতে চান তা নির্বাচন করুন।
5. Save ক্লিক করুন।

API-এর মাধ্যমে (শুধুমাত্র v2):

POST /api/v2/webhooks
Authorization: Bearer v2_YOUR_TOKEN
Content-Type: application/json

{
  "url": "https://your-server.example/webhooks/ispbills",
  "events": ["customer.created", "payment.received", "bill.generated"],
  "active": true
}

ওয়েবহুক ইভেন্ট

ইভেন্ট	ট্রিগার
customer.created	একটি নতুন গ্রাহক নিবন্ধিত হয়েছে
customer.suspended	একটি গ্রাহক অ্যাকাউন্ট স্থগিত করা হয়েছে
customer.activated	একটি গ্রাহক অ্যাকাউন্ট সক্রিয় বা পুনঃসক্রিয় করা হয়েছে
payment.received	একটি পেমেন্ট রেকর্ড বা যাচাই করা হয়েছে
bill.generated	একটি নতুন বিল তৈরি হয়েছে
complaint.created	একটি নতুন সাপোর্ট অভিযোগ জমা দেওয়া হয়েছে

ওয়েবহুক পেলোড

প্রতিটি ওয়েবহুক ইভেন্টের ধরন, টাইমস্ট্যাম্প এবং প্রাসঙ্গিক ডেটা সম্বলিত একটি JSON বডি সহ একটি HTTP POST অনুরোধ পাঠায়:

{
  "event": "payment.received",
  "timestamp": "2026-03-15T10:30:00Z",
  "data": {
    "customer_id": 1234,
    "amount": 500,
    "currency": "BDT",
    "method": "bkash",
    "transaction_id": "TXN-9876"
  }
}

ওয়েবহুক স্বাক্ষর যাচাই

প্রতিটি ওয়েবহুক অনুরোধে HMAC-SHA256 স্বাক্ষর সম্বলিত একটি X-Signature হেডার অন্তর্ভুক্ত থাকে। অনুরোধটি ISPbills থেকে এসেছে কিনা নিশ্চিত করতে সবসময় আপনার সার্ভারে এই স্বাক্ষর যাচাই করুন।

যাচাইয়ের পদক্ষেপ:

1. কাঁচা অনুরোধ বডি ঠিক যেভাবে পেয়েছেন সেভাবে পড়ুন (পার্স এবং পুনঃসিরিয়ালাইজ করবেন না)।
2. আপনার ওয়েবহুক সিক্রেট ব্যবহার করে বডির একটি HMAC-SHA256 হ্যাশ গণনা করুন।
3. একটি টাইমিং-সেফ তুলনা ব্যবহার করে গণনাকৃত হ্যাশকে X-Signature-এর মানের সাথে তুলনা করুন।
4. স্বাক্ষর মিলে না গেলে অনুরোধ প্রত্যাখ্যান করুন।

---

রেট লিমিট

সুষ্ঠু ব্যবহার এবং প্ল্যাটফর্ম স্থিতিশীলতা নিশ্চিত করতে, API অনুরোধ প্রতি ক্লায়েন্ট রেট-লিমিটেড।

API সংস্করণ	টিয়ার	প্রতি মিনিটে অনুরোধ	নোট
v1	স্ট্যান্ডার্ড	60	সকল v1 ক্লায়েন্টের জন্য ডিফল্ট
v1	হাই-ভলিউম	120	আপগ্রেডের জন্য সাপোর্টে যোগাযোগ করুন
v2	স্ট্যান্ডার্ড	120	সকল v2 ক্লায়েন্টের জন্য ডিফল্ট
v2	হাই-ভলিউম	300	আপগ্রেডের জন্য সাপোর্টে যোগাযোগ করুন

রেট লিমিট অতিক্রম হলে, API নিম্নলিখিত হেডার সহ একটি 429 Too Many Requests রেসপন্স ফেরত দেয়:

হেডার	বিবরণ
Retry-After	পরবর্তী অনুরোধ পাঠানোর আগে অপেক্ষার সেকেন্ড
X-RateLimit-Limit	বর্তমান উইন্ডোতে সর্বোচ্চ অনুমোদিত অনুরোধ
X-RateLimit-Remaining	বর্তমান উইন্ডোতে অবশিষ্ট অনুরোধ

---

সাহায্য পাওয়া

• API রেসপন্সে error অবজেক্ট পরীক্ষা করুন — এতে কার্যকরী বার্তা এবং প্রতি-ফিল্ড বিবরণ রয়েছে।
• অনুরোধ ইতিহাস এবং ডিবাগিংয়ের জন্য অ্যাডমিন প্যানেলে (Integrations → API Management → Logs) API Request Log পর্যালোচনা করুন।
• আপনার ISPbills ইনস্টলেশনে /docs/api-তে পাঠানো রুট-স্তরের ডকুমেন্টেশন দেখুন।
• কাস্টম ইন্টিগ্রেশনে সহায়তা প্রয়োজন হলে বা রেট-লিমিট বৃদ্ধি অনুরোধ করতে ISPbills সাপোর্টে যোগাযোগ করুন।