شروع کار
خوش آمدید! این مستندات برای توسعهدهندگانی طراحی شده که میخواهند سرویس SMS را در اپلیکیشنهای خود یکپارچه کنند. با استفاده از وب سرویس ما، میتوانید به راحتی پیامکهای خود را مدیریت و ارسال کنید.
پیشنیازها
قبل از شروع به کار، مطمئن شوید که موارد زیر را دارید:
آشنایی با JWT
JSON Web Token (JWT) یک استاندارد باز (RFC 7519) برای انتقال امن اطلاعات بین طرفین در قالب JSON است. این توکنها به صورت دیجیتالی امضا میشوند و اعتبارسنجی آنها آسان است.
مزایای JWT
- • امنیت بالا
- • حجم کم
- • خودکفا و مستقل
- • سازگاری با همه زبانها
ساختار JWT
- • Header (الگوریتم)
- • Payload (دادهها)
- • Signature (امضا)
HS256 رمزنگاری شوند.
حساب کاربری
نام کاربری (username) شما که در تمام درخواستها باید ارسال شود. این شناسه منحصر به فرد شما در سیستم است.
کلید خصوصی (Secret Key)
کلید خصوصی شما برای رمزنگاری توکنهای JWT استفاده میشود. این کلید را هرگز با کسی به اشتراک نگذارید!
ارسال تکی
برای ارسال یک پیامک به یک شماره مشخص از این endpoint استفاده کنید.
پارامترهای ورودی
| پارامتر | نوع | توضیحات | وضعیت |
|---|---|---|---|
username |
string | نام کاربری حساب شما | اجباری |
token |
string | توکن JWT تولید شده | اجباری |
دادههای Payload برای JWT
| پارامتر | نوع | توضیحات | وضعیت |
|---|---|---|---|
number |
string | شماره موبایل گیرنده | اجباری |
message |
string | متن پیامک | اجباری |
پاسخ (Response)
{
"success": true,
"error": false,
"status": "success",
"code": 200,
"messages": [],
"data": null,
"total": 0
}
مثال عملی
ابتدا توکن JWT را در jwt.io بسازید:
ارسال تکی زماندار
برای ارسال پیامک در زمان مشخص (زمانبندی شده) از این endpoint استفاده کنید.
Y-m-d H:i:s
و با منطقه زمانی ایران/تهران باشد. مثال: 2024-03-21 14:30:00
دادههای Payload
| پارامتر | نوع | توضیحات | وضعیت |
|---|---|---|---|
number |
string | شماره موبایل گیرنده | اجباری |
message |
string | متن پیامک | اجباری |
scheduleDateTime |
string | زمان ارسال (Y-m-d H:i:s) | اجباری |
ارسال گروهی
برای ارسال یک پیامک به چندین شماره به صورت همزمان (حداکثر 100 شماره در هر درخواست).
دادههای Payload
| پارامتر | نوع | توضیحات | وضعیت |
|---|---|---|---|
numbers |
array | آرایهای از شماره موبایلها | اجباری |
message |
string | متن پیامک | اجباری |
{
"numbers": [
"09123456789",
"09367894561",
"09151234567"
],
"message": "پیام شما"
}
ارسال گروهی زماندار
ارسال پیامک به چندین شماره در زمان مشخص (حداکثر 100 شماره).
دادههای Payload
| پارامتر | نوع | توضیحات | وضعیت |
|---|---|---|---|
numbers |
array | آرایه شماره موبایلها | اجباری |
message |
string | متن پیامک | اجباری |
scheduleDateTime |
string | زمان ارسال | اجباری |
ارسال متناظر
ارسال پیامکهای مختلف به شمارههای مختلف به صورت یکبهیک. هر شماره پیامک مخصوص خود را دریافت میکند.
messages به اولین عنصر آرایه numbers ارسال میشود.
بنابراین تعداد و ترتیب آرایهها باید یکسان باشد.
دادههای Payload
| پارامتر | نوع | توضیحات | وضعیت |
|---|---|---|---|
numbers |
array | آرایه شماره موبایلها | اجباری |
messages |
array | آرایه متنهای پیامک | اجباری |
{
"numbers": ["09123456789", "09367894561"],
"messages": ["سلام آقای احمدی", "سلام خانم محمدی"]
}
دریافت مانده اعتبار
برای مشاهده مانده اعتبار ریالی حساب کاربری خود از این endpoint استفاده کنید.
دادههای Payload
| پارامتر | نوع | توضیحات | وضعیت |
|---|---|---|---|
username |
string | نام کاربری | اجباری |
پاسخ موفق
{
"success": true,
"error": false,
"status": "success",
"code": 200,
"messages": [],
"data": "125000", // مانده اعتبار به ریال
"total": 0
}
دریافت پیامکهای ورودی
برای دریافت لیست پیامکهای دریافتی (inbox) با قابلیت فیلتر بر اساس زمان و صفحهبندی.
دادههای Payload
| پارامتر | نوع | توضیحات | وضعیت |
|---|---|---|---|
limit |
integer | تعداد رکورد (پیشفرض: 10) | اختیاری |
offset |
integer | شروع از رکورد (پیشفرض: 0) | اختیاری |
startDateTime |
string | از تاریخ (Y-m-d H:i:s) | اختیاری |
endDateTime |
string | تا تاریخ (Y-m-d H:i:s) | اختیاری |
پاسخ موفق
{
"success": true,
"error": false,
"status": "success",
"code": 200,
"messages": [],
"data": [
{
"number": "09123456789",
"message": "متن پیامک",
"dateCreated": "2024-01-15 14:30:00"
}
],
"total": 145
}
نمونه کدها
کدهای آماده برای پیادهسازی سریع در پروژههای خود
<?php
// مقادیر پیش نیاز
$secret_key = "your-secret-key-here"; // کلید خصوصی برای ساختن JWT
$username = "your-username-key-here"; // نام کاربری حساب کاربری شما
$url = "https://deftsms.ir/api/sms/send/simple"; // آدرس وب سرویس
// شروع فرایند تولید توکن JWT
$header = [
"typ" => "JWT",
"alg" => "HS256"
];
$header = json_encode($header);
$header = base64_encode($header);
$payload = [
"number"=> "09156535299", // شماره موبایل گیرنده پیامک
"message"=> "test" // متن پیامک
];
$payload = json_encode($payload);
$payload = base64_encode($payload);
$signature = hash_hmac("sha256", "{$header}.{$payload}", $secret_key, true);
$signature = base64_encode($signature);
$token = "{$header}.{$payload}.{$signature}"; // توکن تولید شده
// پایان فرایند تولید توکن JWT
// شروع فرایند درخواست
// دیتای مورد ورودی مورد نیاز برای درخواست
$data = array(
"username" => $username,
"token" => $token
);
$options = array(
// use key "http" even if you send the request to https://...
"http" => array(
"header" => "Content-type: application/x-www-form-urlencoded\r\n",
"method" => "POST",
"content" => http_build_query($data)
)
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) { /* Handle error */ }
var_dump($result);
// پایان فرایند درخواست