# SMS API ডকুমেন্টেশন — BuySMS

একটি HTTP রিকোয়েস্টেই আপনার ওয়েবসাইট, অ্যাপ বা সফটওয়্যার থেকে SMS পাঠান। মাস্কিং ও নন-মাস্কিং, ইংরেজি ও বাংলা, একক বা বাল্ক — সাথে ডেলিভারি স্ট্যাটাস ও ব্যালেন্স চেক।

HTML: https://buysms.bd/api · OpenAPI: https://buysms.bd/openapi.json

- **বেস URL:** https://app.buysms.bd/api/v1
- **অথেনটিকেশন:** X-API-KEY হেডার (অথবা api_key প্যারামিটার)
- **ফরম্যাট:** JSON পাঠান, JSON পান (UTF-8)
- **নম্বর:** 01XXXXXXXXX, 8801XXXXXXXXX বা +8801XXXXXXXXX
- **সময় অঞ্চল:** Asia/Dhaka (UTC+6)
- **মুদ্রা:** BDT (৳)

## দ্রুত শুরু

১. অ্যাকাউন্ট খুলে https://app.buysms.bd প্যানেলে লগইন করুন।

২. Developer API পেজ থেকে আপনার API কী কপি করুন। কী গোপন রাখুন: কী যার কাছে থাকবে সে আপনার ব্যালেন্স থেকে SMS পাঠাতে পারবে।

৩. প্রথম SMS পাঠান:

**cURL**

```bash
curl -X POST "https://app.buysms.bd/api/v1/sms/send" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"01711000000,01811000000","message":"Your OTP is 4821"}'
```

**রেসপন্স**

```json
{
  "success": true,
  "batch_id": "5f0c2a1e-7b1d-4c55-9a7e-2d1f0c9b8a10",
  "queued": 2,
  "parts": 2,
  "cost": 0.70,
  "balance": 199.30,
  "invalid_numbers": [],
  "messages": [
    { "id": "b1e2c3d4-0000-4000-8000-000000000001", "to": "8801711000000" },
    { "id": "c9d0e1f2-0000-4000-8000-000000000002", "to": "8801811000000" }
  ]
}
```

## অথেনটিকেশন

প্রতিটি রিকোয়েস্টে আপনার API কী লাগবে। X-API-KEY হেডারে পাঠান (প্রস্তাবিত), অথবা কুয়েরি স্ট্রিং, ফর্ম ফিল্ড বা JSON বডিতে api_key প্যারামিটার হিসেবে।

ভুল বা অনুপস্থিত কী, অথবা নিষ্ক্রিয় অ্যাকাউন্ট হলে HTTP 401 ও কোড invalid_api_key আসবে। প্যানেল থেকে যেকোনো সময় নতুন কী তৈরি করা যায়; পুরনো কী সাথে সাথে বন্ধ হয়ে যায়।

**Header**

```text
X-API-KEY: YOUR_API_KEY
```

## SMS পাঠানো

`POST /api/v1/sms/send`  
`GET /api/v1/sms/send?api_key=…&to=…&message=…`  

একই মেসেজ এক বা একাধিক নম্বরে পাঠান। বডি হতে পারে JSON, ফর্ম ফিল্ড (application/x-www-form-urlencoded), অথবা সহজ ইন্টিগ্রেশনের জন্য GET কুয়েরি স্ট্রিং।

| প্যারামিটার | আবশ্যক | বিবরণ |
|---|---|---|
| `to` | ✔ | মোবাইল নম্বর। একাধিক নম্বর কমা দিয়ে আলাদা করুন (সেমিকোলন, স্পেস বা নতুন লাইনও চলবে)। প্রতি রিকোয়েস্টে সর্বোচ্চ ৫০,০০০। |
| `message` | ✔ | ইংরেজি বা বাংলায় SMS টেক্সট, সর্বোচ্চ ১,০০০ অক্ষর। |
| `sender_id` |  | আপনার অ্যাকাউন্টে দেওয়া মাস্কিং সেন্ডার আইডি (ব্র্যান্ড নাম)। নন-মাস্কিং হলে খালি রাখুন বা বাদ দিন। |
| `api_key` |  | X-API-KEY হেডার না পাঠালে আপনার API কী। |

**cURL (JSON)**

```bash
curl -X POST "https://app.buysms.bd/api/v1/sms/send" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"01711000000,01811000000","message":"Your OTP is 4821"}'
```

**GET URL**

```text
https://app.buysms.bd/api/v1/sms/send?api_key=YOUR_API_KEY&to=01711000000&message=Hello%20from%20BuySMS
```

**cURL (ফর্ম)**

```bash
curl -X POST "https://app.buysms.bd/api/v1/sms/send" \
  -d "api_key=YOUR_API_KEY" \
  -d "to=01711000000" \
  --data-urlencode "message=আপনার অর্ডার পাঠানো হয়েছে"
```

