مستندات فنی

وب‌سرویس API اکسیر پیامک

با استفاده از API اکسیر پیامک می‌تونید ارسال پیامک، تماس صوتی، کد تایید و مدیریت حساب کاربری رو مستقیم از داخل سایت، اپلیکیشن یا نرم‌افزار خودتون انجام بدید. تمام درخواست‌ها به‌صورت HTTP POST با بدنه JSON ارسال می‌شن.

معرفی و پیش‌نیازها

آدرس پایه (Base URL) تمام درخواست‌های API اکسیر پیامک به شرح زیره. تمام مسیرها نسبت به این آدرس هستن.

https://api.exirsms.ir

پاسخ تمام درخواست‌ها به فرمت JSON برگردانده می‌شه و شامل فیلد status برای وضعیت درخواست خواهد بود.

احراز هویت

برای احراز هویت باید کلید اختصاصی حساب خودتون (ApiKey) رو در هدر هر درخواست ارسال کنید. این کلید رو می‌تونید از بخش «تنظیمات وب‌سرویس» در پنل کاربری دریافت کنید.

هدرمقدارتوضیح
ApiKeyYOUR_API_KEYکلید اختصاصی حساب کاربری شما، محرمانه نگه دارید
Content-Typeapplication/jsonفرمت بدنه درخواست

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

در صورت بروز خطا، پاسخ شامل کد وضعیت و پیام توضیحی خواهد بود.

کدمعنی
200درخواست با موفقیت پردازش شد
401ApiKey نامعتبر یا ارسال نشده
402اعتبار حساب کافی نیست
422پارامترهای ارسالی نامعتبر است
429محدودیت تعداد درخواست در بازه زمانی
500خطای داخلی سرور

POST ارسال تکی و انبوه پیامک

POST /api/sendsms

ارسال پیامک به یک یا چند گیرنده با یک متن یکسان. برای ارسال تا ۵ میلیون شماره در یک درخواست مناسبه.

پارامترنوعالزامیتوضیح
recipientsarrayاجباریلیست شماره گیرندگان
senderstringاجباریشماره خط ارسال‌کننده
messagestringاجباریمتن پیامک
sendDatestringاختیاریزمان ارسال زمان‌بندی‌شده (ISO 8601)
cURL
PHP
Node.js
Python
C#
curl -X POST https://api.exirsms.ir/api/sendsms \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"recipients\": [\"09120000000\"],
    \"sender\": \"3000xxxxxx\",
    \"message\": \"سلام از اکسیر پیامک 👋\"
  }"
نمونه پاسخ
{
  "status": 200,
  "messageId": "b2f1e9a0",
  "cost": 1240,
  "recipients": 1
}

POST ارسال نظیر به نظیر

POST /api/sendpeertopeersms

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

پارامترنوعالزامیتوضیح
senderstringاجباریشماره خط ارسال‌کننده
messagesarrayاجباریآرایه‌ای از اشیاء {recipient, text}
cURL
Node.js
curl -X POST https://api.exirsms.ir/api/sendpeertopeersms \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"sender\": \"3000xxxxxx\",
    \"messages\": [
      {\"recipient\": \"09120000001\", \"text\": \"کد سفارش شما: 4471\"},
      {\"recipient\": \"09120000002\", \"text\": \"کد سفارش شما: 8823\"}
    ]
  }"

POST ارسال از طریق فرم

POST /api/SendSmsFromForm

مناسب برای اتصال مستقیم فرم‌های سایت (مثل فرم تماس یا سبد خرید) بدون نیاز به بک‌اند واسط.

پارامترنوعالزامیتوضیح
formKeystringاجباریکلید اختصاصی فرم، از پنل قابل تولید است
recipientstringاجباریشماره گیرنده (مثلاً از input فرم)
variablesobjectاختیاریمقادیر جایگزین در قالب پیام از پیش تعریف‌شده
cURL
curl -X POST https://api.exirsms.ir/api/SendSmsFromForm \
  -H "Content-Type: application/json" \
  -d "{
    \"formKey\": \"YOUR_FORM_KEY\",
    \"recipient\": \"09120000000\",
    \"variables\": {\"name\": \"علی\"}
  }"

POST ارسال با قالب تاییدشده

POST /api/sendpatternmessage

ارسال پیامک بر اساس قالب (Pattern) از پیش تعریف‌شده و تاییدشده؛ مناسب برای پیام‌های تراکنشی مثل فاکتور و کد تایید که نیاز به سرعت تحویل بالا دارن.

