شروع کار با API

برای فراخوانی هر متد کافی است Base URL و کلید API را داشته باشید. مسیر پیشنهادی: کلید را از پنل بگیرید ← هدر X-API-KEY را بفرستید ← یکی از متدهای ارسال را تست کنید.

آدرس پایه

BASE https://api.sms.ir/v1

احراز هویت

به‌منظور هویت‌سنجی در هنگام استفاده از وب‌سرویس‌های SMS.ir، ملزم به ارسال کلید خصوصی در بخش هدر درخواست می‌باشید. کلیدهای خصوصی شما در پنل برنامه‌نویسان قابل مشاهده و مدیریت هستند.

HTTP Request Header

برای انجام تنظیمات ضروری یا شخصی‌سازی‌شده، از هدرهای مشخص‌شده در جدول زیر استفاده کنید.

کلید	مقدار	عملکرد
ACCEPT	`application/json` یا `application/xml`	دریافت خروجی با فرمت Json یا Xml
X-API-KEY	کلید تعریف‌شده در پنل	احراز هویت
Content-Type	`application/json`	الزامی برای درخواست‌های POST با بدنه JSON

مدل بازگشتی (Global Response)

تمامی درخواست‌های ارسالی دارای مدل بازگشتی یکپارچه با ساختار زیر می‌باشند:

مشخصه	توضیح
status	کد وضعیت عملیات (مطابق جدول کدهای وضعیت)
message	توضیحات وضعیت درخواست
data	دیتای بازگشتی؛ نوع آن بسته به متد فراخوانی‌شده متفاوت است

HTTP Status Code

تمامی درخواست‌های ارسالی دارای HTTP Status Codeهای بازگشتی مطابق جدول زیر هستند:

کد وضعیت	توضیح
200	عملیات موفقیت‌آمیز
400	وقوع خطای منطقی
401	وجود خطا در فرآیند احراز هویت
429	تعداد درخواست غیرمجاز (Rate Limit)
500	خطای غیرمنتظره سمت سرور

زمان (Unix Time)

مقادیر زمانی در API به‌صورت Unix Time و بر حسب UTC هستند.

محیط Sandbox

Sandbox محیطی برای تست یکپارچگی است. ساختار URL، هدرها و JSON دقیقاً مثل Production است، اما پیامک واقعی ارسال نمی‌شود. با این محیط می‌توانید فرمت پاسخ و خطا را ببینید، بدون کسر اعتبار و بدون دریافت SMS.

قبل از شروع تست

محیط تست

Sandbox چیست؟

همان Base URL و ساختار Production، با کلید API جداگانه. پاسخ شبیه‌سازی‌شده برمی‌گردد.

فقط برای تست

هزینه

چرا پیامک نمی‌رسد؟

پیامک ارسال نمی‌شود، گزارشی در پنل ثبت نمی‌شود و اعتبار کسر نمی‌شود. فقط HTTP را می‌بینید.

بدون کسر اعتبار

کد تأیید

Verify در Sandbox

فقط با قالب تستی Sandbox کار می‌کند. قالب‌های Production اینجا معتبر نیستند.

فقط قالب تست

مقادیر مجاز Verify در Sandbox

اگر template دیگری بفرستید، خطای «قالب یافت نشد» می‌گیرید.

templateId 123456 template کد تایید شما: #Code#

ساخت کلید Sandbox

وارد پنل کاربری SMS.ir شوید.
از منوی برنامه‌نویسان گزینه لیست کلیدهای API را باز کنید.
روی ایجاد کلید جدید کلیک کنید.
نوع کلید را روی Sandbox قرار دهید و کلید را ذخیره کنید.

کلید Sandbox با کلید Production فرق دارد. در آزمایشگاه API یک کلید Sandbox از پیش در هدر X-API-KEY قرار دارد تا بدون paste دستی تست کنید.

