دسته‌بندی نشده

شروع سریع کار با REST API نگین ارتباط (Quick Start در ۵ دقیقه)

مرحله ۱: پیش‌نیازها و تنظیم کلمه عبور وب‌سرویسلینک کپی شد!

سرویس REST API نگین ارتباط این امکان را به شما می‌دهد تا در کمتر از چند دقیقه سیستم، اپلیکیشن یا وب‌سایت خود را به سامانه پیامک متصل کرده و پیامک‌های تراکنشی، کدهای تأیید ورود (OTP) و اعلانات خود را با بیشترین سرعت ارسال نمایید.

اطلاعات پایه جهت اتصال به سرویس:

  • آدرس پنل کاربری: panel.3300.ir
  • آدرس پایه وب‌سرویس (Base URL): https://sms.3300.ir/api
  • نام کاربری (username): همان نام کاربری ورود شما به پنل پیامک.
  • کلمه عبور وب‌سرویس (password): رمز عبور اختصاصی که باید از داخل پنل تنظیم شود.

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

  1. ورود به پنل پیامک در آدرس panel.3300.ir.
  2. کلیک روی «صفحه پروفایل» (واقع در بالای سمت چپ صفحه).
  3. انتخاب بخش «تنظیمات وب‌سرویس» و تعیین یک رمز عبور اختصاصی و امن.

مرحله ۲: ارسال اولین پیامک تکی (در ۵ دقیقه)لینک کپی شد!

برای ارسال یک پیامک متنی ساده از خط اختصاصی خود، یک درخواست POST با فرمت JSON به آدرس https://sms.3300.ir/api/wsSend.ashx ارسال کنید. زبان برنامه‌نویسی مورد نظر خود را از تب‌های زیر انتخاب نمایید:

# 1. cURL Terminal Request
curl -X POST "https://sms.3300.ir/api/wsSend.ashx" \
     -H "Content-Type: application/json" \
     -d '{
       "username": "YOUR_USERNAME",
       "password": "YOUR_WEBSERVICE_PASSWORD",
       "mobile": "09123456789",
       "message": "سلام! ارسال پیامک تست از نگین ارتباط",
       "line": "9830003300",
       "type": 0
     }'
import requests

url = "https://sms.3300.ir/api/wsSend.ashx"
payload = {
    "username": "YOUR_USERNAME",
    "password": "YOUR_WEBSERVICE_PASSWORD",
    "mobile": "09123456789",
    "message": "سلام! ارسال پیامک تست با پایتون",
    "line": "9830003300",
    "type": 0
}

response = requests.post(url, json=payload)
data = response.json()

if data.get("status") == -1:
    print(f"پیامک با موفقیت ارسال شد. شناسه: {data['data']['message_id']}")
else:
    print(f"خطا در ارسال: {data.get('msg')} (کد خطا: {data.get('status')})")
<?php
$url = "https://sms.3300.ir/api/wsSend.ashx";
$data = [
    "username" => "YOUR_USERNAME",
    "password" => "YOUR_WEBSERVICE_PASSWORD",
    "mobile"   => "09123456789",
    "message"  => "سلام! ارسال پیامک تست با PHP",
    "line"     => "9830003300",
    "type"     => 0
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

$response = json_decode($result, true);
if ($response['status'] === -1) {
    echo "ارسال موفق! شناسه: " . $response['data']['message_id'];
} else {
    echo "خطا: " . $response['msg'];
}
?>
const response = await fetch('https://sms.3300.ir/api/wsSend.ashx', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'YOUR_USERNAME',
    password: 'YOUR_WEBSERVICE_PASSWORD',
    mobile: '09123456789',
    message: 'سلام! ارسال پیامک تست با جاوااسکریپت',
    line: '9830003300',
    type: 0
  })
});

const result = await response.json();
console.log(result);
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

