آموزشی

راهنمای استفاده از REST API نگین ارتباط

Posted by

ارسال پیامک

از این سرویس می‌توانید برای ارسال یک پیامک به یک مخاطب (کدهای تایید OTP، اطلاع‌رسانی سفارش، اعلان‌های تراکنشی و ...) استفاده کنید.

نمونه درخواست

POST https://sms.3300.ir/api/wsSend.ashx

{
    "username": "USERNAME",
    "password": "PASSWORD",
    "mobile": "09123456789",
    "message": "متن پیامک",
    "line": "9830003300",
    "line2": "9830003301",
    "type": 0,
    "template": 0
}

پارامترهای ورودی

نام پارامتر نوع توضیحات
username string نام کاربری وب سرویس
password string رمز عبور اختصاصی وب‌سرویس (تنظیم‌شده در صفحه پروفایل پنل > تنظیمات وب‌سرویس)
mobile string شماره موبایل گیرنده (فرمت‌های 0915xxx، 915xxx، 98915xxx و +98915xxx)
message string متن پیامک (در حالت type=۰ متن پیام، در حالت type=۲ متغیرهای قالب جداشده با |)
line string شماره خط ارسال
line2 string خط جایگزین در صورت عدم امکان ارسال از خط اصلی (Fallback)
type integer نوع ارسال پیامک (۰: ارسال معمولی، ۲: ارسال قالب خدماتی)
template integer اندیس قالب پیامک در حالت استفاده از سرویس خدماتی (شروع از ۰)

نمونه پاسخ موفق

{
  "data": {
    "message_id": "66110",
    "line": "9830003300",
    "mobile": "09123456789"
  },
  "status": -1,
  "msg": "success"
}

نمونه پاسخ خطای اعتبارسنجی

{
  "data": null,
  "status": 5,
  "msg": "line is not valid"
}

پارامترهای خروجی

نام فیلد توضیحات
message_id شناسه پیام ارسال‌شده.
قاعده مهم: اگر این مقدار کمتر از ۱۰۰۰ باشد، پیامک ارسال نشده و این عدد کد خطای عدم ارسال است (مانند خطای ۵، ۸، ۹، ۱۴ و ...).
اگر بزرگتر از ۱۰۰۰ باشد، شناسه یکتای پیامک ارسالی است که برای استعلام وضعیت دلیوری در متد wsStates استفاده می‌شود.
line خط استفاده‌شده برای ارسال پیامک
mobile شماره موبایل گیرنده
status وضعیت عملیات. مقدار -1 نشان‌دهنده موفقیت درخواست است.
msg توضیح نتیجه عملیات

خطای احراز هویت

{
  "relogin": "1"
}

توضیحات

  • در صورت موفقیت، پاسخ با HTTP ۲۰۰ و مقدار status = -1 بازگردانده می‌شود.
  • خطاهای منطقی نیز با HTTP ۲۰۰ بازگردانده می‌شوند و باید مقدار status و msg بررسی شود.
  • در صورت نامعتبر بودن نام کاربری یا رمز عبور، پاسخ با HTTP ۴۰۱ بازگردانده می‌شود.
  • پارامترهای line، line2، type و template اختیاری هستند.
  • حداقل فاصله زمانی بین درخواست‌های متوالی ۵ ثانیه است (خطای ۴۰۹).
  • ارسال زمان‌بندی‌شده از طریق API پشتیبانی نمی‌شود.

سناریوی شماره یک : ارسال پیامک تکی

POST https://sms.3300.ir/api/wsSend.ashx

{
    "username": "USERNAME",
    "password": "PASSWORD",
    "mobile": "09123456789",
    "message": "متن پیامک شما",
    "line": "9830003300",
    "type": 0
}

سناریوی شماره دو : ارسال پیامک با خط خدماتی متعلق به نگین رایانه

در صورتی که type=۲ باشد، مقادیر متغیرهای قالب با کاراکتر | در message قرار می‌گیرند و در متن قالب {۰}، {۱} و ... جای‌گذاری می‌شوند.

POST https://sms.3300.ir/api/wsSend.ashx

{
    "username": "USERNAME",
    "password": "PASSWORD",
    "mobile": "09123456789",
    "message": "علیرضا|1234|1405/02/12",
    "type": 2,
    "template": 0
}

