یک درخواست HTTP، و پیامک شما رفته است

در یک نگاه

اگر فقط ۳۰ ثانیه وقت دارید، همین چهار خط کافی است.

شروع سریع

این پنج قدم به‌ترتیب‌اند؛ جابه‌جا کردنشان یعنی اولین ارسال شما شکست می‌خورد.

1. حساب بسازیددر پنل کاربری شماره‌ی موبایل را وارد کنید و با کد پیامکی وارد شوید. رمزی در کار نیست.
2. کیف‌پول را شارژ کنیداز تب «کیف‌پول». با موجودی صفر هیچ پیامکی ارسال نمی‌شود و پاسخ insufficient balance می‌گیرید.
3. کلید API بسازیداز تب «کلیدها». متن کلید فقط همان یک بار نمایش داده می‌شود؛ همان‌جا در جای امن ذخیره‌اش کنید.
4. قالب را انتخاب یا بسازیداز تب «قالب‌ها»، یا از فهرست قالب‌های عمومی. قالبی که «وصل‌نشده» است هنوز قابل ارسال نیست — چه عمومی، چه اختصاصیِ خودتان.
5. یک پیامک واقعی بفرستید و با چشم ببینیدبه شماره‌ی خودتان. تا وقتی پیامک روی گوشی نیامده، اتصال را تمام‌شده حساب نکنید.

کلید API

کلید در هدر x-api-key می‌رود — نه در Authorization، نه در query string.

x-api-key: pp_OzZk6QvR2mNbXwT8yLhP4dCsJfA1gEuK

• کلید با pp_ شروع می‌شود و در مجموع ۳۵ کاراکتر است.
• ما فقط هشِ کلید را نگه می‌داریم، پس اگر گمش کنید قابل بازیابی نیست — باید کلید تازه بسازید.
• هر کلید را می‌توان از پنل باطل کرد؛ ابطال بلافاصله اثر می‌کند.
• کلید را در مخزن گیت کامیت نکنید. متغیر محیطی بگذارید.

ارسال پیامک

POST /sms/send — تنها اندپوینتی که با کلید API باز می‌شود.

بدنه‌ی درخواست

دو شکل پارامتر، یک نتیجه

شکل اول ساده‌تر است. شکل دوم همان بدنه‌ای است که کلاینت‌های sms.ir از قبل می‌سازند و عمداً پشتیبانی می‌شود تا مهاجرت به تغییر بدنه نیاز نداشته باشد. هزینه و خروجی هر دو یکسان است.

{
  "template": "verify",
  "mobile": "09121110001",
  "parameters": { "CODE": "45678" }
}

{
  "template": "verify",
  "mobile": "09121110001",
  "parameters": [
    { "name": "CODE", "value": "45678" }
  ]
}

پاسخ موفق

{
  "id": "efb20be8-c5b5-4427-ae9a-6f7e83df43b3",
  "status": "queued",
  "segments": 1,
  "encoding": "UCS2",
  "cost": 260
}

قالب‌های عمومی

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

این محدودیت از سمت اپراتور می‌آید، نه ما: هر متنی که به مشترک می‌رسد باید از قبل ثبت و تأیید شده باشد. در عوض، ارسال از طریق قالب سریع است و نیاز به تأییدِ موردی ندارد.

قالب‌های زیر برای همه‌ی مشتری‌ها در دسترس‌اند. اگر متنِ دیگری لازم دارید، از پنل کاربری → تب «قالب‌ها» قالبِ اختصاصیِ خودتان را بسازید؛ بعد از اینکه ما آن را به اپراتور وصل کردیم، دقیقاً مثل بقیه کار می‌کند.

فهرست نمونه — برای دیدن فهرست کامل و به‌روز، وارد پنل کاربری شوید.

چطور از یک قالب استفاده کنیم

کدِ قالب را در فیلد template بگذارید و هر #PARAM# را با یک کلید هم‌نام در parameters پر کنید. مثلاً برای verify با متنِ کد تأیید شما در #COMPANY#: #CODE#:

{
  "template": "verify",
  "mobile": "09121110001",
  "parameters": {
    "COMPANY": "آرین اسپرت",
    "CODE": "45678"
  }
}

متنی که به گیرنده می‌رسد می‌شود: کد تأیید شما در آرین اسپرت: 45678

هزینه و بخش‌بندی

هزینه ثابت نیست. از روی متن نهایی — قالب به‌علاوه‌ی پارامترهای شما — در لحظه‌ی ارسال حساب می‌شود.

یک پیامک ظرفیت محدودی دارد و متن بلندتر به چند پیامک تقسیم می‌شود. چون الفبای فارسی یونیکد است، ظرفیتش کمتر از متن لاتین است:

