مقدمه

این مستندات راهنمای کامل وب‌سرویس پیامک سامانه پیامک (نسخه ۳ – REST) است. درخواست‌ها از طریق POST (با بدنه JSON) انجام می‌شوند و پاسخ‌ها به صورت JSON بازگردانده می‌شوند.

آدرس پایه

https://api-payamak.com/api/v3/rest

(برای استفاده از نسخه ۳، آدرس را به api/v3/rest تغییر دهید)

  • برای احراز هویت از هدرهای Authorization یا Token استفاده کنید. تمام متدها با متد POST فراخوانی می‌شوند مگر در مواردی که DELETE ذکر شده باشد.

احراز هویت

برای احراز هویت، API-KEY خود را از طریق هدرهای زیر ارسال کنید:

Authorization: YOUR_API_KEY
Token: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY

یا به‌جای توکن، از username/password استفاده کنید:

Username: YOUR_USERNAME
Password: YOUR_PASSWORD

ارسال پیامک POST

POST https://api-payamak.com/api/v3/rest/sms/send

ارسال پیامک به یک یا چند گیرنده (حداکثر ۲۰۰ گیرنده در هر فراخوانی).

پارامتر نوع اجباری توضیح
from String اجباری شماره فرستنده
recipients Array of String اجباری لیست گیرندگان
message String اجباری متن پیام (حداکثر ۹۰۰ کاراکتر)
type Integer اختیاری نوع پیام (۰=معمولی، ۱=فلش) – پیش‌فرض ۰
📤 مثال درخواست
{
    "from": "21xxxxxxxx",
    "recipients": ["09123456789", "09123456789"],
    "message": "خدمات پیام کوتاه",
    "type": 0
}
📤 مثال پاسخ
{
    "return": {
        "status": 200,
        "message": "پیام با موفقیت در صف ارسال قرار گرفت"
    },
    "data": {
        "messageid": 8792343,
        "message": "خدمات پیام کوتاه",
        "state": "فعال",
        "from": "21xxxxxxxx",
        "date": 1786619709
    }
}

ارسال گروهی (چند پیام) POST

POST https://api-payamak.com/api/v3/rest/sms/multiple-send

ارسال چندین پیام متفاوت به گیرنده‌های مختلف با شماره‌های فرستنده متفاوت. تعداد آرایه‌ها باید برابر باشد.

پارامتر نوع اجباری توضیح
fromArrayArray of Stringاجباریشماره‌های فرستنده
recipientsArray of Stringاجباریشماره‌های گیرنده
messageArrayArray of Stringاجباریمتن پیام‌ها
typeArrayArray of Integerاجبارینوع هر پیام (۰ یا ۱)
📤 مثال درخواست
{
    "fromArray": ["21xxxx", "21xxxx"],
    "recipients": ["09123456789", "09123456789"],
    "messageArray": ["پیام", "پیام"],
    "typeArray": [0, 0]
}

کنترل وضعیت پیامک POST

POST https://api-payamak.com/api/v3/rest/sms/status

دریافت وضعیت پیام‌های ارسال شده (حداکثر ۵۰ شناسه در هر فراخوانی).

پارامتر نوع اجباری توضیح
messageidArray of Longاجباریشناسه‌های پیام
📤 مثال درخواست
{
    "messageid": [8792343, 8792344]
}
📤 مثال پاسخ
{
    "return": {
        "status": 200,
        "message": "وضعیت پیام‌ها"
    },
    "entries": [
        {
            "messageid": 8792343,
            "from": "21xxxx",
            "number": "09123456789",
            "state": 10,
            "status": "رسیده به گیرنده"
        }
    ]
}

جزئیات پیامک POST

POST https://api-payamak.com/api/v3/rest/sms/select

مشابه Status اما با اطلاعات کامل‌تر (متن پیام، شماره فرستنده، تاریخ).

پارامتر نوع اجباری توضیح
messageidArray of Longاجباریشناسه‌های پیام
📤 مثال درخواست
{
    "messageid": [8792343]
}

لیست ارسال‌ها POST

POST https://api-payamak.com/api/v3/rest/sms/selectoutbox

دریافت لیست پیام‌های ارسال شده در بازه زمانی (حداکثر ۱ روز).