پیامک واقعی ارسال نمی‌شود و اعتبار کسر نمی‌گردد. برای Verify در Sandbox فقط templateId=123456 و قالب کد تایید شما: #Code# معتبر است.

آدرس پایه API

Sandbox و Production از یک Base URL استفاده می‌کنند. تفاوت فقط در X-API-KEY است.

BASE https://api.sms.ir/v1

هدرهای درخواست

هدر	مقدار در Sandbox	توضیح
X-API-KEY	کلید Sandbox	در آزمایشگاه API از پیش تنظیم شده
Accept	application/json	پیش‌فرض اکثر endpointها
Accept	text/plain	فقط برای `POST /send/verify`
Content-Type	application/json	برای POST/DELETE با بدنه JSON

پارامترهای Verify در Sandbox

پارامتر	نوع	مقدار مجاز در Sandbox	توضیح
mobile	String	هر شماره معتبر	فقط برای ساختار درخواست؛ SMS ارسال نمی‌شود
templateId	Integer	فقط این مقدار 123456	سایر شناسه‌ها خطای «قالب یافت نشد» می‌دهند
parameters	Array	نام متغیر Code نمونه JSON [{"name":"Code","value":"12345"}]	`name` باید با متغیر قالب (#Code#) یکی باشد

نمونه درخواست Verify (Sandbox)

نمونه پاسخ

برای تست زنده endpointها به آزمایشگاه API بروید. این بخش فقط مستندات است و درخواست HTTP از اینجا ارسال نمی‌شود.

آزمایشگاه API

اینجا می‌توانید endpointها را با کلید Sandbox به https://api.sms.ir/v1 بفرستید و پاسخ سرور را ببینید. preset انتخاب کنید، در صورت نیاز JSON را ویرایش کنید و ارسال بزنید.

Sandbox

پیامک واقعی ارسال نمی‌شود. این بخش فقط برای تست درخواست HTTP و دیدن پاسخ است: status code، JSON خطا، ساختار data و زمان پاسخ. اعتبار کسر نمی‌شود و گزارشی در پنل ثبت نمی‌شود.

Endpoint

Response

Body · application/json

Query params

Headers

cURL را paste کنید. Method، URL، Header و Body در فرم بالا ست می‌شود.

آماده

ارسال گروهی (Bulk)

این متد برای ارسال یک متن پیامک به گروهی از شماره موبایل‌ها مورد استفاده قرار می‌گیرد. با مقداردهی به پارامتر sendDateTime می‌توانید از قابلیت ارسال زمان‌بندی‌شده استفاده کنید.

حداکثر تعداد مجاز شماره‌های مقصد: 100
زمان معتبر برای ارسال زمان‌بندی‌شده، از یک ساعت آینده تا حداکثر 365 روز آینده است.

POST https://api.sms.ir/v1/send/bulk

پارامترهای بدنه درخواست

پارامتر	نوع	وضعیت	توضیح
lineNumber	Long	اجباری	شماره خط ارسالی
messageText	String	اجباری	متن پیام کوتاه
mobiles	Array[String]	اجباری	شماره موبایل‌ها
sendDateTime	UnixTime	اختیاری	زمان ارسال پیامک در آینده (خالی = ارسال در لحظه)

نمونه کد یکپارچه

using System.Net.Http.Json;

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sms.ir/v1/send/bulk");
request.Headers.Add("X-API-KEY", "YOUR_API_KEY");

var payload = new {
    lineNumber = 30004505000017,
    messageText = "متن پیام شما اینجا قرار می‌گیرد",
    mobiles = new[] { "09120000000" }
};

request.Content = JsonContent.Create(payload);
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

<?php
$curl = curl_init();

$payload = [
    "lineNumber" => 30004505000017,
    "messageText" => "متن پیام شما اینجا قرار می‌گیرد",
    "mobiles" => ["09120000000"]
];

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.sms.ir/v1/send/bulk',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_HTTPHEADER => [
    'X-API-KEY: YOUR_API_KEY',
    'Content-Type: application/json'
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;

const axios = require('axios');

const payload = {
  lineNumber: 30004505000017,
  messageText: "متن پیام شما اینجا قرار می‌گیرد",
  mobiles: ["09120000000"]
};

axios.post('https://api.sms.ir/v1/send/bulk', payload, {
  headers: {
    'X-API-KEY': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
}).then(res => console.log(res.data));

import requests

url = "https://api.sms.ir/v1/send/bulk"
payload = {
    "lineNumber": 30004505000017,
    "messageText": "متن پیام شما اینجا قرار می‌گیرد",
    "mobiles": ["09120000000"]
}
headers = {
    "X-API-KEY": "YOUR_API_KEY"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://api.sms.ir/v1/send/bulk"
    payload := map[string]interface{}{
        "lineNumber":  30004505000017,
        "messageText": "متن پیام شما اینجا قرار می‌گیرد",
        "mobiles":     []string{"09120000000"},
    }
    jsonData, _ := json.Marshal(payload)
    
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("X-API-KEY", "YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

curl -X POST "https://api.sms.ir/v1/send/bulk" \\
  -H "X-API-KEY: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "lineNumber": 30004505000017,
    "messageText": "متن پیام شما اینجا قرار می‌گیرد",
    "mobiles": ["09120000000"]
  }'

در آرایه messageIds مقدار 0 یعنی شماره در لیست سیاه است؛ مقدار null یعنی شماره نامعتبر یا متن بیش از حد مجاز.

ارسال نظیر به نظیر (Like To Like)

این متد برای ارسال متن‌های متفاوت به شماره‌های مختلف استفاده می‌شود. تعداد موبایل‌ها و متن‌ها باید دقیقاً برابر باشند.

POST https://api.sms.ir/v1/send/likeToLike

پارامتر	نوع	وضعیت	توضیح
lineNumber	Long	اجباری	شماره خط ارسالی
messageTexts	Array[String]	اجباری	متن پیام‌ها
mobiles	Array[String]	اجباری	شماره موبایل‌ها
sendDateTime	UnixTime	اختیاری	زمان ارسال

حداکثر تعداد مجاز شماره‌های مقصد: 100

using System.Net.Http.Json;

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sms.ir/v1/send/likeToLike");
request.Headers.Add("X-API-KEY", "YOUR_API_KEY");

var payload = new {
    lineNumber = 30004505000017,
    messageTexts = new[] { "پیام اختصاصی یک", "پیام اختصاصی دو" },
    mobiles = new[] { "09120000001", "09120000002" }
};

request.Content = JsonContent.Create(payload);
var response = await client.SendAsync(request);

<?php
$curl = curl_init();

$payload = [
    "lineNumber" => 30004505000017,
    "messageTexts" => ["پیام اختصاصی یک", "پیام اختصاصی دو"],
    "mobiles" => ["09120000001", "09120000002"]
];

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.sms.ir/v1/send/likeToLike',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_HTTPHEADER => [ 'X-API-KEY: YOUR_API_KEY', 'Content-Type: application/json' ],
]);

$response = curl_exec($curl);

const axios = require('axios');

const payload = {
  lineNumber: 30004505000017,
  messageTexts: ["پیام اختصاصی یک", "پیام اختصاصی دو"],
  mobiles: ["09120000001", "09120000002"]
};

axios.post('https://api.sms.ir/v1/send/likeToLike', payload, {
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
}).then(res => console.log(res.data));

import requests

url = "https://api.sms.ir/v1/send/likeToLike"
payload = {
    "lineNumber": 30004505000017,
    "messageTexts": ["پیام اختصاصی یک", "پیام اختصاصی دو"],
    "mobiles": ["09120000001", "09120000002"]
}
headers = { "X-API-KEY": "YOUR_API_KEY" }

response = requests.post(url, json=payload, headers=headers)

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    payload := map[string]interface{}{
        "lineNumber":  30004505000017,
        "messageTexts": []string{"پیام اختصاصی یک", "پیام اختصاصی دو"},
        "mobiles":     []string{"09120000001", "09120000002"},
    }
    jsonData, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.sms.ir/v1/send/likeToLike", bytes.NewBuffer(jsonData))
    req.Header.Set("X-API-KEY", "YOUR_API_KEY")
    client := &http.Client{}
    client.Do(req)
}

