وب سرویس پیامک فراز اس ام اس — مستندات REST API و SDK ارسال پیامک

مستندات رسمیِ وب سرویس پیامک فراز اس ام اس (ایران پیامک) برای ارسال پیامک با REST API: ارسال پیامک پترن، رمز یک‌بارمصرف (OTP)، ارسال گروهی و سریع، گزارش تحویل، دفترتلفن و کیف‌پول. آدرس پایه: https://api.iranpayamak.com — احراز هویت با هدر Api-Key (کلید از پنل، حساس به حروف؛ بدون نیاز به لاگین).

SDK رسمیِ همه‌ی زبان‌ها: pip install farazsms · npm install farazsms · composer require farazsms/php · composer require farazsms/laravel · dotnet add package FarazSMS · go get github.com/ghaffari273/farazsms-go.

ابزارها و راهنماها: SDK و کتابخانه‌ها · مرجع خطا و کدهای تحویل · راهنمای کارها · واژه‌نامه · ارسال با URL · Node-RED · وب‌هوک · OpenAPI و Postman

دسته‌بندی وب‌سرویس‌ها (64 سرویس)

ارسال پیامک — Send SMS

نقطهٔ شروع. برای OTP از «ارسال با پترن» استفاده کن — سریع‌ترین راه.

• POST /ws/v1/sms/pattern — ارسال پیامک پترن (قالب‌دار) — ارسال پیامک قالب‌دار (OTP، کد تأیید، اعلان تراکنش). سریع‌ترین راه و بدون صف — برای کدهای یک‌بارمصرف از این استفاده کن.
• POST /ws/v1/sms/simple — ارسال پیامک ساده (گروهی) از طریق وب‌سرویس — متن خودتان را می‌نویسید و برای یک یا چند شماره می‌فرستید — ساده‌ترین راه برای شروع و تستِ اتصال. مناسب اطلاع‌رسانی و پیامک تبلیغاتی گروهی. پیامک پیش از ارسال به تأیید ناظر انسانی می‌رسد، پس ممکن است چند دقیقه طول بکشد؛ برای کد تأیید و هر پیامکی که باید زیر ۵ ثانیه برسد از «ارسال با پترن» استفاده کنید.
• POST /ws/v1/sms/keywords — ارسال پیامک با متغیر (شخصی‌سازی‌شده) — ارسال انبوهِ شخصی‌سازی‌شده؛ متغیرها (مثل نام مخاطب) داخل `%...%` در متن جای می‌گیرند.
• POST /ws/v1/lbs — ساخت ارسال موقعیت‌محور (LBS) — ساخت کمپین ارسال بر اساس موقعیت جغرافیایی؛ به کسانی که در یک محدوده و بازه‌ی زمانی مشخص هستند پیامک می‌دهد.
• GET /ws/v1/lbs — فهرست ارسال‌های موقعیت‌محور (LBS) — فهرست کمپین‌های موقعیت‌محورِ ساخته‌شده، برای پیگیری وضعیتشان.
• PUT /ws/v1/lbs/{lbsId} — ویرایش ارسال موقعیت‌محور (LBS) — ویرایش یک کمپین موقعیت‌محور پیش از اجرا (متن، محدوده، فیلترها).
• GET /ws/v1/lbs/{lbsId} — جزئیات ارسال موقعیت‌محور (LBS) — دیدن جزئیات کاملِ یک کمپین موقعیت‌محور با شناسه‌اش.
• PATCH /ws/v1/lbs/{lbsId}/cancel — لغو ارسال موقعیت‌محور (LBS) — لغو یک کمپین موقعیت‌محور پیش از ارسال.
• POST /ws/v1/sms/bank — ارسال پیامک به بانک شماره — ارسال هدفمند به «بانک شماره» (شماره‌های آماده بر اساس صنف/منطقه) بدون اینکه دفترتلفن داشته باشی.
• POST /ws/v1/sms/postal/send — Send Postal Code SMS
• POST /ws/v1/sms/sample — ارسال پیامک نمونه — ارسال یک نمونه فقط به خودت، برای تست متن و خط فرستنده پیش از کمپین انبوه.
• POST /ws/v1/sms/simple-file — ارسال پیامک ساده از اکسل — ارسال متن ثابت با فهرست گیرنده‌ها از فایل Excel — برای فهرست‌های بزرگ.
• POST /ws/v1/sms/voice/calculate-cost — Calculate Voice Message Cost
• GET /ws/v1/sms/voice/download-file — دانلود فایل پیام صوتی — دانلود دوباره‌ی یک فایل صوتیِ آپلودشده با `file_id`.
• POST /ws/v1/sms/voice/send — ارسال پیام صوتی — ارسال تماس صوتی (پیام ضبط‌شده) به گیرنده‌ها؛ ابتدا باید فایل صوتی آپلود شده باشد.
• POST /ws/v1/sms/voice/upload-file — آپلود فایل پیام صوتی — آپلود فایل صوتی و گرفتن `file_id` — پیش‌نیازِ ارسال پیام صوتی.