پارامتر نوع اجباری توضیح
startdateUnixTimeاجباریتاریخ شروع
enddateUnixTimeاجباریتاریخ پایان
📤 مثال درخواست
{
    "startdate": 1759533200,
    "enddate": 1809619600
}

آخرین وضعیت پیام POST

POST https://api-payamak.com/api/v3/rest/sms/latest

دریافت آخرین پیام ارسال‌شده (آخرین رکورد بر اساس شناسه) همراه با جزئیات کامل. این متد نیازی به پارامتر ورودی ندارد.

📤 مثال پاسخ
{
    "return": {
        "status": 200,
        "message": "آخرین وضعیت پیام"
    },
    "data": {
        "messageid": 8792340,
        "message": "خدمات پیام کوتاه",
        "recipients_count": 2,
        "recipients": ["09123456789", "09123456789"],
        "from": "21xxxxxxxx",
        "state": 10,
        "date": 1786619709
    }
}

آخرین ارسال‌ها POST

POST https://api-payamak.com/api/v3/rest/sms/latestoutbox

دریافت آخرین پیام‌های ارسال شده (حداکثر ۲۰۰ مورد).

پارامتر نوع اجباری توضیح
pagesizeIntegerاختیاریتعداد نتایج (پیش‌فرض ۲۰۰)
📤 مثال درخواست
{
    "pagesize": 50
}

تعداد ارسال‌ها POST

POST https://api-payamak.com/api/v3/rest/sms/countoutbox

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

پارامتر نوع اجباری توضیح
startdateUnixTimeاجباریتاریخ شروع
enddateUnixTimeاجباریتاریخ پایان
📤 مثال درخواست
{
    "startdate": 1759533200,
    "enddate": 1789619600
}

تعداد دریافت‌ها POST

POST https://api-payamak.com/api/v3/rest/sms/countinbox

تعداد پیام‌های دریافت شده با فیلتر شماره و وضعیت خوانده‌شدن.

پارامتر نوع اجباری توضیح
startdateUnixTimeاجباریتاریخ شروع
enddateUnixTimeاجباریتاریخ پایان
numberStringاختیاریشماره خط گیرنده
isreadIntegerاختیاری۰=نخوانده، ۱=خوانده
📤 مثال درخواست
{
    "startdate": 1759533200,
    "enddate": 1789619600,
    "number": "1000xxxx",
    "isread": 0
}

دریافت پیام‌های دریافتی POST

POST https://api-payamak.com/api/v3/rest/sms/inbox

دریافت لیست پیام‌های دریافتی کاربر با قابلیت تعیین تعداد و offset (صفحه‌بندی ساده).

پارامتر نوع اجباری توضیح
countIntegerاختیاریتعداد پیام‌های مورد نظر (پیش‌فرض ۵۰)
offsetIntegerاختیاریمیزان offset (پیش‌فرض ۰)
📤 مثال درخواست
{
    "count": 50,
    "offset": 0
}

دریافت پیامک (صفحه‌بندی) POST

POST https://api-payamak.com/api/v3/rest/sms/inboxpaged

دریافت پیام‌های دریافتی با صفحه‌بندی (تا ۵۰۰ مورد در هر صفحه).

پارامتر نوع اجباری توضیح
numberStringاختیاریشماره خط
isreadIntegerاختیاری۰=نخوانده، ۱=خوانده
pageIntegerاختیاریشماره صفحه (پیش‌فرض ۱)
pagesizeIntegerاختیاریتعداد در هر صفحه (پیش‌فرض ۲۰۰، حداکثر ۵۰۰)
📤 مثال درخواست
{
    "number": "1000xxxx",
    "isread": 0,
    "page": 1,
    "pagesize": 200
}

دریافت پیامک POST

POST https://api-payamak.com/api/v3/rest/sms/receive

دریافت حداکثر ۵۰ پیام خوانده‌نشده و بروزرسانی خودکار وضعیت به خوانده‌شده.

پارامتر نوع اجباری توضیح
numberStringاختیاریشماره خط
isreadIntegerاختیاری۰=نخوانده (پیش‌فرض)، ۱=خوانده
📤 مثال درخواست
{
    "number": "1000xxxx",
    "isread": 0
}