curl -X POST "https://api.sms.ir/v1/send/likeToLike" \\
  -H "X-API-KEY: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "lineNumber": 30004505000017,
    "messageTexts": ["پیام اختصاصی یک", "پیام اختصاصی دو"],
    "mobiles": ["09120000001", "09120000002"]
  }'

در آرایه messageIds مقدار 0 یعنی شماره در لیست سیاه است؛ مقدار null یعنی شماره نامعتبر یا متن بیش از حد مجاز.

ارسال Verify (کد تأیید)

برای OTP و پیامک الگومند: متن از قالب تأیید‌شده پنل می‌آید؛ در API فقط شماره، templateId و مقادیر متغیرها را می‌فرستید.

خط خدماتی · عبور از بلک‌لیست متن از قالب پنل پاسخ اغلب text/plain

از قالب تا درخواست

در پنل، از برنامه‌نویسان وارد قالب‌های ارسال سریع شوید و قالب بسازید.
متغیرها را با نام انگلیسی بین دو # بنویسید؛ مثلاً:

نمونه متن قالب

کد تأیید شما: #Code#

بعد از تأیید، شناسه قالب را بردارید و در درخواست بفرستید.
در JSON، همان نام را بدون # بگذارید:

#Code# name: Code value: 12345

هدر پیشنهادی: Accept: text/plain. نام پارامترها به حروف بزرگ و کوچک حساس است.