var client = new HttpClient();
var payload = new {
    username = "YOUR_USERNAME",
    password = "YOUR_WEBSERVICE_PASSWORD",
    mobile = "09123456789",
    message = "سلام! ارسال پیامک با C# .NET",
    line = "9830003300",
    type = 0
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://sms.3300.ir/api/wsSend.ashx", content);
var responseBody = await response.Content.ReadAsStringAsync();

Console.WriteLine(responseBody);

توضیحات پاسخ وب‌سرویس: در پاسخ دریافتی، فیلد status: -1 به معنای موفقیت است و message_id شناسه یکتای پیامک ارسالی است که برای استعلام وضعیت دلیوری استفاده می‌شود.

مرحله ۳: ارسال کدهای تایید OTP و پیامک خدماتی (عبور از بلک‌لیست)لینک کپی شد!

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

نحوه ارسال پیامک با قالب خدماتی (Pattern / Template):

  1. مقدار type را برابر با 2 قرار دهید.
  2. شماره قالب را در پارامتر template مشخص کنید (اندیس از 0 شروع می‌شود).
  3. متغیرهای قالب را در فیلد message با کاراکتر | (پایپ) از یکدیگر جدا نمایید.
curl -X POST "https://sms.3300.ir/api/wsSend.ashx" \
     -H "Content-Type: application/json" \
     -d '{
       "username": "YOUR_USERNAME",
       "password": "YOUR_WEBSERVICE_PASSWORD",
       "mobile": "09123456789",
       "message": "علیرضا|12345|1405/02/12",
       "type": 2,
       "template": 0
     }'
import requests

url = "https://sms.3300.ir/api/wsSend.ashx"
payload = {
    "username": "YOUR_USERNAME",
    "password": "YOUR_WEBSERVICE_PASSWORD",
    "mobile": "09123456789",
    "message": "علیرضا|12345|1405/02/12",
    "type": 2,
    "template": 0
}

response = requests.post(url, json=payload)
data = response.json()
print("نتیجه ارسال OTP:", data)
<?php
$url = "https://sms.3300.ir/api/wsSend.ashx";
$data = [
    "username" => "YOUR_USERNAME",
    "password" => "YOUR_WEBSERVICE_PASSWORD",
    "mobile"   => "09123456789",
    "message"  => "علیرضا|12345|1405/02/12",
    "type"     => 2,
    "template" => 0
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

$response = json_decode($result, true);
echo "شناسه OTP: " . $response['data']['message_id'];
?>
const response = await fetch('https://sms.3300.ir/api/wsSend.ashx', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'YOUR_USERNAME',
    password: 'YOUR_WEBSERVICE_PASSWORD',
    mobile: '09123456789',
    message: 'علیرضا|12345|1405/02/12',
    type: 2,
    template: 0
  })
});

const result = await response.json();
console.log('OTP Result:', result);
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

var client = new HttpClient();
var payload = new {
    username = "YOUR_USERNAME",
    password = "YOUR_WEBSERVICE_PASSWORD",
    mobile = "09123456789",
    message = "علیرضا|12345|1405/02/12",
    type = 2,
    template = 0
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://sms.3300.ir/api/wsSend.ashx", content);
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine("OTP Response: " + result);

توضیح عملکرد: اگر متن قالب ثبت‌شده شما سلام {0} کد ورود شما {1} است (تاریخ: {2}) باشد، متغیرها به ترتیب جای‌گذاری شده و پیامک نهایی زیر با خط خدماتی برای کاربر ارسال می‌شود:

«سلام علیرضا کد ورود شما ۱۲۳۴۵ است (تاریخ: ۱۴۰۵/۰۲/۱۲)»

مرحله ۴: پیگیری وضعیت دلیوری و وضعیت ارسال پیامکلینک کپی شد!

پس از ارسال پیامک، می‌توانید وضعیت تحویل آن به گوشی مخاطب یا اپراتور را با ارسال شناسه پیامک (message_id) به سرویس wsStates.ashx پیگیری نمایید:

curl -X POST "https://sms.3300.ir/api/wsStates.ashx" \
     -H "Content-Type: application/json" \
     -d '{
       "username": "YOUR_USERNAME",
       "password": "YOUR_WEBSERVICE_PASSWORD",
       "message_ids": "66110,66111"
     }'