کنترل وضعیت با شماره POST

POST https://api-payamak.com/api/v3/rest/sms/statusbynumber

دریافت وضعیت پیام‌های ارسال شده به یک شماره خاص از تاریخ شروع تا حال.

پارامتر نوع اجباری توضیح
numberStringاجباریشماره موبایل گیرنده
startdateUnixTimeاجباریتاریخ شروع
pagesizeIntegerاختیاریتعداد نتایج (پیش‌فرض ۵۰، حداکثر ۵۰)
📤 مثال درخواست
{
    "number": "09123456789",
    "startdate": 1785677000,
    "pagesize": 50
}

اعتبار کاربر POST

POST https://api-payamak.com/api/v3/rest/my/credit

دریافت اعتبار باقی‌مانده حساب کاربری (ریال).

📤 مثال پاسخ
{
    "return": {
        "status": 200,
        "message": "اعتبار کاربر"
    },
    "data": {
        "credit": 1500000
    }
}

اطلاعات کاربر POST

POST https://api-payamak.com/api/v3/rest/my

دریافت مشخصات کامل کاربر شامل نام، شرکت، اعتبار، تعرفه و ...

📤 مثال پاسخ
{
    "return": {
        "status": 200,
        "message": "اطلاعات کاربر"
    },
    "data": {
        "fullname": "محمدرضا راه‌پیما",
        "mellicode": "001xxxxxxx",
        "shenasname": "001xxxxxxx",
        "date": "1375/11/22",
        "postcode": "1234567890",
        "addr": "تهران _ تهران _ پايتخت",
        "expire_time": "1900000000",
        "credit": "10000000.000",
        "tarrif": "2400",
        "type": "نماینده"
    }
}

ثبت‌نام کاربر POST

POST https://api-payamak.com/api/v3/rest/user/register

ایجاد حساب کاربری جدید در سامانه. (هر مدیر در روز حداکثر ۲ کاربر ثبت‌نام می‌کند.)

پارامتر نوع اجباری توضیح
unameStringاجبارینام کاربری (فقط حروف و اعداد انگلیسی)
passwdStringاجباریرمز عبور
passwd_repeatStringاجباریتکرار رمز عبور
parentStringاجبارینام کاربری مدیر
mobileStringاجباریشماره موبایل (۰۹۱۲... یا ۹۸۹۱۲...)
melli_codeStringاجباریکد ملی ۱۰ رقمی
packageIntegerاجباریشناسه پکیج (بسته تعرفه‌ای)
resellerIntegerاجباریوضعیت نمایندگی (۰=نیست، ۱=هست)
📤 مثال درخواست
{
    "uname": "amirreza",
    "passwd": "123456",
    "passwd_repeat": "123456",
    "parent": "admin",
    "mobile": "09121234567",
    "melli_code": "1234567890",
    "package": 1,
    "reseller": 1
}
📤 مثال پاسخ موفق
{
    "return": {
        "status": 200,
        "message": "ثبت نام با موفقیت انجام شد"
    }
}

فهرست دفترچه‌های تلفن POST

POST https://api-payamak.com/api/v3/rest/my/phonebook

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

پارامتر نوع اجباری توضیح
nameStringاختیاریفیلتر بر اساس نام دفترچه
📤 مثال درخواست
{
    "name": "مشتریان"
}
📤 مثال پاسخ
{
    "return": {
        "status": 200,
        "message": "لیست دفترچه‌ها"
    },
    "entries": [
        {
            "book_id": 123,
            "uname": "user",
            "title": "مشتریان",
            "count": 45
        }
    ]
}

شماره‌های دفترچه POST

POST https://api-payamak.com/api/v3/rest/phonebook/number

دریافت لیست شماره‌های یک دفترچه تلفن.

پارامتر نوع اجباری توضیح
book_idIntegerاجباریشناسه دفترچه
📤 مثال درخواست
{
    "book_id": 123
}

ایجاد دفترچه تلفن POST

POST https://api-payamak.com/api/v3/rest/phonebook/new

ایجاد دفترچه تلفن جدید با لیست شماره‌ها.