مدیریت پترن — Patterns

ساخت و مدیریت پترن‌ها — پیش‌نیازِ ارسالِ پترن.

• POST /ws/v1/patterns — ساخت پترن جدید — ساخت پترن (قالب) جدید با متغیر؛ پیش‌نیازِ ارسال پترن. پس از ساخت باید تأیید شود.
• GET /ws/v1/patterns — فهرست پترن‌ها — فهرست پترن‌های حساب؛ از این‌جا `code` پترن را برای ارسال پیدا کن.
• PUT /ws/v1/patterns/{code} — ویرایش پترن — ویرایش متن یا متغیرهای یک پترن موجود (ممکن است نیاز به تأیید مجدد داشته باشد).
• GET /ws/v1/patterns/{code} — جزئیات پترن — دیدن جزئیات یک پترن (نام و تعداد متغیرها) تا ارسالت دقیقاً با آن بخواند.
• DELETE /ws/v1/patterns/{code} — حذف پترن — حذف دائمیِ یکی از پترن‌های خودتان، با کد پترن. برای پاک‌سازی پترن‌های آزمایشی و از‌رده‌خارج.

گزارش و دریافت — Reports & Inbox

بعد از ارسال: وضعیت ارسال‌ها و پیامک‌های دریافتی.

• GET /ws/v1/inbox — دریافت پیامک‌های ورودی (صندوق دریافت) — خواندن پیامک‌های دریافتی (پاسخ مشتری‌ها)؛ برای دوطرفه‌کردن مکالمه این را به‌صورت دوره‌ای poll کن.
• GET /ws/v1/send_request — فهرست درخواست‌های ارسال — فهرست همه‌ی ارسال‌ها با وضعیت کلی‌شان (صف، ارسال‌شده، رد…)؛ با `status` فیلتر کن.
• GET /ws/v1/send_request/{send_request_id} — جزئیات درخواست ارسال — دیدن جزئیات یک ارسالِ مشخص با شناسه‌اش.
• GET /ws/v1/send_request/{send_request_id}/items — وضعیت تحویل گیرنده‌ها — وضعیت تحویلِ تک‌تک گیرنده‌ها در یک ارسال (تحویل‌شده، ناموفق، لیست سیاه…).

دفترتلفن و مخاطبین — Phonebook & Contacts

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

• GET /example/phone-book/{phone_book}/data.xlsx — دانلود نمونه اکسل دفترتلفن — دانلود فایل نمونه‌ی Excel آن دفترتلفن؛ ستون‌ها را طبق آن پر کن — پیش‌نیازِ افزودن از Excel.
• POST /ws/v1/phone_book — ساخت دفترتلفن جدید — ساخت دفترتلفن جدید برای دسته‌بندی مخاطبین.
• GET /ws/v1/phone_book — فهرست دفترتلفن‌ها — فهرست دفترتلفن‌ها و شناسه‌هایشان.
• PUT /ws/v1/phone_book/{id} — ویرایش دفترتلفن — تغییر نام یا ستون‌های یک دفترتلفن موجود.
• POST /ws/v1/phone_book_attribute — ساخت ویژگی دفترتلفن — ساخت ستون/ویژگی دلخواه (مثل تاریخ تولد یا کد ملی) برای مخاطبین.
• GET /ws/v1/phone_book_attribute — فهرست ویژگی‌های دفترتلفن — فهرست ویژگی‌های تعریف‌شده و شناسه‌هایشان (برای استفاده هنگام افزودن مخاطب).
• POST /ws/v1/phone_book_data — افزودن مخاطب — افزودن یک مخاطبِ تکی به دفترتلفن.
• GET /ws/v1/phone_book_data — فهرست مخاطبین دفترتلفن — گرفتن مخاطبینِ یک دفترتلفن با جستجو و صفحه‌بندی.
• POST /ws/v1/phone_book_data/bulk-upsert — افزودن انبوه مخاطبین — افزودن/به‌روزرسانیِ انبوه مخاطبین در یک درخواست (سقف ۵۰۰ مخاطب).
• POST /ws/v1/phone_book_data/excel-upsert — افزودن مخاطبین از اکسل — وارد کردن مخاطبین از فایل Excel، بدون محدودیت تعداد.
• DELETE /ws/v1/phone_book_data/{id} — حذف مخاطب — حذف یک مخاطب با شناسه (برگشت‌ناپذیر).

حساب و کیف‌پول — Account & Wallet

اعتبار، شارژ، پروفایل، خطوط و سفارش‌ها. (تستِ اعتبار = تستِ بی‌هزینهٔ کلید)