Endpoint

POST https://api.sms.ir/v1/send/verify

بدنه درخواست (Request Body)

پارامتر	نوع	وضعیت	توضیح
mobile	String	اجباری	شماره موبایل گیرنده
templateId	Integer	اجباری	شناسه قالب (قالب‌ها در پنل تعریف می‌شوند)
parameters	Array[Parameter]	اجباری	آرایه‌ای از مدل Parameter برای جایگزینی

مدل Parameter

پارامتر	نوع	وضعیت	توضیح
name	String	اجباری	نام متغیر در قالب، بدون # (مثلاً Code)
value	String	اجباری	مقدار جایگزین؛ حداکثر ۲۵ کاراکتر

ساختار JSON

نمونه بدنه درخواست Verify. مقادیر را با قالب و شماره خود جایگزین کنید:

نمونه کد

using System.Net.Http.Json;

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sms.ir/v1/send/verify");
request.Headers.Add("X-API-KEY", "YOUR_API_KEY");
request.Headers.Add("Accept", "text/plain");

var payload = new {
    mobile = "09190000000",
    templateId = 123456,
    parameters = new[] {
        new { name = "Code", value = "12345" }
    }
};

request.Content = JsonContent.Create(payload);
var response = await client.SendAsync(request);

<?php
$curl = curl_init();

$payload = [
    "mobile" => "09190000000",
    "templateId" => 123456,
    "parameters" => [
        ["name" => "Code", "value" => "12345"]
    ]
];

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.sms.ir/v1/send/verify',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_HTTPHEADER => ['X-API-KEY: YOUR_API_KEY', 'Content-Type: application/json', 'Accept: text/plain'],
]);

$response = curl_exec($curl);

const axios = require('axios');

const payload = {
  mobile: "09190000000",
  templateId: 123456,
  parameters: [{ name: "Code", value: "12345" }]
};

axios.post('https://api.sms.ir/v1/send/verify', payload, {
  headers: { 'X-API-KEY': 'YOUR_API_KEY', 'Accept': 'text/plain' }
}).then(res => console.log(res.data));

import requests