پارامتر نوع اجباری توضیح
nameStringاجباریعنوان دفترچه (یکتا برای هر کاربر)
numbersArray of Stringاجباریلیست شماره‌های موبایل (حداقل یک شماره)
flagStringاجباریبرچسب یکتا (مثلاً "vip" یا "customers")
📤 مثال درخواست
{
    "name": "مشتریان ویژه",
    "numbers": ["09123456789", "09123456788"],
    "flag": "vip_customers"
}

حذف دفترچه تلفن DELETE

DELETE https://api-payamak.com/api/v3/rest/phonebook/delete

حذف یک دفترچه تلفن و تمام شماره‌های موجود در آن.

پارامتر نوع اجباری توضیح
book_idIntegerاجباریشناسه دفترچه
📤 مثال درخواست
{
    "book_id": 123
}

افزودن شماره به دفترچه POST

POST https://api-payamak.com/api/v3/rest/phonebook/number/add

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

پارامتر نوع اجباری توضیح
book_idIntegerاجباریشناسه دفترچه
numbersArray of Stringاجباریلیست شماره‌های موبایل
flagStringاختیاریبرچسب (کاربردی ندارد)
📤 مثال درخواست
{
    "book_id": 123,
    "numbers": ["09123456789", "09123456788"]
}

حذف شماره از دفترچه DELETE

DELETE https://api-payamak.com/api/v3/rest/phonebook/number/delete

حذف یک یا چند شماره موبایل از دفترچه تلفن.

پارامتر نوع اجباری توضیح
book_idIntegerاجباریشناسه دفترچه
numbersArray of Stringاجباریلیست شماره‌های موبایل برای حذف
flagStringاختیاریبرچسب (کاربردی ندارد)
📤 مثال درخواست
{
    "book_id": 123,
    "numbers": ["09123456789", "09123456788"]
}

لیست سیاه POST

POST https://api-payamak.com/api/v3/rest/line/blocked/list

دریافت لیست شماره‌های مسدود شده برای یک خط.

پارامتر نوع اجباری توضیح
numberStringاجباریشماره خط
startdateUnixTimeاختیاریتاریخ شروع
pageIntegerاختیاریشماره صفحه
pagesizeIntegerاختیاریتعداد در هر صفحه
📤 مثال درخواست
{
    "number": "1000xxxx",
    "page": 1,
    "pagesize": 200
}
📤 مثال پاسخ
{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "number": "1000xxxx",
            "to": "09123456789",
            "user": "username",
            "setter": "system"
        }
    ],
    "current": {
        "totalcount": "1",
        "currentpage": "1",
        "totalpages": "1",
        "pagesize": "200"
    }
}

افزودن به لیست سیاه POST

POST https://api-payamak.com/api/v3/rest/line/blocked/add

افزودن یک یا چند شماره موبایل به لیست سیاه یک خط مشخص (حداکثر ۲۰۰ شماره در هر فراخوانی).

پارامتر نوع اجباری توضیح
numberStringاجباریشماره خط
toArray of Stringاجباریشماره موبایل(های) مورد نظر برای مسدودسازی
📤 مثال درخواست
{
    "number": "21xxxxxxxx",
    "to": ["09123456789", "09123456789"]
}
📤 مثال پاسخ
{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "number": "21xxxxxxxx",
            "to": "+989123456789",
            "status": "افزوده شد"
        },
        {
            "number": "21xxxxxxxx",
            "to": "+989123456789",
            "status": "تکراری"
        }
    ]
}

حذف از لیست سیاه POST

POST https://api-payamak.com/api/v3/rest/line/blocked/remove

حذف یک شماره موبایل از لیست سیاه یک خط مشخص.

پارامتر نوع اجباری توضیح
numberStringاجباریشماره خط
toStringاجباریشماره موبایل برای حذف
📤 مثال درخواست
{
    "number": "21xxxxxxxx",
    "to": "09123456789"
}
📤 مثال پاسخ
{
    "return": {
        "status": 200,
        "message": "شماره با موفقیت از لیست سیاه حذف شد"
    }
}

بررسی وجود در لیست سیاه POST

POST https://api-payamak.com/api/v3/rest/line/blocked/exists