• GET /ws/v1/account/balance — موجودی و اعتبار حساب — دیدن موجودی حساب؛ بهترین تستِ بی‌هزینه برای اطمینان از درستیِ کلید API.
• POST /ws/v1/account/wallet/charge — شارژ کیف‌پول — شارژ کیف‌پولِ حساب (یک سفارشِ قابل‌پرداخت ساخته می‌شود).
• GET /ws/v1/account/profile — پروفایل حساب — گرفتن اطلاعات پروفایل حساب (نام و مشخصات).
• POST /ws/v1/account/register — ثبت‌نام حساب — ثبت‌نام حساب از طریق API (برای ارسال پیامک لازم نیست).
• POST /ws/v1/account/update — به‌روزرسانی حساب — به‌روزرسانی اطلاعات حساب.
• GET /ws/v1/lines/accessible — خطوط فرستنده‌ی حساب — فهرست خطوط فرستنده‌ی قابل‌استفاده؛ شماره‌ی خط را برای `line_number` از این‌جا بردار.
• POST /ws/v1/orders/apply-discount — اعمال کد تخفیف سفارش — اعمال کد تخفیف روی یک سفارش پیش از پرداخت.
• POST /ws/v1/orders/cancel — لغو سفارش — لغو یک سفارشِ پرداخت‌نشده.
• POST /ws/v1/orders/pay — پرداخت سفارش — پرداخت یک سفارشِ ساخته‌شده (مثلاً شارژ کیف‌پول).

پشتیبانی — Tickets

ارتباط با پشتیبانی از طریق API.

• POST /ws/v1/ticket — ساخت تیکت پشتیبانی — ساخت تیکت پشتیبانی جدید.
• GET /ws/v1/ticket — فهرست تیکت‌ها — فهرست تیکت‌های پشتیبانی (فیلتر با وضعیت و دپارتمان).
• POST /ws/v1/ticket/closed — بستن تیکت — بستن یک تیکت.
• GET /ws/v1/ticket/file/download — دانلود پیوست تیکت — دانلود فایلِ پیوستِ یک پیامِ تیکت.
• POST /ws/v1/ticket/reply — Replay to Ticket
• GET /ws/v1/ticket/{id} — مشاهده مکالمات تیکت — دیدن کل مکالمات یک تیکت.

مرجع و ابزار — Reference & Tools

داده‌های کمکی: استان/شهر، جنسیت، محاسبه هزینه، بانک شماره.

• GET /cities — فهرست شهرهای استان — فهرست شهرهای یک استان (برای فیلترهای ارسال هدفمند).
• GET /provinces — فهرست استان‌ها — فهرست استان‌ها؛ با `has_any_banks` فقط استان‌هایی که بانک شماره دارند.
• GET /ws/v1/number_bank — فهرست بانک‌های شماره — فهرست بانک‌های شماره‌ی موجود برای ارسال هدفمند (فیلتر با استان/شهر).
• GET /ws/v1/number_bank/{number_bank_id} — جزئیات یک بانک شماره — اطلاعات کاملِ یک بانک شماره — عنوان، استان، شهر و فایل‌های پیوست‌شده.
• POST /ws/v1/sms/calculate-cost — برآورد هزینه‌ی ارسال پیامک — برآورد هزینه‌ی یک ارسال (مثلاً ارسال کدپستی) پیش از انجام آن.
• GET /ws/v1/sms/postal/get-available-lines — خطوط مجاز ارسال کدپستی — خطوط مجاز برای ارسال کدپستی را برمی‌گرداند.
• GET /ws/v1/sms/postal/get-genders — فهرست جنسیت‌ها (ارسال کدپستی) — فهرست جنسیت‌ها برای فیلترِ ارسال کدپستی.
• GET /ws/v1/sms/postal/get-receiver-count — تخمین تعداد گیرنده (کدپستی) — تخمین تعداد گیرنده پیش از ارسالِ کدپستی، بر اساس فیلترها (کدپستی، جنسیت، بازه‌ی سنی، پیش‌شماره).

ورود و حساب پنل — Panel Login & Account

این‌ها برای ورود به پنل‌اند؛ برای فراخوانی وب‌سرویس‌ها «لازم نیستند».

• POST /ws/v1/auth/login — ورود به پنل — ورودِ کاربر به پنل (نه اتصالِ وب‌سرویس). برای فراخوانی APIها از Api-Key استفاده کن، نه این.
• POST /ws/v1/auth/logout — خروج از پنل — خروج از نشستِ پنل؛ به وب‌سرویس‌ها ربطی ندارد.
• POST /ws/v1/auth/register — ثبت‌نام در پنل — ثبت‌نام کاربر در پنل؛ برای کار با APIها لازم نیست.
• GET /ws/v1/auth/show_register_form — فرم ثبت‌نام پنل — فیلدهای موردنیاز فرم ثبت‌نام پنل را برمی‌گرداند.
• POST /ws/v1/auth/verify-2fa — تأیید کد دومرحله‌ای — تأیید کد دومرحله‌ای هنگام ورود به پنل.

برای هوش مصنوعی: llms.txt · llms-full.txt · OpenAPI.

English documentation