آموزشی

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

ارسال توسط

ارسال پیامک

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

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

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

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

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

نام پارامتر نوع توضیحات
username string نام کاربری وب سرویس
password string رمز عبور وب سرویس
mobile string شماره موبایل گیرنده
message string متن پیامک
line string شماره خط ارسال
line2 string خط جایگزین در صورت عدم امکان ارسال از خط اصلی
type integer نوع ارسال پیامک
template integer شماره قالب پیامک (در حالت استفاده از سرویس خدماتی)

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

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

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

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

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

نام فیلد توضیحات
message_id شناسه پیام ارسال‌شده. در برخی شرایط ممکن است مقدار بازگشتی یک کد خطای اپراتور باشد.
line خط استفاده‌شده برای ارسال پیامک
mobile شماره موبایل گیرنده
status وضعیت عملیات. مقدار -۱ نشان‌دهنده موفقیت درخواست است.
msg توضیح نتیجه عملیات

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

{
  "relogin": "1"
}

توضیحات

  • در صورت موفقیت، پاسخ با HTTP 200 و مقدار status = -1 بازگردانده می‌شود.
  • خطاهای منطقی نیز با HTTP 200 بازگردانده می‌شوند و باید مقدار status و msg بررسی شود.
  • در صورت نامعتبر بودن نام کاربری یا رمز عبور، پاسخ با HTTP 401 بازگردانده می‌شود.
  • پارامترهای line، line2، type و template اختیاری هستند.

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

url= https://sms.3300.ir/api/wsSend.ashx 

POST parameters 
    username:USERNAME
    password:PASSWORD 
    mobile:MOBILE 
    message:MESSAGE_TEXT 
    line:SMS_LINE_NUMBER

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

url= https://sms.3300.ir/api/wsSend.ashx

POST parameters
    username:USERNAME
    password:PASSWORD
    mobile:MOBILE
    message:MESSAGE_TEXT
    type:2

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

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

url= https://sms.3300.ir/api/wsSend.ashx

POST parameters
    username:USERNAME
    password:PASSWORD
    mobile:MOBILE
    message:MESSAGE_TEXT
    line:SMS_LINE_NUMBER
    line2:SMS_LINE_NUMBER2

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

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

url= https://sms.3300.ir/api/wsSend.ashx

POST parameters
    username:USERNAME
    password:PASSWORD
    mobile:MOBILE
    message:MESSAGE_TEXT
    line:SMS_LINE_NUMBER
    type:2
    template:0
template: در صورتی که بیش از یک متن برای ارسال با خط خدماتی نگین رایانه وجود دارد، شماره تمپلیت را ارسال کنید.

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

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

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

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

{
    "username": "USERNAME",
    "password": "PASSWORD",
    "line": "9830003300",
    "messages": [
        "پیام اول",
        "پیام دوم"
    ],
    "mobiles": [
        "۰۹۱۲۳۴۵۶۷۸۹",
        "۰۹۱۲۳۴۵۶۷۸۹"
    ],
    "tempCheckIds": [
        ۱۰۰۱,
        ۱۰۰۲
    ]
}

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

نام پارامتر نوع توضیحات
username string نام کاربری وب سرویس
password string رمز عبور وب سرویس
line string شماره خط ارسال پیامک
messages array[string] لیست پیام‌های ارسالی
mobiles array[string] لیست شماره موبایل‌ها
tempCheckIds array[integer] شناسه‌های موقت برای پیگیری وضعیت ارسال هر پیام

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

{
    "data": {
        "msgIds": [
            ۶۶۱۱۰,
            ۶۶۱۱۱
        ]
    },
    "status": -2,
    "msg": "success"
}

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

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

توضیحات

  • مقادیر messages و mobiles باید هم‌اندازه باشند یا پیام‌ها به صورت یکسان برای همه شماره‌ها ارسال شوند.
  • در صورت موفقیت، مقدار status = -2 بازگردانده می‌شود.
  • برای پیگیری وضعیت پیام‌ها می‌توانید از متد دریافت وضعیت پیامک‌ها استفاده کنید.

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

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

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

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

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

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": "989123456789",
            "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": [
            "۶۶۱۱۰",
            "۶۶۱۱۱",
            "۶۶۱۱۲"
        ],
        "states": [
            ۱,
            ۱,
            ۸
        ]
    },
    "status": -1,
    "msg": "success"
}

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

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

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

کد توضیحات
-۱ ارسال نشده به اپراتور
۰ نامشخص
۱ دریافت توسط گوشی
۲ عدم دریافت توسط گوشی
۸ دریافت شده توسط اپراتور
۱۶ عدم دریافت توسط اپراتور

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

{
    "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 فقط برای بررسی وضعیت کلی سرور استفاده می‌شود و داده‌ای بازنمی‌گرداند.
بازگشت به لیست
قدیمی تر راهنمای استفاده از WebService نگین ارتباط