شروع سریع با API پیامک در پنج دقیقه
ساخت کلید API، ارسال اولین پیامک با cURL، Node.js، Python و PHP، دریافت وضعیت تحویل با وب‌هوک و نکته‌های ایمنی کلید.
زمان مطالعه: ۱ دقیقه · آخرین بروزرسانی:
گام ۱: کلید دسترسی
در پنل، بخش «وب‌سرویس» یک کلید بسازید. کلید فقط یک بار نمایش داده می‌شود و ما فقط هش آن را نگه می‌داریم؛ پس همان لحظه در جای امن (متغیر محیطی یا مدیر اسرار) ذخیره کنید. می‌توانید دامنهٔ دسترسی (scope) و فهرست IP مجاز تعیین کنید.
گام ۲: اولین ارسال
درخواست زیر یک پیامک می‌فرستد. به‌جای IRNOTI_KEY کلید خود را بگذارید:
curl -X POST https://api.irnoti.ir/api/v1/sms/send \
-H "Authorization: Bearer $IRNOTI_KEY" \
-H "Idempotency-Key: order-1042" \
-H "Content-Type: application/json" \
-d '{"lineId":"1","to":["09121234567"],"text":"سفارش شما ارسال شد"}'نمونهٔ Node.js، Python و PHP در صفحهٔ مستندات هست.
گام ۳: تکرارپذیری
شبکه می‌تواند قطع شود و کد شما درخواست را تکرار کند. هدر Idempotency-Key (حداکثر ۱۰۰ نویسه) تضمین می‌کند ارسال دوباره با همان کلید، پیام تکراری نمی‌سازد و نتیجهٔ قبلی را برمی‌گرداند. برای هر رخداد کسب‌وکار (مثلاً هر سفارش) یک کلید یکتا بفرستید.
گام ۴: وضعیت تحویل
به‌جای پرس‌وجوی مکرر، یک وب‌هوک ثبت کنید تا وضعیت نهایی هر پیام را به آدرس شما بفرستد. امضای HMAC درخواست (هدر X-Irnoti-Signature) را بررسی کنید، رویدادهای تکراری را با X-Irnoti-Delivery نادیده بگیرید و پاسخ ۲۰۰ را سریع برگردانید.
نکتهٔ ایمنی
کلید را هرگز در کد سمت کاربر (مرورگر یا اپ موبایل) نگذارید. درخواست را از سرور خود بفرستید، و اگر کلید لو رفت، همان‌جا آن را ابطال و کلید جدید بسازید.
سوالات متداول
محیط تست دارید؟
بله. کلید Sandbox پیام واقعی نمیفرستد و هزینهای ندارد؛ برای تست یکپارچهسازی مناسب است.
محدودیت تعداد درخواست؟
برای حفاظت، نرخ درخواست محدود است و در صورت عبور، پاسخ ۴۲۹ می‌گیرید. حجم بالا را در یک درخواست گروهی بفرستید.