**PHP**

```php
<?php
$ch = curl_init("https://app.buysms.bd/api/v1/sms/send");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-KEY: YOUR_API_KEY", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode([
        "to" => "01711000000",
        "message" => "আপনার অর্ডার পাঠানো হয়েছে",
        "sender_id" => "YourBrand", // masking; leave "" for non-masking
    ]),
]);
$result = json_decode(curl_exec($ch), true);
echo $result["success"] ? "Queued: " . $result["batch_id"] : $result["error"];
```

**Python**

```python
import requests

r = requests.post("https://app.buysms.bd/api/v1/sms/send",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    json={"to": "01711000000", "message": "Your OTP is 4821"})
data = r.json()
print(data["messages"][0]["id"] if data["success"] else data["error"])
```

**Node.js**

```javascript
const res = await fetch("https://app.buysms.bd/api/v1/sms/send", {
  method: "POST",
  headers: { "X-API-KEY": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ to: "01711000000", message: "Your OTP is 4821" })
});
console.log(await res.json());
```

**C#**

```csharp
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-API-KEY", "YOUR_API_KEY");
var res = await http.PostAsJsonAsync("https://app.buysms.bd/api/v1/sms/send",
    new { to = "01711000000", message = "Your OTP is 4821" });
Console.WriteLine(await res.Content.ReadAsStringAsync());
```

**রেসপন্স**

```json
{
  "success": true,
  "batch_id": "5f0c2a1e-7b1d-4c55-9a7e-2d1f0c9b8a10",
  "queued": 2,
  "parts": 2,
  "cost": 0.70,
  "balance": 199.30,
  "invalid_numbers": [],
  "messages": [
    { "id": "b1e2c3d4-0000-4000-8000-000000000001", "to": "8801711000000" },
    { "id": "c9d0e1f2-0000-4000-8000-000000000002", "to": "8801811000000" }
  ]
}
```

- রিকোয়েস্টের খরচ সাথে সাথে কাটা হয় এবং প্রতিটি SMS ডেলিভারি কিউতে যায়।
- ভুল নম্বর বাদ দিয়ে invalid_numbers-এ দেখানো হয়; বাকিগুলো পাঠানো হয়।
- পরে ডেলিভারি স্ট্যাটাস দেখতে প্রতিটি messages[].id সংরক্ষণ করুন।

## বাল্ক SMS (প্রতি নম্বরে আলাদা মেসেজ)

`POST /api/v1/sms/bulk`  

একটি রিকোয়েস্টেই অনেক নম্বরে ব্যক্তিগত মেসেজ — বিল, OTP, নাম — পাঠান (সর্বোচ্চ ৫০,০০০টি)। পুরো রিকোয়েস্টের খরচ একবারে কাটা হয়। শুধু JSON বডি।

| প্যারামিটার | আবশ্যক | বিবরণ |
|---|---|---|
| `messages` | ✔ | { "to": "01XXXXXXXXX", "message": "টেক্সট" } অবজেক্টের অ্যারে। |
| `sender_id` |  | রিকোয়েস্টের সব মেসেজের মাস্কিং সেন্ডার আইডি। খালি = নন-মাস্কিং। |
| `api_key` |  | X-API-KEY হেডার না পাঠালে আপনার API কী। |

**cURL**

```bash
curl -X POST "https://app.buysms.bd/api/v1/sms/bulk" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "",
    "messages": [
      { "to": "01711000000", "message": "Dear Rahim, your bill is 1,200 Tk." },
      { "to": "01811000000", "message": "প্রিয় করিম, আপনার বিল ৮৫০ টাকা।" }
    ]
  }'
```

**Python**

```python
import requests

rows = [("01711000000", "Rahim", 1200), ("01811000000", "Karim", 850)]
r = requests.post("https://app.buysms.bd/api/v1/sms/bulk",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    json={"messages": [{"to": n, "message": f"Dear {name}, your bill is {amt} Tk."} for n, name, amt in rows]})
print(r.json())
```

**রেসপন্স**

```json
{
  "success": true,
  "batch_id": "5f0c2a1e-7b1d-4c55-9a7e-2d1f0c9b8a10",
  "queued": 2,
  "parts": 2,
  "cost": 0.70,
  "balance": 199.30,
  "invalid_numbers": [],
  "messages": [
    { "id": "b1e2c3d4-0000-4000-8000-000000000001", "to": "8801711000000" },
    { "id": "c9d0e1f2-0000-4000-8000-000000000002", "to": "8801811000000" }
  ]
}
```

## ডেলিভারি স্ট্যাটাস

`GET /api/v1/sms/status/{id}`  