url = "https://api.sms.ir/v1/send/verify"
payload = {
    "mobile": "09190000000",
    "templateId": 123456,
    "parameters": [{"name": "Code", "value": "12345"}]
}
headers = { "X-API-KEY": "YOUR_API_KEY", "Accept": "text/plain" }

response = requests.post(url, json=payload, headers=headers)

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    payload := map[string]interface{}{
        "mobile":     "09190000000",
        "templateId": 123456,
        "parameters": []map[string]string{
            {"name": "Code", "value": "12345"},
        },
    }
    jsonData, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.sms.ir/v1/send/verify", bytes.NewBuffer(jsonData))
    req.Header.Set("X-API-KEY", "YOUR_API_KEY")
    req.Header.Set("Accept", "text/plain")
    client := &http.Client{}
    client.Do(req)
}

curl -X POST "https://api.sms.ir/v1/send/verify" \\
  -H "X-API-KEY: YOUR_API_KEY" \\
  -H "Accept: text/plain" \\
  -H "Content-Type: application/json" \\
  -d '{
    "mobile": "09190000000",
    "templateId": 123456,
    "parameters": [{"name": "Code", "value": "12345"}]
  }'

پاسخ سرور

ابزار ساخت JSON از قالب Verify

متن قالب را وارد کنید، مقادیر متغیرها را تنظیم کنید و JSON آماده را کپی یا در Sandbox تست کنید.

قالب در پنل، برنامه‌نویسان، قالب‌های ارسال سریع ساخته می‌شود. متن قالب باید حداقل یک متغیر به شکل #Name# داشته باشد؛ در JSON فیلد name همان نام بدون # است.

استفاده از قالب آزمایشی Sandbox

قالب Sandbox مخصوص تست API است و از قبل روی سرور تنظیم شده: templateId = 123456 با متن کد تأیید شما: #Code#.

قالب‌های پنل Production در Sandbox پشتیبانی نمی‌شوند. پیامک واقعی ارسال نمی‌شود و اعتباری کسر نمی‌شود.

templateId

mobile هر سه فرمت مجاز است 9123456789 09123456789 989123456789

متن قالب حداقل یک متغیر بین دو # لازم است؛ مثلاً #Code#

پارامترها: مقادیر متغیرها

متن قالب را وارد کنید؛ متغیرهای #Name# اینجا ظاهر می‌شوند.

پیش‌نمایش پیامک

...

خروجی JSON

{}

ارسال از طریق URL

این متد برای ارسال پیامک از طریق URL مورد استفاده قرار می‌گیرد. کافی است پارامترهای مورد نیاز را در قالب Query Params در آدرس مشخص‌شده قرار دهید. متد قابل استفاده: GET و POST.

GET https://api.sms.ir/v1/send

پارامتر	نوع	وضعیت	توضیح
username	String	اجباری	نام کاربری
password	String	اجباری	کلید خصوصی (از پنل برنامه‌نویسان)
line	Long	اجباری	شماره خط
mobile	String	اجباری	شماره موبایل
text	String	اجباری	متن پیامک

حذف ارسال زمان‌بندی‌شده

حداکثر تا 3 دقیقه مانده به زمان ارسال، مجاز به لغو آن می‌باشید.

DELETE https://api.sms.ir/v1/send/scheduled/{packId}

پارامتر	نوع	وضعیت	توضیح
packId	Guid	اجباری	شناسه مجموعه ارسال (در URL)

نمونه کد

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-KEY", "YOUR_API_KEY");
var response = await client.DeleteAsync(
    "https://api.sms.ir/v1/send/scheduled/2b99e63c-9bf8-4a21-9bfe-3f72dc1b46f1");
Console.WriteLine(await response.Content.ReadAsStringAsync());

$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.sms.ir/v1/send/scheduled/2b99e63c-9bf8-4a21-9bfe-3f72dc1b46f1',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_HTTPHEADER => ['X-API-KEY: YOUR_API_KEY'],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;