بررسی اینکه آیا یک شماره در لیست سیاه خط مورد نظر وجود دارد یا خیر.

پارامتر نوع اجباری توضیح
numberStringاجباریشماره خط
toArray of Stringاجباریشماره موبایل(ها)
📤 مثال درخواست
{
    "number": "1000xxxx",
    "to": ["09123456789"]
}
📤 مثال پاسخ
{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "number": "1000xxxx",
            "to": "09123456789",
            "status": "فعال"
        }
    ]
}

کدهای برگشتی

وضعیت‌های کاربر

این کدها در پاسخ وب‌سرویس‌هایی که جزئیات حساب کاربری را برمی‌گردانند برگشت داده می‌شوند.

  • 0 - کاربر در وضعیت فعال قرار دارد.
  • 1 - کاربر مورد بررسی یافت نشد.
  • 2 - کاربر آزمایشی (جهت تست وب‌سرویس).
  • 3 - کاربر قفل شده است.
  • 4 - عضویت کاربر منقضی شده است.
  • 5 - کاربر هنوز تأیید نشده است.
  • 6 - دسترسی به وب‌سرویس برای کاربر تعریف نشده است.

وضعیت‌های ثبت کاربر جدید

  • 0 - ثبت‌نام با موفقیت انجام شد.
  • 10 - نام کاربری نامعتبر است.
  • 11 - شماره موبایل نامعتبر است.
  • 12 - کد ملی نامعتبر است.
  • 13 - ایمیل نامعتبر است.
  • 14 - مدیر کاربر دسترسی کافی ندارد.
  • 15 - نام کاربری قبلاً ثبت شده است.
  • 16 - پکیج درخواستی اشتباه است.
  • 17 - رمز عبور و تکرار آن هماهنگ نیست.
  • 18 - محدودیت ثبت‌نام (بیش از ۲ کاربر در روز).
  • 19 - کد ملی نامعتبر است.

وضعیت‌های ارسال پیامک

  • 0 - ارسال با موفقیت انجام شد.
  • 21 - تعداد گیرنده‌ها از حد مجاز بیشتر است.
  • 22 - اعتبار کاربر کافی نیست.
  • 23 - شماره فرستنده نامعتبر است.
  • 24 - متن پیام خالی است.
  • 25 - هیچ گیرنده‌ای انتخاب نشده است.
  • 26 - زمان ارسال اشتباه تنظیم شده است.
  • 27 - خطای نامشخص در ارسال (اپراتور).
  • 28 - داده‌های ارسالی مغایرت دارد.
  • 29 - الگوی انتخاب‌شده فعال نیست.

وضعیت گزارش‌های پیامکی

  • 0 - گزارش با موفقیت ایجاد شد.
  • 30 - هیچ پیامکی انتخاب نشده است.
  • 31 - هیچ گزارشی موجود نیست.
  • 32 - تعداد شناسه‌ها از حد مجاز فراتر رفته است.

وضعیت دلیوری (رسید) پیامک

  • 0 - ارسال شده به مخابرات (گزارش از اپراتور دریافت نشده).
  • 1 - ارسال شده به مخابرات.
  • 2 - نرسیده به مخابرات.
  • 3 - رسیده به مخابرات.
  • 4 - رسیده به گوشی.
  • 5 - نرسیده به گوشی.
  • 6 - برگشتی.
  • 14 - کد وضعیت نامعتبر است (شناسه نامعتبر).

وضعیت دفترچه تلفن

  • 0 - عملیات با موفقیت انجام شد.
  • 40 - رکوردی با این اطلاعات وجود ندارد.
  • 41 - دفترچه تلفن با این اطلاعات قبلاً وجود دارد.
  • 42 - شماره‌ای ارسال نشده است.
  • 43 - عملیات شکست خورد.
  • 44 - فیلد flag خالی ارسال شده است.
  • 45 - flag تکراری است.

سایر کدهای وضعیت

  • 1000 - اشکال در پایگاه داده.
  • 2000 - اشکال در سرور.

مستندات وب سرویس REST پیامکی پیشرو پیامک - نسخه 3.0

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

سبد خرید

سبد خرید شما خالی است.

محصولات مورد نظر خود را به سبد اضافه کنید.

فروشگاه