وبسرویس API اکسیر پیامک
با استفاده از API اکسیر پیامک میتونید ارسال پیامک، تماس صوتی، کد تایید و مدیریت حساب کاربری رو مستقیم از داخل سایت، اپلیکیشن یا نرمافزار خودتون انجام بدید. تمام درخواستها بهصورت HTTP POST با بدنه JSON ارسال میشن.
معرفی و پیشنیازها
آدرس پایه (Base URL) تمام درخواستهای API اکسیر پیامک به شرح زیره. تمام مسیرها نسبت به این آدرس هستن.
پاسخ تمام درخواستها به فرمت JSON برگردانده میشه و شامل فیلد status برای وضعیت درخواست خواهد بود.
احراز هویت
برای احراز هویت باید کلید اختصاصی حساب خودتون (ApiKey) رو در هدر هر درخواست ارسال کنید. این کلید رو میتونید از بخش «تنظیمات وبسرویس» در پنل کاربری دریافت کنید.
| هدر | مقدار | توضیح |
|---|---|---|
ApiKey | YOUR_API_KEY | کلید اختصاصی حساب کاربری شما، محرمانه نگه دارید |
Content-Type | application/json | فرمت بدنه درخواست |
خطاها و کدهای وضعیت
در صورت بروز خطا، پاسخ شامل کد وضعیت و پیام توضیحی خواهد بود.
| کد | معنی |
|---|---|
200 | درخواست با موفقیت پردازش شد |
401 | ApiKey نامعتبر یا ارسال نشده |
402 | اعتبار حساب کافی نیست |
422 | پارامترهای ارسالی نامعتبر است |
429 | محدودیت تعداد درخواست در بازه زمانی |
500 | خطای داخلی سرور |
POST ارسال تکی و انبوه پیامک
ارسال پیامک به یک یا چند گیرنده با یک متن یکسان. برای ارسال تا ۵ میلیون شماره در یک درخواست مناسبه.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
recipients | array | اجباری | لیست شماره گیرندگان |
sender | string | اجباری | شماره خط ارسالکننده |
message | string | اجباری | متن پیامک |
sendDate | string | اختیاری | زمان ارسال زمانبندیشده (ISO 8601) |
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 ارسال نظیر به نظیر
ارسال پیامهای متفاوت به چند گیرنده در یک درخواست؛ مناسب برای ارسال کد سفارش، یادآوری قسط یا پیامهای شخصیسازیشده.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
sender | string | اجباری | شماره خط ارسالکننده |
messages | array | اجباری | آرایهای از اشیاء {recipient, text} |
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 ارسال از طریق فرم
مناسب برای اتصال مستقیم فرمهای سایت (مثل فرم تماس یا سبد خرید) بدون نیاز به بکاند واسط.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
formKey | string | اجباری | کلید اختصاصی فرم، از پنل قابل تولید است |
recipient | string | اجباری | شماره گیرنده (مثلاً از input فرم) |
variables | object | اختیاری | مقادیر جایگزین در قالب پیام از پیش تعریفشده |
curl -X POST https://api.exirsms.ir/api/SendSmsFromForm \
-H "Content-Type: application/json" \
-d "{
\"formKey\": \"YOUR_FORM_KEY\",
\"recipient\": \"09120000000\",
\"variables\": {\"name\": \"علی\"}
}"
POST ارسال با قالب تاییدشده
ارسال پیامک بر اساس قالب (Pattern) از پیش تعریفشده و تاییدشده؛ مناسب برای پیامهای تراکنشی مثل فاکتور و کد تایید که نیاز به سرعت تحویل بالا دارن.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
patternCode | string | اجباری | کد قالب تاییدشده در پنل |
recipient | string | اجباری | شماره گیرنده |
values | array | اجباری | مقادیر جایگزین متغیرهای قالب، بهترتیب |
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 ارسال پیام صوتی
پخش پیام صوتی ضبطشده یا تبدیلشده از متن (Text-to-Speech) برای گیرنده از طریق تماس تلفنی.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
recipient | string | اجباری | شماره گیرنده تماس |
text | string | اختیاری | متن برای تبدیل به گفتار (در صورت نبود فایل صوتی) |
audioUrl | string | اختیاری | آدرس فایل صوتی از پیش ضبطشده |
curl -X POST https://api.exirsms.ir/api/sendvoice \
-H "ApiKey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"recipient\": \"09120000000\",
\"text\": \"سفارش شما ارسال شد\"
}"
POST کد تایید تلفنی
اعلام کد تایید از طریق تماس صوتی؛ گزینه مناسب برای زمانی که تحویل پیامک با تاخیر مواجه میشه.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
recipient | string | اجباری | شماره گیرنده تماس |
code | string | اجباری | کد تایید عددی برای اعلام صوتی |
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 ارسال کد تایید
تولید و ارسال خودکار کد یکبار مصرف (OTP) پیامکی برای تایید شماره موبایل کاربران.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
recipient | string | اجباری | شماره موبایل گیرنده |
codeLength | number | اختیاری | طول کد تایید، پیشفرض ۵ رقم |
curl -X POST https://api.exirsms.ir/api/sendcode \
-H "ApiKey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d "{ \"recipient\": \"09120000000\" }"
POST بررسی کد تایید
اعتبارسنجی کدی که کاربر پس از دریافت پیامک OTP وارد کرده است.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
recipient | string | اجباری | شماره موبایلی که کد برایش ارسال شده |
code | string | اجباری | کدی که کاربر وارد کرده |
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 دریافت پیامهای ورودی
دریافت لیست پیامکهایی که کاربران به خط اختصاصی شما ارسال کردهاند (مثلاً پاسخ به نظرسنجی یا کلمه کلیدی).
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
sender | string | اختیاری | فیلتر بر اساس خط دریافتکننده |
fromDate | string | اختیاری | محدوده زمانی شروع |
curl -X POST https://api.exirsms.ir/api/getreceivedmessage \
-H "ApiKey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d "{ \"sender\": \"3000xxxxxx\" }"
POST وضعیت تحویل پیام
استعلام وضعیت تحویل یک یا چند پیامک ارسالشده با استفاده از شناسه پیام.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
messageIds | array | اجباری | لیست شناسه پیامهای دریافتی از پاسخ ارسال |
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 اعتبار و تعرفه حساب
دریافت میزان اعتبار باقیمانده و تعرفه هر پیامک برای حساب کاربری فعلی.
curl -X POST https://api.exirsms.ir/api/getcurrentcredit \ -H "ApiKey: YOUR_API_KEY"
{
"status": 200,
"credit": 1250000,
"tariff": 124
}
POST لغو پیامک زمانبندیشده
لغو یک پیامک که برای ارسال در آینده زمانبندی شده و هنوز ارسال نشده است.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
messageId | string | اجباری | شناسه پیام زمانبندیشده |
curl -X POST https://api.exirsms.ir/api/CancelUserOneMessage \
-H "ApiKey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d "{ \"messageId\": \"b2f1e9a0\" }"