const axios = require('axios');

axios.delete('https://api.sms.ir/v1/send/scheduled/2b99e63c-9bf8-4a21-9bfe-3f72dc1b46f1', {
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
}).then(res => console.log(res.data));

import requests

url = "https://api.sms.ir/v1/send/scheduled/2b99e63c-9bf8-4a21-9bfe-3f72dc1b46f1"
headers = { "X-API-KEY": "YOUR_API_KEY" }
response = requests.delete(url, headers=headers)
print(response.json())

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://api.sms.ir/v1/send/scheduled/2b99e63c-9bf8-4a21-9bfe-3f72dc1b46f1", nil)
    req.Header.Set("X-API-KEY", "YOUR_API_KEY")
    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)
    fmt.Println(string(body))
}

curl -X DELETE "https://api.sms.ir/v1/send/scheduled/2b99e63c-9bf8-4a21-9bfe-3f72dc1b46f1" \\
  -H "X-API-KEY: YOUR_API_KEY"

گزارش‌های ارسال پیامک

با متدهای این بخش می‌توانید وضعیت ارسال، دلیوری و آرشیو پیامک‌های ارسالی را پیگیری کنید.

گزارش پیامک: دریافت وضعیت

با شناسه یکتای پیامک (messageId) وضعیت دلیوری (Delivery) آن قابل دریافت است.

GET https://api.sms.ir/v1/send/{messageId}

گزارش مجموعه ارسال‌های روز

اطلاعات کلی مجموعه ارسال‌های روز جاری را دریافت کنید.

GET https://api.sms.ir/v1/send/pack

پارامتر	نوع	وضعیت	توضیح
PageSize	Integer	اختیاری	تعداد آیتم در صفحه (پیش‌فرض: 100)
PageNumber	Integer	اختیاری	شماره صفحه (پیش‌فرض: 1)

گزارش مجموعه ارسال (جزئیات Pack)

با شناسه مجموعه ارسال (packId)، گزارش پیامک‌های ارسالی آن درخواست به‌همراه وضعیت دلیوری هرکدام را دریافت کنید.

GET https://api.sms.ir/v1/send/pack/{packId}

گزارش ارسال‌های روز (Live)

گزارشی از ارسال‌های انجام‌شده در روز جاری قابل دریافت است.

GET https://api.sms.ir/v1/send/live

پارامتر	نوع	وضعیت	توضیح
pageSize	Integer	اختیاری	تعداد آیتم در صفحه (حداکثر و پیش‌فرض: 100)
pageNumber	Integer	اختیاری	شماره صفحه (پیش‌فرض: 1)
mobile	String	اختیاری	فیلتر بر اساس شماره موبایل
sortByNewest	Boolean	اختیاری	مرتب‌سازی نزولی بر اساس تاریخ (پیش‌فرض: false)

گزارش ارسال‌های آرشیو شده

گزارشی از ارسال‌های انجام‌شده در گذشته (تا انتهای روز قبل) را دریافت کنید.

GET https://api.sms.ir/v1/send/archive

پارامتر	نوع	وضعیت	توضیح
fromDate	Integer (UnixTime)	اختیاری	از تاریخ
toDate	Integer (UnixTime)	اختیاری	تا تاریخ
pageSize	Integer	اختیاری	تعداد آیتم در صفحه
pageNumber	Integer	اختیاری	شماره صفحه
mobile	String	اختیاری	فیلتر بر اساس شماره موبایل
sortByNewest	Boolean	اختیاری	مرتب‌سازی نزولی بر اساس تاریخ (پیش‌فرض: false)

گزارش‌های دریافت پیامک

متدهای این بخش برای دریافت پیامک‌های وارده به خطوط اختصاصی شما استفاده می‌شوند.

گزارش تازه‌ترین پیامک‌های دریافتی

