اتصال سایت و نرم‌افزار به وب‌سرویس پیامک؛ نمونه‌کد PHP، پایتون، C# و cURL

«آیا سایت من با PHP نوشته شده، می‌شود به وب‌سرویس پیامک وصلش کرد؟» جواب کوتاه: هر زبانی که بتواند یک درخواست HTTP بفرستد، می‌تواند پیامک بفرستد؛ PHP و لاراول، پایتون و جنگو، C# و دات‌نت، جاوا، Node.js، Go و حتی یک اسکریپت ساده در خط فرمان. در این مقاله با نمونه‌های واقعی از وب‌سرویس درگاه پیامک (SMSGate) نشان می‌دهیم این اتصال چه شکلی دارد.

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

ساختار یک درخواست ارسال

• نشانی: POST https://smsgate.webservice.ir/v1/sms/send
• احراز هویت: سرآیند Authorization: Bearer کلید-شما
• بدنه (JSON): senderNumber (شمارهٔ خط، بدون پیشوند ۹۸)، recipients (فهرست گیرندگان) و body (متن)

شماره‌های گیرنده در نمونه‌های مستندات ده‌رقمی و بدون صفر ابتدا هستند، مثل 9121234567. همیشه ارقام را لاتین بفرستید.

cURL: سریع‌ترین راه برای امتحان

curl -X POST https://smsgate.webservice.ir/v1/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"senderNumber":"50003123","recipients":["9121234567"],"body":"سلام؛ این یک پیام آزمایشی است."}'

PHP

<?php
$payload = [
    'senderNumber' => '50003123',
    'recipients'   => ['9121234567'],
    'body'         => 'سفارش شما ثبت شد.',
];
$ch = curl_init('https://smsgate.webservice.ir/v1/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('SMS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($res['code'] ?? 0) === 100) {
    $batchId = $res['data']['batchId'];   // برای پیگیری ذخیره کنید
} else {
    error_log('SMS error ' . ($res['code'] ?? '?') . ': ' . ($res['message'] ?? ''));
}

پایتون

import os
import requests

resp = requests.post(
    "https://smsgate.webservice.ir/v1/sms/send",
    headers={"Authorization": f"Bearer {os.environ['SMS_API_KEY']}"},
    json={
        "senderNumber": "50003123",
        "recipients": ["9121234567"],
        "body": "سفارش شما ثبت شد.",
    },
    timeout=15,
)
res = resp.json()
if res.get("code") == 100:
    batch_id = res["data"]["batchId"]
else:
    print("خطا:", res.get("code"), res.get("message"))

C# (دات‌نت)

using System.Net.Http.Headers;
using System.Net.Http.Json;

var http = new HttpClient { Timeout = TimeSpan.FromSeconds(15) };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("SMS_API_KEY"));

var resp = await http.PostAsJsonAsync("https://smsgate.webservice.ir/v1/sms/send", new {
    senderNumber = "50003123",
    recipients = new[] { "9121234567" },
    body = "سفارش شما ثبت شد."
});
var json = await resp.Content.ReadAsStringAsync();
Console.WriteLine(json);

ارسال گروهی و نظیربه‌نظیر

برای فرستادن یک متن به چند نفر، کافی است چند شماره در recipients بگذارید. اگر چند شماره نامعتبر باشند، بقیه ارسال می‌شوند و آن‌ها در پاسخ با وضعیت invalid مشخص می‌شوند؛ فقط وقتی همهٔ شماره‌ها نامعتبر باشند کل درخواست با خطای ۱۵۲ رد می‌شود.

برای متن جدا برای هر نفر (مثلاً شمارهٔ سفارش هر مشتری)، به جای رشته، شیء بفرستید:

{
  "senderNumber": "50003123",
  "recipients": [
    {"recipientNumber": "9121234567", "body": "سفارش ۱۰۲۴ شما ارسال شد."},
    {"recipientNumber": "9351234567", "body": "سفارش ۱۰۲۵ شما ارسال شد."}
  ]
}

نوع پیام را خود سامانه از شکل درخواست تشخیص می‌دهد: یک گیرنده با متن کوتاه (تا ۶۴ نویسه) «کد تأیید»، یک گیرنده با متن بلندتر «تکی»، چند شمارهٔ ساده «گروهی» و فهرست شیءها «نظیربه‌نظیر».

پاسخ را درست بخوانید

پاسخ موفق کد HTTP ۲۰۲ و در بدنه code: 100 دارد. داخل data این‌ها مهم‌اند:

• batchId: شناسهٔ کل این ارسال.
• entries: برای هر گیرنده یک ردیف با status (پذیرفته یا نامعتبر)، trackId و cost.
• totalCost: هزینهٔ کل به ریال.

«پذیرفته» یعنی پیام در صف ارسال است، نه این‌که رسیده باشد. وضعیت نهایی هر گیرنده را با GET /v1/message/delivery/{trackId} بپرسید، یا بهتر از آن، یک وب‌هوک تحویل تنظیم کنید تا سامانه خودش خبر دهد.

پنج عادت که از روز اول خطا را کم می‌کنند

1. کلید را در کد ننویسید. در متغیر محیطی یا فایل تنظیمات بیرون از مخزن کد نگه دارید.
2. ارقام را لاتین کنید. شماره‌ای که از فرم فارسی آمده باید پیش از ارسال تبدیل شود.
3. مهلت (timeout) بگذارید تا قطعی لحظه‌ای شبکه صفحهٔ سایت شما را معطل نکند.
4. ارسال را از مسیر اصلی صفحه جدا کنید. در سایت‌های پرترافیک، ارسال را در یک صف یا کار پس‌زمینه انجام دهید.
5. کد خطا را لاگ کنید. پیام فارسی خطا معمولاً خودش راه‌حل را می‌گوید.

جمع‌بندی

اتصال به وب‌سرویس پیامک در هر زبانی چند خط کد است. کار اصلی، رعایت جزئیات است: کلید امن، ارقام لاتین و خواندن درست پاسخ. مستندات کامل درگاه پیامک، با همهٔ متدها و نمونه‌ها، در doc.webservice.ir در دسترس است. اگر حجم ارسال شما بالاست و می‌خواهید حساب درگاه پیامک داشته باشید، از راه تماس با ما درخواست دهید.