import requests

url = "https://sms.3300.ir/api/wsStates.ashx"
payload = {
    "username": "YOUR_USERNAME",
    "password": "YOUR_WEBSERVICE_PASSWORD",
    "message_ids": "66110,66111"
}

response = requests.post(url, json=payload)
data = response.json()
print("وضعیت دلیوری:", data)
<?php
$url = "https://sms.3300.ir/api/wsStates.ashx";
$data = [
    "username"    => "YOUR_USERNAME",
    "password"    => "YOUR_WEBSERVICE_PASSWORD",
    "message_ids" => "66110,66111"
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

$response = json_decode($result, true);
print_r($response);
?>
const response = await fetch('https://sms.3300.ir/api/wsStates.ashx', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'YOUR_USERNAME',
    password: 'YOUR_WEBSERVICE_PASSWORD',
    message_ids: '66110,66111'
  })
});

const result = await response.json();
console.log('وضعیت دلیوری:', result);
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

var client = new HttpClient();
var payload = new {
    username = "YOUR_USERNAME",
    password = "YOUR_WEBSERVICE_PASSWORD",
    message_ids = "66110,66111"
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://sms.3300.ir/api/wsStates.ashx", content);
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine("Delivery States: " + result);

جدول کدهای وضعیت پیامک (Delivery States):

کد وضعیت عنوان وضعیت توضیحات
1 رسیده به گوشی (Delivered) پیامک با موفقیت توسط دستگاه کاربر دریافت شده است.
2 نرسیده به گوشی (Undelivered) گوشی خاموش، خارج از دسترس یا حافظه آن پر بوده است.
8 تحویل اپراتور شده پیامک به مرکز پیام اپراتور تحویل داده شده و در انتظار ارسال است.
16 عدم دریافت توسط اپراتور ارسال توسط اپراتور رد شده است.
-1 ارسال نشده به اپراتور پیامک در صف ارسال قرار دارد.

مرحله ۵: نکات کلیدی و الزامات فنی توسعه‌دهندگانلینک کپی شد!

برای پیاده‌سازی بهینه و پایدار وب‌سرویس، رعایت نکات زیر الزامی است:

  • قاعده بررسی شناسه‌ها (Message ID Rule):
    • اگر مقدار message_id < 1000 باشد، ارسال انجام نشده و این عدد کد خطای عدم ارسال است (مانند خطای 5 خط نامعتبر، 8 شماره نامعتبر، 9 بلک‌لیست، 14 اعتبار ناکافی).
    • اگر مقدار message_id >= 1000 باشد، پیامک با موفقیت ثبت شده و این عدد شناسه یکتای پیگیری دلیوری است.
  • محدودیت فاصله زمانی (Rate Limit): حداقل فاصله زمانی بین درخواست‌های متوالی ۵ ثانیه است. در صورت فراخوانی سریع‌تر، خطای 409 برگردانده می‌شود.
  • فرمت‌های استاندارد شماره موبایل: وب‌سرویس تمام فرمت‌های رایج شامل 09151234567، 9151234567، 989151234567 و +989151234567 را به صورت خودکار نرمال‌سازی می‌کند.
  • پشتیبانی از انواع فرمت‌های ورودی: پارامترهای درخواست علاوه بر application/json، از طریق x-www-form-urlencoded، multipart/form-data و حتی Query String نیز قابل ارسال هستند.
مستندات تکمیلی: جهت مشاهده توضیحات متدهای ارسال گروهی، اینباکس پیام‌های دریافتی، وب‌سرویس SOAP و لیست کامل کدهای خطا، به صفحه مستندات جامع REST API و مستندات WebService SOAP مراجعه نمایید.