پارامترنوعالزامیتوضیح
patternCodestringاجباریکد قالب تاییدشده در پنل
recipientstringاجباریشماره گیرنده
valuesarrayاجباریمقادیر جایگزین متغیرهای قالب، به‌ترتیب
cURL
PHP
curl -X POST https://api.exirsms.ir/api/sendpatternmessage \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"patternCode\": \"ORDER_CONFIRM\",
    \"recipient\": \"09120000000\",
    \"values\": [\"علی\", \"128000\"]
  }"

POST ارسال پیام صوتی

POST /api/sendvoice

پخش پیام صوتی ضبط‌شده یا تبدیل‌شده از متن (Text-to-Speech) برای گیرنده از طریق تماس تلفنی.

پارامترنوعالزامیتوضیح
recipientstringاجباریشماره گیرنده تماس
textstringاختیاریمتن برای تبدیل به گفتار (در صورت نبود فایل صوتی)
audioUrlstringاختیاریآدرس فایل صوتی از پیش ضبط‌شده
cURL
curl -X POST https://api.exirsms.ir/api/sendvoice \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"recipient\": \"09120000000\",
    \"text\": \"سفارش شما ارسال شد\"
  }"

POST کد تایید تلفنی

POST /api/SendOTPVoice

اعلام کد تایید از طریق تماس صوتی؛ گزینه مناسب برای زمانی که تحویل پیامک با تاخیر مواجه می‌شه.

پارامترنوعالزامیتوضیح
recipientstringاجباریشماره گیرنده تماس
codestringاجباریکد تایید عددی برای اعلام صوتی
cURL
curl -X POST https://api.exirsms.ir/api/SendOTPVoice \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"recipient\": \"09120000000\",
    \"code\": \"482913\"
  }"

POST ارسال کد تایید

POST /api/sendcode

تولید و ارسال خودکار کد یکبار مصرف (OTP) پیامکی برای تایید شماره موبایل کاربران.

پارامترنوعالزامیتوضیح
recipientstringاجباریشماره موبایل گیرنده
codeLengthnumberاختیاریطول کد تایید، پیش‌فرض ۵ رقم
cURL
curl -X POST https://api.exirsms.ir/api/sendcode \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"recipient\": \"09120000000\" }"

POST بررسی کد تایید

POST /api/checkcode

اعتبارسنجی کدی که کاربر پس از دریافت پیامک OTP وارد کرده است.

پارامترنوعالزامیتوضیح
recipientstringاجباریشماره موبایلی که کد برایش ارسال شده
codestringاجباریکدی که کاربر وارد کرده
cURL
curl -X POST https://api.exirsms.ir/api/checkcode \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"recipient\": \"09120000000\",
    \"code\": \"48291\"
  }"

POST دریافت پیام‌های ورودی

POST /api/getreceivedmessage

دریافت لیست پیامک‌هایی که کاربران به خط اختصاصی شما ارسال کرده‌اند (مثلاً پاسخ به نظرسنجی یا کلمه کلیدی).

پارامترنوعالزامیتوضیح
senderstringاختیاریفیلتر بر اساس خط دریافت‌کننده
fromDatestringاختیاریمحدوده زمانی شروع
cURL
curl -X POST https://api.exirsms.ir/api/getreceivedmessage \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"sender\": \"3000xxxxxx\" }"

POST وضعیت تحویل پیام

POST /api/getstatus

استعلام وضعیت تحویل یک یا چند پیامک ارسال‌شده با استفاده از شناسه پیام.

پارامترنوعالزامیتوضیح
messageIdsarrayاجباریلیست شناسه پیام‌های دریافتی از پاسخ ارسال
cURL
curl -X POST https://api.exirsms.ir/api/getstatus \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"messageIds\": [\"b2f1e9a0\"] }"
نمونه پاسخ
{
  "status": 200,
  "results": [
    { "messageId": "b2f1e9a0", "state": "delivered" }
  ]
}

POST اعتبار و تعرفه حساب

POST /api/getcurrentcredit

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

cURL
curl -X POST https://api.exirsms.ir/api/getcurrentcredit \
  -H "ApiKey: YOUR_API_KEY"
نمونه پاسخ
{
  "status": 200,
  "credit": 1250000,
  "tariff": 124
}

POST لغو پیامک زمان‌بندی‌شده

POST /api/CancelUserOneMessage

لغو یک پیامک که برای ارسال در آینده زمان‌بندی شده و هنوز ارسال نشده است.

پارامترنوعالزامیتوضیح
messageIdstringاجباریشناسه پیام زمان‌بندی‌شده
cURL
curl -X POST https://api.exirsms.ir/api/CancelUserOneMessage \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"messageId\": \"b2f1e9a0\" }"