اگر متن قالب

سلام {0}
کد ورود شما {1}
تاریخ {2}

باشد، مخاطب متن

سلام علیرضا
کد ورود شما 1234
تاریخ 1405/02/12

را دریافت می‌کند.

سناریوی شماره سه : ارسال پیامک با خط اینترنتی و پشتیبانی خط دوم

در صورتی که ارسال با خط اصلی به مشکل بخورد، در صورت تعیین خط دوم، با این خط مجدداً ارسال انجام می‌شود:

POST https://sms.3300.ir/api/wsSend.ashx

{
    "username": "USERNAME",
    "password": "PASSWORD",
    "mobile": "09123456789",
    "message": "متن پیامک",
    "line": "9830003300",
    "line2": "9830003301",
    "type": 0
}

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

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

POST https://sms.3300.ir/api/wsSend.ashx

{
    "username": "USERNAME",
    "password": "PASSWORD",
    "mobile": "09123456789",
    "message": "رضا|45890",
    "line": "9830003300",
    "line2": "9830003301",
    "type": 2,
    "template": 0
}
template: اندیس الگوی خدماتی ثبت‌شده در سامانه (شروع از ۰) است.
در صورتی که بیش از یک متن برای ارسال با خط خدماتی نگین رایانه وجود دارد، شماره قالب را ارسال کنید.

ارسال پیامک گروهی (Batch)

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

نمونه درخواست

POST https://sms.3300.ir/api/wsSendBatch.ashx

{
    "username": "USERNAME",
    "password": "PASSWORD",
    "line": "9830003300",
    "messages": [
        "پیام اول",
        "پیام دوم"
    ],
    "mobiles": [
        "09123456789",
        "09123456789"
    ],
    "tempCheckIds": [
        1001,
        1002
    ]
}

پارامترهای ورودی

نام پارامتر نوع توضیحات
username string نام کاربری وب سرویس
password string رمز عبور وب سرویس
line string شماره خط ارسال پیامک (در هر درخواست Batch فقط ارسال از یک خط ممکن است)
messages array[string] لیست پیام‌های ارسالی (۱ پیام برای همه یا متناظر با شماره‌ها)
mobiles array[string] لیست شماره موبایل‌ها (حداکثر ۵۰ شماره در هر فراخوانی)
tempCheckIds array[long] شناسه‌های موقت ۶۴ بیتی (Long) برای پیگیری وضعیت ارسال هر پیام

نمونه پاسخ موفق

{
    "data": {
        "msgIds": [
            66110,
            66111
        ]
    },
    "status": -1,
    "msg": "success"
}

پارامترهای خروجی

نام فیلد توضیحات
msgIds آرایه شناسه‌های پیام‌های ارسالی به ترتیب درخواست.
قاعده مهم: هر عضو آرایه که کمتر از ۱۰۰۰ باشد پیامک برای آن مخاطب خاص ارسال نشده و عدد نشان‌دهنده کد خطا است؛
هر عضو بزرگتر از ۱۰۰۰ شناسه یکتای پیامک ثبت‌شده‌ای است که برای استعلام وضعیت دلیوری قابل استفاده است.

توضیحات

  • حداکثر تعداد شماره‌ها در هر بار فراخوانی ۵۰ عدد است.
  • مقادیر messages و mobiles باید هم‌اندازه باشند یا پیام‌ها به صورت یکسان برای همه شماره‌ها ارسال شوند.
  • مقادیر tempCheckIds و mobiles باید هم‌اندازه باشند.
  • در صورت موفقیت، مقدار status = -1 (یا منفی) بازگردانده می‌شود.
  • در متد ارسال گروهی، پارامتر line2 و ارسال چندخطی پشتیبانی نمی‌شود.

دریافت پیام‌های ورودی (Inbox)

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

نکات عملکرد سرویس

  • فقط پیام‌های ۲۴ ساعت اخیر قابل دریافت هستند.
  • با هر بار فراخوانی این آدرس، تا سقف ۱۰۰ پیام (به ترتیب قدیمی‌ترین) از سرور دریافت می‌شود.
  • پس از دریافت پیام‌ها، آن‌ها به صورت خودکار در وضعیت خوانده‌شده ثبت می‌شوند و در درخواست‌های بعدی برگردانده نمی‌شوند.
  • در صورت عدم وجود پیام جدید، آرایه خالی بازگردانده می‌شود.

