IRNoti
ورودشروع رایگان
مستنداتv1 stable
دریافت کلید API
REST API · JSON · v1

مستندات API پیامک

وب‌سرویس REST با بدنه JSON. هر کاری که در پنل انجام می‌دهید با API هم ممکن است. همه نمونه‌ها برای ۱۱ زبان تولید می‌شود و می‌توانید هر درخواست را همین‌جا با کلید آزمایشی اجرا کنید.

شروع سریع

  1. ۱در پنل ثبت‌نام کنید و از بخش «وب‌سرویس» یک کلید آزمایشی بسازید.
  2. ۲با lineId: "sandbox" یک پیام بفرستید — بدون هزینه و بدون ارسال واقعی.
  3. ۳پس از احراز هویت، کلید واقعی بسازید و شناسه خط واقعی را از خطوط من بگیرید.
آدرس پایه
BASE

احراز هویت

هر درخواست باید کلید دسترسی را در هدر Authorization: Bearer irn_live_… داشته باشد. کلید فقط هنگام ساخت یک‌بار نمایش داده می‌شود و در سرور ما فقط به‌صورت هش نگهداری می‌شود؛ آن را در کد سمت کاربر (مرورگر/اپ) قرار ندهید.

دسترسی (scope)اجازه
sms.sendارسال پیامک و پترن
sms.readبرآورد هزینه، گزارش پیام‌ها و خطوط
wallet.readمشاهده اعتبار
phonebook.readخواندن دفترچه تلفن
phonebook.writeویرایش دفترچه تلفن
  • برای هر کلید می‌توانید فهرست IP مجاز تعیین کنید؛ درخواست از IP دیگر ۴۰۱ می‌گیرد.
  • کلید آزمایشی با پیشوند irn_test_ شروع می‌شود و هرگز پیام واقعی نمی‌فرستد.
  • ساخت و حذف کلید فقط از پنل ممکن است، نه با خودِ کلید.

قراردادها

  • آدرس پایه:
  • مبلغ‌ها عدد صحیح به ریال و به‌صورت رشته هستند (مثلا "1960")؛ هرگز اعشار نیستند.
  • شماره‌ها: 09121234567، +989121234567 و ارقام فارسی پذیرفته می‌شود.
  • زمان‌ها ISO 8601 در UTC هستند.
  • Idempotency: برای ارسال، هدر Idempotency-Key بفرستید تا تلاش دوباره (timeout، قطع اینترنت) پیام تکراری نسازد.
  • محدودیت نرخ: ارسال تا ۶۰۰ و پترن تا ۱۲۰۰ درخواست در دقیقه برای هر IP؛ پاسخ 429 یعنی کمی صبر کنید.

محدودیت نرخ

در صورت عبور از محدودیت، پاسخ 429 برگردانده می‌شود. محدودیت‌ها به‌ازای هر IP و در هر دقیقه‌اند.

ارسال پیامک600 req/min
ارسال پترن1200 req/min

خطاها

کد وضعیت HTTP نتیجه را مشخص می‌کند. بدنه خطا شامل message و گاهی code و details است.

400درخواست نامعتبر (فیلد ناقص، شماره نامعتبر…)
401کلید نامعتبر، حذف‌شده یا IP مجاز نیست
402اعتبار کافی نیست
403دسترسی (scope) یا احراز هویت حساب کافی نیست
404منبع یافت نشد
409تعارض (مثلا نام تکراری)
422تعرفه تعریف نشده
429تعداد درخواست زیاد
5xxخطای سرور — با همان Idempotency-Key دوباره تلاش کنید

مرجع endpointها

POST/sms/sos
ارسال تضمین‌شده (SOS)

ارسال پیام حیاتی از مسیرهای پلتفرم با جایگزینی خودکار پرووایدر.

POST/sms/send
ارسال پیامک

ارسال یک متن به یک یا چند گیرنده، یا به گروه‌های دفترچه تلفن.

POST/sms/quote
برآورد هزینه

هزینه دقیق یک ارسال را بدون ارسال و بدون کسر اعتبار برمی‌گرداند.

POST/sms/pattern
ارسال پترن (قالب)

ارسال پیام بر اساس یک قالب تأییدشده با جایگذاری پارامترها — مناسب کد تأیید و پیام‌های تراکنشی.

GET/sms/messages
فهرست پیام‌ها

پیام‌های ارسالی اخیر با وضعیت تحویل.

GET/sms/messages/{id}
جزئیات یک پیام

وضعیت و جزئیات یک پیام با شناسه.

GET/sms/lines
خطوط من

خطوطی که می‌توانید از آن‌ها ارسال کنید.

GET/phonebook/groups
گروه‌های دفترچه تلفن

فهرست گروه‌ها با تعداد مخاطبین.

POST/phonebook/groups
ساخت گروه

یک گروه جدید در دفترچه تلفن بسازید.

POST/phonebook/groups/{id}/contacts
افزودن مخاطب

افزودن چند مخاطب به یک گروه.

GET/wallet
اعتبار

موجودی کیف پول به ریال.

بعدی ←
ارسال تضمین‌شده (SOS)
curl -X POST '/sms/sos' \
  -H "Authorization: Bearer $IRNOTI_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: alert-77' \
  -d '{
  "to": [
    "09121234567"
  ],
  "text": "هشدار: قطعی سرویس",
  "lineId": "sandbox"
}'
پاسخ نمونه200 OK
{
  "batchId": "920",
  "count": 1,
  "totalPrice": "5000",
  "replayed": false
}