اولین پیام شما،
چند خط کد فاصله دارد.

شروع سریع

1. رایگان با موبایل ثبت‌نام کنید و احراز هویت و مدارک موردنیاز حساب را تکمیل کنید.
2. پترنی با متغیرهایی مانند {order_id} ثبت کنید. بعد از تأیید، شناسه پترن NextSMS را از پنل بردارید.
3. کیف پول را شارژ و یک کلید API در پنل ایجاد کنید.
4. در نمونه زیر، دامنه، شناسه پترن و کلید را جایگزین کنید.

ارسال با پترن

curl -X POST "https://api.nextsms.ir/api/v1/messages" \
  -H "Authorization: Bearer ns_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-24815-sms" \
  -d '{
    "patternId": "YOUR_PATTERN_UUID",
    "recipient": "989121234567",
    "parameters": { "order_id": "24815" }
  }'

برای تلاش مجدد همان درخواست، همان کلید یکتا را بفرستید. استفاده از همان کلید با بدنه متفاوت خطای 409 می‌دهد. محدودیت ارسال ۶۰ درخواست در دقیقه برای هر حساب است.

پاسخ و پیگیری

{
  "data": {
    "message": {
      "id": "MESSAGE_UUID",
      "status": "accepted",
      "cost": 1500,
      "segments": 1
    },
    "replayed": false
  }
}

مبلغ بالا نمونه است؛ هزینه واقعی از تعرفه فعال و متن نهایی محاسبه می‌شود. کد HTTP برابر 201 به معنی ثبت درخواست است؛ وضعیت ارسال را از data.message.status بخوانید.

این مسیر نیز به هدر Bearer نیاز دارد. وضعیت accepted پذیرش اپراتور است؛ delivered فقط بعد از گزارش تحویل ثبت می‌شود. گزارش به‌صورت خودکار به‌روزرسانی می‌شود و شیء timing زمان‌های ثبت، ارسال، پذیرش، تحویل و آخرین استعلام را با قالب ISO 8601 و منطقه زمانی UTC برمی‌گرداند.

مدت ثبت تا تحویل در submission_to_delivery_seconds، مدت شروع ارسال سامانه تا تحویل در send_to_delivery_seconds و مدت ارسال اپراتور تا تحویل در operator_to_delivery_seconds بر حسب ثانیه است. این فیلدها داخل timing قرار دارند. زمان تحویل از گزارش اپراتور گرفته می‌شود؛ زمان خواندن پیام مشخص نیست. مقدار ناموجود یا مدت نامعتبر برابر null است. در پیام چندبخشی زمان تحویل آخرین بخشِ تأییدشده ملاک است. مسیر سازگار نیز همین شیء را در هر ردیف entries برمی‌گرداند.

سقف پیش‌فرض وب‌سرویس ۶۰۰۰ درخواست در دقیقه برای هر IP و ۳۰۰۰ درخواست در دقیقه برای هر حساب است؛ کلیدهای یک حساب و هر دو قالب API سهمیه مشترک دارند. محدودیت‌های ورود، ثبت‌نام و ارسال از پنل مستقل‌اند. پاسخ ۴۲۹ هدر Retry-After را با تعداد ثانیه انتظار برمی‌گرداند. برای بازیابی وضعیت، فاصلهٔ استعلام را حداقل ۵ ثانیه بگذارید.

در وضعیت unknown یا processing با کلید جدید دوباره ارسال نکنید؛ ممکن است اپراتور پیام را پذیرفته باشد. تیم پشتیبانی نتیجه را بررسی می‌کند. در رد قطعی اولیه، هزینه خودکار برمی‌گردد؛ تحویل‌نشدن پس از پذیرش مشمول بازگشت خودکار نیست.

خطاهای متداول