نمونه درخواست

POST https://sms.3300.ir/api/wsReceive.ashx

{
    "username": "USERNAME",
    "password": "PASSWORD"
}

پارامترهای ورودی

نام پارامتر نوع توضیحات
username string نام کاربری وب سرویس
password string رمز عبور وب سرویس

نمونه پاسخ

{
    "data": [
        {
            "Id": 123456789,
            "Date": "2026-06-01 12:41",
            "Message": "Hello",
            "Mobile": "09123456789",
            "Line": "9830003300"
        }
    ],
    "status": -1,
    "msg": "success"
}

پارامترهای خروجی

نام فیلد توضیحات
Id شناسه یکتای پیام دریافتی
Date تاریخ و زمان دریافت پیام
Message متن پیام دریافتی
Mobile شماره موبایل فرستنده
Line شماره خط دریافت‌کننده پیام

خطای احراز هویت

{
  "relogin": "1"
}

دریافت وضعیت پیامک‌ها

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

نمونه درخواست

POST https://sms.3300.ir/api/wsStates.ashx

{
    "username": "USERNAME",
    "password": "PASSWORD",
    "message_ids": "66110,66111,66112"
}

پارامترهای ورودی

نام پارامتر نوع توضیحات
username string نام کاربری وب سرویس
password string رمز عبور وب سرویس
message_ids string شناسه پیام‌ها به صورت رشته جداشده با کاما یا آرایه (حداکثر ۵۰ شناسه تا ۷ روز گذشته)

نمونه پاسخ موفق

{
    "data": {
        "msgIds": [
            "66110",
            "66111",
            "66112"
        ],
        "states": [
            1,
            1,
            8
        ]
    },
    "status": -1,
    "msg": "success"
}

پارامترهای خروجی

نام فیلد توضیحات
msgIds لیست شناسه پیام‌ها (همان ترتیب ورودی)
states لیست وضعیت هر پیام متناظر با msgIds

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

کد توضیحات
-1 ارسال نشده به اپراتور
0 نامشخص
1 دریافت توسط گوشی
2 عدم دریافت توسط گوشی
8 دریافت شده توسط اپراتور
16 عدم دریافت توسط اپراتور

خطای احراز هویت

{
  "relogin": "1"
}

دریافت باقی‌مانده اعتبار

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

نمونه درخواست

POST https://sms.3300.ir/api/wsCredit.ashx

{
    "username": "USERNAME",
    "password": "PASSWORD"
}

پارامترهای ورودی

نام پارامتر نوع توضیحات
username string نام کاربری وب سرویس
password string رمز عبور وب سرویس

نمونه پاسخ

{
    "data": {
        "credit": 36408,
        "send": 96354,
        "receive": 0,
        "charge": 132762
    },
    "status": -1,
    "msg": "success"
}

پارامترهای خروجی

نام فیلد توضیحات
credit موجودی اعتبار (ریال)
send مجموع هزینه ارسال پیامک‌ها (ریال)
receive مجموع هزینه دریافت پیامک‌ها (ریال)
charge مجموع شارژهای انجام‌شده (ریال)

خطای احراز هویت

{
  "relogin": "1"
}

بررسی وضعیت سرویس (Ping)

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

نمونه درخواست

GET https://sms.3300.ir/api/ping.ashx

نمونه پاسخ

pong

توضیحات

  • این سرویس نیازی به احراز هویت ندارد.
  • در صورت در دسترس بودن سرویس، مقدار pong بازگردانده می‌شود.
  • این endpoint فقط برای بررسی وضعیت کلی سرور استفاده می‌شود و داده‌ای بازنمی‌گرداند.

جدول کدهای خطای عمومی وب‌سرویس و REST API

در صورتی که عملیاتی با خطا مواجه شود، کد خطای مربوطه در فیلد status بازگردانده خواهد شد:

کد خطا شرح خطا توضیحات و راهکار رفع خطا
0 خطای غیرمنتظره سیستمی در اجرای سرویس خطای سیستمی رخ داده است؛ پارامترهای ارسالی را بازبینی کنید.
1 اطلاعات ورود خالی است نام کاربری یا کلمه عبور وب‌سرویس ارسال نشده است.
2 عدم کفایت موجودی اعتبار ریالی حساب جهت ارسال پیامک کافی نیست.
3 سقف ارسال روزانه تعداد ارسال‌های روزانه از سقف مجاز تعریف‌شده فراتر رفته است.
4 محدودیت نرخ ارسال در ثانیه تعداد درخواست‌ها در ثانیه بیش از حد مجاز است.
5 خط فرستنده نامعتبر شماره خط فرستنده نامعتبر است یا به حساب کاربری شما تعلق ندارد.
6 عدم امکان مسیریابی ارسال به رنج شماره‌های مقصد در حال حاضر مقدور نیست.
7 متن فیلترشده یا غیرمجاز متن پیامک حاوی کلمات غیرمجاز، فیشینگ یا مسدودشده توسط قوانین است.
8 شماره گیرنده نامعتبر فرمت شماره موبایل گیرنده اشتباه یا نامعتبر است.
9 لیست سیاه مخابرات (Blacklist) شماره گیرنده در لیست سیاه مخابراتی است (با سرشماره‌های غیرخدماتی امکان ارسال نیست).
10 حساب کاربری غیرفعال حساب کاربری غیرفعال شده یا دسترسی وب‌سرویس مسدود است.
12 مدارک احراز هویت ناقص مدارک و اطلاعات هویتی کاربر در پنل تکمیل نشده است.
14 اعتبار ریالی ناکافی موجودی ریالی برای انجام عملیات درخواستی کافی نمی‌باشد.
18 نام کاربری یا رمز اشتباه نام کاربری یا کلمه عبور وب‌سرویس نادرست است.
20 شناسه پیام نامعتبر شناسه پیامک ارسالی در سیستم یافت نشد.
100 خطای طول آرایه Encoding طول آرایه انکودینگ ارسالی اشتباه است.
101 خطای طول آرایه Messages طول آرایه متن پیامک‌ها با تعداد گیرندگان همخوانی ندارد.
103 خطای طول آرایه Mobiles طول آرایه شماره‌های گیرنده نامعتبر است.
107 بیش از سقف ۵۰ عدد تعداد گیرندگان در درخواست بیش از حد مجاز (حداکثر ۵۰ شماره) است.

قوانین محاسبه کاراکترها و بخش‌های پیامک (Multipart SMS)

محاسبه هزینه و تعداد بخش‌های ارسالی بر اساس استانداردهای زیر صورت می‌پذیرد:

  • پیامک فارسی (یونیکود):
    • پیامک تک‌بخشی: تا سقف ۷۰ کاراکتر معادل ۱ پارت محاسبه می‌شود.
    • پیامک چندبخشی (۲ پارت به بالا): تمام بخش‌ها (شامل بخش اول) به ازای هر ۶۴ کاراکتر یک پارت محاسبه می‌شوند.
  • پیامک انگلیسی (لاتین / GSM ۷-bit):
    • پیامک تک‌بخشی: تا سقف ۱۶۰ کاراکتر معادل ۱ پارت محاسبه می‌شود.
    • پیامک چندبخشی: به ازای هر ۱۵۳ کاراکتر یک پارت محاسبه می‌شوند.
  • ایموجی‌ها و شکلک‌ها: هر شکلک/ایموجی معادل ۲ کاراکتر یونیکود در طول پیامک شمارش می‌شود.

احراز هویت و تنظیم کلمه عبور وب‌سرویس

برای برقراری ارتباط با وب‌سرویس و REST API نگین ارتباط، رعایت نکات زیر الزامی است:

  • کلمه عبور وب‌سرویس مستقل از رمز عبور ورود به پنل کاربری است.
  • برای ایجاد یا تغییر رمز وب‌سرویس، پس از ورود به سامانه پیامک (panel.3300.ir)، از «صفحه پروفایل» (واقع در بالای سمت چپ صفحه) به بخش «تنظیمات وب‌سرویس» مراجعه نموده و کلمه عبور اختصاصی خود را تعیین یا ویرایش نمایید.
  • نام کاربری وب‌سرویس همان نام کاربری ورود به پنل پیامک شما می‌باشد.
Newer
نحوه محاسبه و کسر اعتبار نمایندگان فروش
Back to list
Older راهنمای استفاده از WebService نگین ارتباط