نتیجه‌ی عملی: یک نویسه‌ی فارسی در یک قالب لاتین، هزینه را بیش از دو برابر می‌کند، و یک لینک بلندتر می‌تواند پیامک یک‌بخشی را دوبخشی کند. متن را با پارامترهای واقعی و بلندترین حالت ممکن امتحان کنید:

چرخه‌ی عمر پیام

بین «پذیرفتیم» تا «رسید» فاصله هست، و این فاصله برای شما معنا دارد.

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

وضعیت هر پیام، متن نهایی و هزینه‌اش را در پنل کاربری، تب «پیامک‌ها» می‌بینید و می‌توانید بر اساس شماره جست‌وجو کنید.

خطاها

همه‌ی پاسخ‌های زیر عیناً از خود API گرفته شده‌اند.

بدنه‌ی خطاها همیشه همین شکل است:

{
  "message": "insufficient balance",
  "error": "Bad Request",
  "statusCode": 400
}

برای خطاهای اعتبارسنجی، message به‌جای رشته یک آرایه از رشته‌هاست. اگر آن را مستقیم چاپ می‌کنید، هر دو حالت را در نظر بگیرید.

نمونه کد

هر نمونه یک کار می‌کند: ارسال کد تأیید و خواندن هزینه‌ی واقعی از پاسخ.

curl -X POST https://api.payampal.com/api/sms/send \
  -H "x-api-key: $PAYAMPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"verify","mobile":"09121110001","parameters":{"CODE":"45678"}}'

async function sendOtp(mobile, code) {
  const res = await fetch('https://api.payampal.com/api/sms/send', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.PAYAMPAL_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      template: 'verify',
      mobile,
      parameters: { CODE: code },
    }),
  });

  const body = await res.json();

  if (!res.ok) {
    // message is a string, or an array for validation errors
    const msg = Array.isArray(body.message) ? body.message.join(', ') : body.message;
    throw new Error(`payampal ${res.status}: ${msg}`);
  }

  // 201 means accepted and charged — not delivered
  return body; // { id, status, segments, encoding, cost }
}

function sendOtp(string $mobile, string $code): array {
    $ch = curl_init('https://api.payampal.com/api/sms/send');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'x-api-key: ' . getenv('PAYAMPAL_API_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'template'   => 'verify',
            'mobile'     => $mobile,
            'parameters' => ['CODE' => $code],
        ], JSON_UNESCAPED_UNICODE),
    ]);

    $raw    = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $body = json_decode($raw, true);
    if ($status >= 400) {
        $m = $body['message'] ?? 'unknown';
        throw new \RuntimeException('payampal: ' . (is_array($m) ? implode(', ', $m) : $m));
    }
    return $body;
}

import os, requests

def send_otp(mobile: str, code: str) -> dict:
    r = requests.post(
        "https://api.payampal.com/api/sms/send",
        headers={"x-api-key": os.environ["PAYAMPAL_API_KEY"]},
        json={
            "template": "verify",
            "mobile": mobile,
            "parameters": {"CODE": code},
        },
        timeout=15,
    )

    if not r.ok:
        m = r.json().get("message", "unknown")
        raise RuntimeError(f"payampal {r.status_code}: {m}")

    # 201 — accepted and charged, delivery happens after this
    return r.json()

مهاجرت از sms.ir

اگر پروژه‌تان الان مستقیم به sms.ir وصل است، سه چیز عوض می‌شود و بس.

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

مرزهای کلید API

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

پیش از انتشار

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

• پیامک واقعی را روی گوشی دیده‌امپاسخ ۲۰۱ به‌تنهایی هیچ چیزی درباره‌ی تحویل نمی‌گوید.
• کلید در متغیر محیطی است، نه در کدو در تاریخچه‌ی گیت هم کامیت نشده.
• نام پارامترها با قالب مو به مو یکی استبزرگی و کوچکی حروف را هم چک کرده‌ام.
• متن را با بلندترین پارامتر ممکن حساب کرده‌امبلندترین لینک، بلندترین نام — تا هزینه‌ی واقعی غافلگیرم نکند.
• خطای insufficient balance را جداگانه هندل کرده‌اماین خطا یعنی «شارژ کن»، نه «دوباره تلاش کن».
• retry خودکار و کورکورانه ندارمچون هر تلاش دوباره، یک پیامک دیگر و یک هزینه‌ی دیگر است.
• id هر ارسال را ذخیره می‌کنمبرای وقتی که باید یک ارسال مشخص را پیگیری کنیم.