پرش به محتوای اصلی

مستندات وب‌سرویس پیامک (API)

راهنمای اتصال سایت و نرم‌افزار به وب‌سرویس پنل پیامک وستا: دریافت کلید API، ارسال کد تایید (پترن)، ارسال پیامک عادی، استعلام اعتبار و گزارش ارسال، با نمونه‌کد cURL، PHP و Python.

پنل پیامک وستا روی زیرساخت IPPanel اجرا می‌شود و وستا نماینده‌ی رسمی آن است. برای همین، وب‌سرویس پنل شما همان Edge API رسمی IPPanel است. در این صفحه آنچه برای اتصال سایت، اپلیکیشن یا نرم‌افزارتان لازم دارید، با نمونه‌کد آمده است. ورود به پنل از sms.vestait.ir است و خرید پنل از صفحه‌ی پنل پیامک.

خلاصه

  • آدرس پایه: https://edge.ippanel.com/v1
  • احراز هویت: کلید API در هدر Authorization، همراه با Content-Type: application/json
  • فرمت شماره‌ها: بین‌المللی (E.164)، مثلاً +989121234567 و خط ارسال +983000505
  • پاسخ موفق: meta.status = true و meta.message_code = "200-1"

۱. دریافت کلید API

  1. با شماره‌ی همراهتان وارد پنل پیامک شوید.
  2. از منوی «توسعه‌دهندگان»، بخش «کلیدهای دسترسی»، یک کلید جدید بسازید.
  3. کلید را فقط در سمت سرور (فایل تنظیمات یا متغیر محیطی) نگه دارید؛ هرگز در کد جاوااسکریپت سایت یا اپلیکیشن موبایل نگذارید، چون هر کسی آن را ببیند می‌تواند از اعتبار شما پیامک بفرستد.

کلید API تاریخ انقضا ندارد. اگر فکر می‌کنید لو رفته است، همان‌جا حذفش کنید و کلید تازه بسازید.

۲. ارسال کد تایید و پیامک‌های خدماتی (پترن)

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

درخواست: POST /api/send

curl -X POST "https://edge.ippanel.com/v1/api/send" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sending_type": "pattern",
    "from_number": "+983000505",
    "code": "YOUR_PATTERN_CODE",
    "recipients": ["+989121234567"],
    "params": { "code": "48213" }
  }'
  • code: کد پترن تأییدشده در پنل.
  • recipients: در ارسال پترنی فقط یک گیرنده مجاز است.
  • params: نام کلیدها باید دقیقاً همان نام متغیرهای تعریف‌شده در پترن باشد (بدون علامت %).

پاسخ موفق:

{
  "data": { "message_outbox_ids": [1123594208] },
  "meta": { "status": true, "message": "انجام شد", "message_code": "200-1" }
}

عدد message_outbox_ids را ذخیره کنید؛ برای گرفتن گزارش ارسال لازم است.

۳. ارسال پیامک عادی (وب‌سرویس)

برای متن‌های غیرتکراری به یک یا چند گیرنده:

curl -X POST "https://edge.ippanel.com/v1/api/send" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sending_type": "webservice",
    "from_number": "+983000505",
    "message": "سفارش شما ثبت شد.",
    "params": { "recipients": ["+989121234567", "+989351234567"] }
  }'

برای ارسال زمان‌بندی‌شده، فیلد اختیاری send_time را با قالب YYYY-MM-DD HH:MM:SS به وقت UTC اضافه کنید؛ بدون آن، پیامک فوراً ارسال می‌شود. ارسال انبوه تبلیغاتی به شماره‌هایی که دریافت تبلیغات را بسته‌اند نمی‌رسد؛ برای پیامک خدماتی از پترن استفاده کنید.

۴. استعلام اعتبار حساب

curl "https://edge.ippanel.com/v1/api/payment/credit/mine" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"

مقدار اعتبار در data.credit برمی‌گردد. پیشنهاد می‌کنیم وقتی اعتبار از حدی کمتر شد، سامانه‌ی شما به مدیر هشدار دهد تا ارسال کد تایید قطع نشود.

۵. گزارش ارسال

curl "https://edge.ippanel.com/v1/api/report/by_bulk?messages_outbox_id=1123594208" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"

