وبلاگ
شروع سریع کار با REST API نگین ارتباط (Quick Start در ۵ دقیقه)
مرحله ۱: پیشنیازها و تنظیم کلمه عبور وبسرویسلینک کپی شد!
سرویس REST API نگین ارتباط این امکان را به شما میدهد تا در کمتر از چند دقیقه سیستم، اپلیکیشن یا وبسایت خود را به سامانه پیامک متصل کرده و پیامکهای تراکنشی، کدهای تأیید ورود (OTP) و اعلانات خود را با بیشترین سرعت ارسال نمایید.
اطلاعات پایه جهت اتصال به سرویس:
- آدرس پنل کاربری: panel.3300.ir
- آدرس پایه وبسرویس (Base URL):
https://sms.3300.ir/api - نام کاربری (username): همان نام کاربری ورود شما به پنل پیامک.
- کلمه عبور وبسرویس (password): رمز عبور اختصاصی که باید از داخل پنل تنظیم شود.
مراحل تنظیم کلمه عبور وبسرویس:
- ورود به پنل پیامک در آدرس panel.3300.ir.
- کلیک روی «صفحه پروفایل» (واقع در بالای سمت چپ صفحه).
- انتخاب بخش «تنظیمات وبسرویس» و تعیین یک رمز عبور اختصاصی و امن.
مرحله ۲: ارسال اولین پیامک تکی (در ۵ دقیقه)لینک کپی شد!
برای ارسال یک پیامک متنی ساده از خط اختصاصی خود، یک درخواست 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):
- مقدار
typeرا برابر با2قرار دهید. - شماره قالب را در پارامتر
templateمشخص کنید (اندیس از0شروع میشود). - متغیرهای قالب را در فیلد
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 نیز قابل ارسال هستند.