تازه‌ترین پیامک‌های دریافتی را مشاهده کنید. هر پیامک دریافتی تنها یک‌بار توسط این متد قابل دسترسی است و پس از خوانده شدن، دیگر برنمی‌گردد.

GET https://api.sms.ir/v1/receive/latest

پارامتر	نوع	وضعیت	توضیح
count	Integer	اختیاری	تعداد درخواستی (حداکثر و پیش‌فرض: 100)

گزارش پیامک‌های دریافتی روز

گزارش پیامک‌های دریافتی روز جاری (خوانده‌شده و نشده). در آغاز ساعات روز، گزارش پیام‌های دریافتی روز گذشته نیز با همین متد قابل دریافت است.

GET https://api.sms.ir/v1/receive/live

پارامتر	نوع	وضعیت	توضیح
pageSize	Integer	اختیاری	تعداد آیتم در صفحه (حداکثر: 100)
pageNumber	Integer	اختیاری	شماره صفحه
sortByNewest	Boolean	اختیاری	مرتب‌سازی بر اساس تاریخ (پیش‌فرض: false)
mobile	String	اختیاری	فیلتر بر اساس شماره فرستنده

گزارش پیامک‌های دریافتی آرشیو شده

گزارشی از پیامک‌های دریافتی در گذشته (تا انتهای روز قبل).

GET https://api.sms.ir/v1/receive/archive

پارامتر	نوع	وضعیت	توضیح
fromDate	Integer (UnixTime)	اختیاری	از تاریخ
toDate	Integer (UnixTime)	اختیاری	تا تاریخ
pageSize	Integer	اختیاری	تعداد آیتم در صفحه
pageNumber	Integer	اختیاری	شماره صفحه
mobile	String	اختیاری	فیلتر بر اساس شماره فرستنده

تنظیمات (اعتبار و خطوط)

دریافت مقدار اعتبار فعلی

برای مشاهده مقدار اعتبار فعلی پنل از متد زیر استفاده کنید.

GET https://api.sms.ir/v1/credit

دریافت لیست خطوط

با این متد، لیست خطوط آماده استفاده برای ارسال قابل مشاهده است.

GET https://api.sms.ir/v1/line

کدهای وضعیت و خطا

فیلد status در پاسخ API معنای عملیات را مشخص می‌کند. کد 1 به معنای موفقیت است؛ سایر کدها خطا یا هشدار را نشان می‌دهند.

کدهای وضعیت سیستم

کد	توضیح	کد	توضیح
1	عملیات با موفقیت انجام شد	106	تعداد متن‌ها بیش از حد مجاز (100)
0	مشکلی در سامانه رخ داده؛ با پشتیبانی تماس بگیرید	107	لیست موبایل‌ها خالی است
10	کلید وب‌سرویس نامعتبر است	108	لیست متن‌ها خالی است
11	کلید وب‌سرویس غیرفعال است	109	زمان ارسال نامعتبر است
12	کلید محدود به IPهای تعریف‌شده است	110	تعداد موبایل‌ها و متن‌ها برابر نیستند
13	حساب کاربری غیرفعال است	111	با این شناسه ارسالی ثبت نشده است
14	حساب کاربری در حالت تعلیق است	112	رکوردی برای حذف یافت نشد
20	تعداد درخواست بیش از حد مجاز	113	قالب یافت نشد
101	شماره خط نامعتبر است	114	طول مقدار پارامتر بیش از 25 کاراکتر است
102	اعتبار کافی نیست	115	شماره موبایل در لیست سیاه سامانه است
103	درخواست دارای متن(های) خالی است	116	نام پارامتر نمی‌تواند خالی باشد
104	درخواست دارای موبایل(های) نادرست است	117	متن ارسال‌شده مورد تأیید نیست
105	تعداد موبایل‌ها بیش از 100 است	118	تعداد پیام‌ها بیش از حد مجاز است
		119	برای قالب شخصی‌سازی‌شده پلن را ارتقا دهید
		123	خط ارسال‌کننده نیاز به فعال‌سازی دارد