شناسه همان عددی است که در پاسخ ارسال گرفتید. وضعیت ارسال در فیلدهای state و status برمی‌گردد. گزارش کامل هر ارسال در پنل هم دیده می‌شود.

نمونه‌کد PHP

<?php
function send_otp($mobile, $otp) {
    $body = [
        'sending_type' => 'pattern',
        'from_number'  => '+983000505',
        'code'         => getenv('SMS_PATTERN_OTP'),
        'recipients'   => ['+98' . ltrim($mobile, '0')],
        'params'       => ['code' => (string) $otp],
    ];
    $ch = curl_init('https://edge.ippanel.com/v1/api/send');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode($body, JSON_UNESCAPED_UNICODE),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'Authorization: ' . getenv('SMS_API_KEY'),
        ],
    ]);
    $res = json_decode((string) curl_exec($ch), true);
    curl_close($ch);
    return !empty($res['meta']['status']);
}

نمونه‌کد Python

import os, requests

def send_otp(mobile: str, otp: str) -> bool:
    r = requests.post(
        "https://edge.ippanel.com/v1/api/send",
        headers={"Authorization": os.environ["SMS_API_KEY"]},
        json={
            "sending_type": "pattern",
            "from_number": "+983000505",
            "code": os.environ["SMS_PATTERN_OTP"],
            "recipients": ["+98" + mobile.lstrip("0")],
            "params": {"code": otp},
        },
        timeout=10,
    )
    return bool(r.json().get("meta", {}).get("status"))

خطاها

در پاسخ ناموفق، meta.status برابر false است، توضیح خطا در meta.message می‌آید و خطای هر فیلد در meta.errors.

  • 400-1: کلید API نامعتبر است یا ارسال نشده.
  • 400-2: درخواست ناقص است (مثلاً فیلد اجباری خالی است)؛ جزئیات در meta.errors.

همیشه علاوه بر کد HTTP، مقدار meta.status را بررسی کنید.

توصیه‌های امنیتی برای کد تایید

  • برای هر شماره و هر IP محدودیت تعداد درخواست بگذارید (مثلاً یک کد در هر دو دقیقه)، تا ربات‌ها اعتبار شما را خالی نکنند.
  • کد را ۵ یا ۶ رقمی، تصادفی و با اعتبار کوتاه (چند دقیقه) بسازید و بعد از یک بار استفاده باطل کنید.
  • تعداد دفعات وارد کردن کد اشتباه را محدود کنید.

درباره‌ی نکات بیشتر، راهنمای پیامک کد تایید (OTP) را بخوانید.

وردپرس و ووکامرس

اگر سایتتان وردپرسی است، لازم نیست کد بنویسید: افزونه‌ی پیامک ووکامرس برای ورود با کد تایید و اطلاع‌رسانی سفارش آماده است. برای راه‌اندازی، کلید API و کد پترن‌ها را در تنظیمات افزونه وارد کنید. اگر کمک لازم دارید، از راه‌های تماس با ما هر روز از ۸ صبح تا ۸ شب پاسخ می‌دهیم.

پرسش‌های پرتکرار

آدرس وب‌سرویس با آدرس پنل فرق دارد؟

بله. پنل کاربری روی sms.vestait.ir است و درخواست‌های API به edge.ippanel.com فرستاده می‌شوند. کلید API را از همان پنل خودتان می‌سازید.

شماره‌ی خط ارسال را از کجا بدانم؟

خط‌های فعال حسابتان در پنل، بخش خطوط، دیده می‌شوند. پترن‌ها معمولاً از خط خدماتی ارسال می‌شوند؛ اگر مطمئن نیستید، از پشتیبانی بپرسید.

چرا پیامک پترنی ارسال نمی‌شود؟

سه علت رایج: پترن هنوز تأیید نشده، نام متغیرها در params با پترن یکی نیست، یا اعتبار حساب تمام شده است. پیام دقیق در meta.message پاسخ می‌آید.

مطمئن نیستید کدام خدمت به کارتان می‌آید؟

۴۵ دقیقه با یک کارشناس وستا صحبت کنید؛ نیازتان را می‌شنویم و مسیر ارزان‌تر و سریع‌تر را نشانتان می‌دهیم.

رزرو وقت مشاوره تماس: ۰۹۱۵ ۵۵۱ ۳۷۸۲ پشتیبانی در تلگرام پشتیبانی در واتس‌اپ