مقدمه و قراردادها

در این بخش مفاهیم و قراردادهای کلی مربوط به استفاده از وب‌سرویس SMS.ir شرح داده می‌شود. پیش از فراخوانی هر متد، آشنایی با هدرها، کدهای HTTP و مدل پاسخ یکپارچه توصیه می‌شود.

HTTP Request Header

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

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

HTTP Status Code

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

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

Unix Time

واحد مقادیر مربوط به زمان در سطح این سامانه به‌صورت Unix Time و بر حسب ساعت هماهنگ جهانی (UTC) لحاظ شده است.

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

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

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

Authorization · احراز هویت

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

محیط Sandbox

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

ساخت کلید Sandbox

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

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

🧪

Sandbox چیست؟

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

📵

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

هیچ SMS ارسال نمی‌شود، گزارشی در پنل ثبت نمی‌شود و اعتبار کسر نمی‌شود.

📋

Verify در Sandbox

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

قالب‌هایی که در پنل Production ساخته‌اید با کلید Sandbox کار نمی‌کنند و خطای «قالب یافت نشد» برمی‌گردند.

آدرس پایه 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	`[{ "name": "Code", "value": "..." }]`	`name` باید با متغیر قالب (#Code#) یکی باشد

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

نمونه پاسخ

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

آزمایشگاه API

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

Sandbox

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

Endpoint

پاسخ

بدنه · 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	اختیاری	زمان ارسال پیامک در آینده (خالی = ارسال در لحظه)

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

HttpClient + JsonContent.Create؛ هدر X-API-KEY را در DefaultRequestHeaders بگذار.

curl_setopt + CURLOPT_POSTFIELDS؛ آرایه mobiles را با json_encode بفرست.

fetch یا axios؛ headers['X-API-KEY'] و body: JSON.stringify(...).

requests.post؛ headers= و json=؛ کتابخانه خودش serialize می‌کند.

http.NewRequest + json.Marshal؛ req.Header.Set("X-API-KEY", ...).

فلگ -H "X-API-KEY: ..." و -d با JSON inline.

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

دو آرایه messageTexts و mobiles باید هم‌اندازه باشند؛ index i به index i.

قبل از ارسال count($mobiles) === count($messageTexts) را چک کن.

هر دو فیلد array؛ طول‌شان با .length یکی باشد.

لیست‌ها را zip نکن مگر مطمئن باشی طول برابر است.

دو slice جدا؛ len(mobiles) == len(messageTexts) الزامی.

JSON شامل دو آرایه موازی؛ طول هر دو باید یکسان باشد.

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"]
  }'

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

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

ارسال از خطوط خدماتی با عبور از بلک‌لیست مخابراتی
متن پیامک از قبل در پنل تعریف می‌شود و نیازی به ارسال متن کامل در API نیست
پاسخ این متد اغلب plain text است؛ هدر مناسب را در درخواست ست کنید

ساخت قالب در پنل

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

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

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

پس از تأیید قالب، شناسه قالب را از لیست قالب‌ها بردارید و در API استفاده کنید.

نحوه جایگزینی متغیرها

در بدنه درخواست، آرایه‌ای از name/value ارسال می‌شود. نام هر آیتم باید دقیقاً مطابق نام متغیر در قالب باشد، بدون علامت #.

متغیر در قالب	name در API	نمونه value
#Code#	Code	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

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

نمونه کد

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

متن قالب

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

متن قالب را وارد کنید؛ متغیرهای #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)

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

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

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

با شناسه یکتای پیامک (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) کنید:

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

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

مقدمه و قراردادها

HTTP Request Header

HTTP Status Code

Unix Time

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

Authorization · احراز هویت

محیط Sandbox

ساخت کلید Sandbox

Sandbox چیست؟

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

Verify در 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)