کدهای وضعیت دلیوری (DeliveryState)

در گزارش‌های ارسال، فیلد deliveryState وضعیت رسیدن پیامک به گوشی را نشان می‌دهد:

کد	توضیح	کد	توضیح
1	رسیده به گوشی	5	رسیده به مخابرات
2	نرسیده به گوشی	6	خطا
3	پردازش در مخابرات	7	لیست سیاه
4	نرسیده به مخابرات

تنظیمات امنیتی و لیست سفید (IP Whitelisting)

اگر در سرویس خود نیاز به محدودیت دسترسی (IP Restriction) دارید، برای جلوگیری از مسدود شدن درخواست‌ها هنگام Failover، هر دو IP زیر را در فایروال سرور خود مجاز (Whitelist) کنید:

Server IPs

وضعیت زنده سرویس

می‌خواهید از پایداری سرویس مطمئن شوید؟

وضعیت لحظه‌ای API، OTP و سرشماره‌ها را در مانیتورینگ SMS.ir ببینید.

--:--:-- مشاهده وضعیت ↗

شروع سریع با SDK

دستور نصب را کپی کنید و شروع کنید

پکیج رسمی Node، Laravel، Python و .NET را با یک دستور نصب کنید و بعد در آزمایشگاه API تست بگیرید.

sms.ir · install

tip: help · install · verify · api-key · clear

منابع توسعه‌دهندگان

ریپازیتوری، صفحه پکیج‌ها و وضعیت سرویس

GitHub نمونه‌کد و پکیج‌های رسمی Packages Laravel · Node · .NET · Python Status وضعیت لحظه‌ای سرویس‌ها

پکیج‌های رسمی

SDKهای آماده برای شروع سریع

همه پکیج‌ها ↗

زبان برنامه‌نویسی

ابزار تبدیل زمان به Unix Time

شروع کار با API

آدرس پایه

احراز هویت

HTTP Request Header

مدل بازگشتی (Global Response)

HTTP Status Code

زمان (Unix Time)

محیط Sandbox

Sandbox چیست؟

چرا پیامک نمی‌رسد؟

Verify در Sandbox

ساخت کلید Sandbox

آدرس پایه API

هدرهای درخواست

پارامترهای Verify در Sandbox

نمونه درخواست Verify (Sandbox)

نمونه پاسخ

آزمایشگاه API

ارسال گروهی (Bulk)

پارامترهای بدنه درخواست

نمونه کد یکپارچه

ارسال نظیر به نظیر (Like To Like)

ارسال Verify (کد تأیید)

از قالب تا درخواست

Endpoint

بدنه درخواست (Request Body)

مدل Parameter

ساختار JSON

نمونه کد

پاسخ سرور

ابزار ساخت JSON از قالب Verify

ارسال از طریق URL

حذف ارسال زمان‌بندی‌شده

نمونه کد

گزارش‌های ارسال پیامک

گزارش پیامک: دریافت وضعیت

گزارش مجموعه ارسال‌های روز

گزارش مجموعه ارسال (جزئیات Pack)

گزارش ارسال‌های روز (Live)

گزارش ارسال‌های آرشیو شده

گزارش‌های دریافت پیامک

گزارش تازه‌ترین پیامک‌های دریافتی

گزارش پیامک‌های دریافتی روز

گزارش پیامک‌های دریافتی آرشیو شده

تنظیمات (اعتبار و خطوط)

دریافت مقدار اعتبار فعلی

دریافت لیست خطوط

کدهای وضعیت و خطا

کدهای وضعیت سیستم

کدهای وضعیت دلیوری (DeliveryState)

تنظیمات امنیتی و لیست سفید (IP Whitelisting)

می‌خواهید از پایداری سرویس مطمئن شوید؟

دستور نصب را کپی کنید و شروع کنید

منابع توسعه‌دهندگان

پکیج‌های رسمی