পাঠানোর সময় পাওয়া id দিয়ে একটি মেসেজের অবস্থা দেখুন।

**cURL**

```bash
curl "https://app.buysms.bd/api/v1/sms/status/b1e2c3d4-0000-4000-8000-000000000001" \
  -H "X-API-KEY: YOUR_API_KEY"
```

**রেসপন্স**

```json
{
  "success": true,
  "id": "b1e2c3d4-0000-4000-8000-000000000001",
  "to": "8801711000000",
  "status": "sent",
  "parts": 1,
  "cost": 0.35,
  "error": null,
  "queued_at": "28 Sep 2026, 03:15 PM",
  "finished_at": "28 Sep 2026, 03:15 PM"
}
```

- status হবে: queued (অপেক্ষায়), sending (পাঠানো হচ্ছে), sent (অপারেটর গ্রহণ করেছে), failed (ব্যর্থ)।
- ব্যর্থ SMS-এর টাকা স্বয়ংক্রিয়ভাবে ব্যালেন্সে ফেরত আসে; কারণ error-এ লেখা থাকে।
- সময় বাংলাদেশ সময়ে। মেসেজ লগ ৩ মাস রাখা হয়; পুরনো id-তে 404 not_found আসে।

## ব্যালেন্স

`GET /api/v1/balance`  

আপনার বর্তমান ব্যালেন্স, প্রতি SMS-এর রেট এবং ব্যবহারযোগ্য মাস্কিং সেন্ডার আইডি।

**cURL**

```bash
curl "https://app.buysms.bd/api/v1/balance" -H "X-API-KEY: YOUR_API_KEY"
```

**রেসপন্স**

```json
{
  "success": true,
  "balance": 199.30,
  "currency": "BDT",
  "rate_non_masking": 0.35,
  "rate_masking": 0.60,
  "masking_sender_ids": ["YourBrand"]
}
```

## এরর

এররে success: false, মেশিন-রিডেবল code এবং পড়ার উপযোগী error আসে। রিকোয়েস্ট ব্যর্থ হলে কোনো টাকা কাটা হয় না।

**রেসপন্স**

```json
{
  "success": false,
  "code": "insufficient_balance",
  "error": "Insufficient balance. Needed ৳12.50, available ৳3.00.",
  "invalid_numbers": null
}
```

| HTTP | code | অর্থ |
|---|---|---|
| 401 | `invalid_api_key` | কী নেই বা ভুল, অথবা অ্যাকাউন্ট নিষ্ক্রিয়। |
| 402 | `insufficient_balance` | পুরো রিকোয়েস্টের জন্য যথেষ্ট ব্যালেন্স নেই। কিছুই কিউতে যায়নি। |
| 400 | `missing_to / missing_message / missing_messages` | আবশ্যক প্যারামিটার খালি। |
| 400 | `invalid_json` | রিকোয়েস্ট বডি সঠিক JSON নয়। |
| 400 | `rejected` | কোনো সঠিক নম্বর নেই, মেসেজ খুব বড়, মাস্কিং আইডি আপনাকে দেওয়া হয়নি, অতিরিক্ত প্রাপক ইত্যাদি। error দেখুন। |
| 404 | `not_found` | অজানা মেসেজ id, অথবা তার লগ মুছে ফেলা হয়েছে। |

## SMS দৈর্ঘ্য, মাস্কিং ও ভালো অভ্যাস

- ইংরেজি (GSM) টেক্সট: এক SMS-এ ১৬০ অক্ষর; বড় হলে প্রতি অংশে ১৫৩।
- বাংলা বা অন্য ইউনিকোড টেক্সট: এক SMS-এ ৭০ অক্ষর; বড় হলে প্রতি অংশে ৬৭।
- খরচ অংশ হিসেবে: খরচ = অংশ × আপনার রেট।
- নম্বর বাংলাদেশি মোবাইল (০১৩–০১৯)। 01XXXXXXXXX, 8801XXXXXXXXX ও +8801XXXXXXXXX সবই চলে; সংরক্ষিত হয় 8801XXXXXXXXX হিসেবে।
- মাস্কিং = সেন্ডার হিসেবে আপনার ব্র্যান্ড নাম (sender_id)। নন-মাস্কিং = সেন্ডার হিসেবে একটি নম্বর (sender_id খালি)। মাস্কিং নাম প্যানেলে অনুমোদন ও বরাদ্দ করা হয়।
- API কী আপনার সার্ভারে রাখুন। মোবাইল অ্যাপ, ওয়েব পেজ বা পাবলিক রিপোজিটরিতে কখনো রাখবেন না।
- শুধু নেটওয়ার্ক এরর বা HTTP 5xx হলে আবার চেষ্টা করুন; 4xx একই ইনপুটে আবার ব্যর্থ হবে।