مقدمه
این مستندات راهنمای کامل متدهای GET وبسرویس پیامک سامانه پیامک (نسخه ۴) است. تمام درخواستها از طریق GET انجام میشوند و پاسخها به صورت JSON بازگردانده میشوند.
آدرس پایه
https://api-payamak.com/api/v4/{API-KEY}/
کلید API را در مسیر قرار دهید یا بهصورت پارامتر کوئری ?apikey=... یا ?api_key=... ارسال کنید.
- برای راحتی کار، تمام نمونهها از پارامترهای کوئری استفاده میکنند. حتماً
{API-KEY}را با کلید خود جایگزین کنید. - پاسخها همواره شامل دو بخش اصلی
return(وضعیت و پیام) وdataیاentries(دادههای اصلی) هستند.
احراز هویت
برای احراز هویت، API-KEY خود را به یکی از روشهای زیر ارسال کنید:
?apikey=YOUR_API_KEY?api_key=YOUR_API_KEY
یا کلید را در مسیر قرار دهید:
https://api-payamak.com/api/v4/{API-KEY}/sms/send.json
در این مستندات از روش پارامتر کوئری (
?api_key=...) استفاده شده است.
ارسال پیامک GET
GET
https://api-payamak.com/api/v4/{API-KEY}/sms/send.json?from=21xxxxxxxx&recipients=09123456789&message=سلام&type=0
ارسال پیامک به یک یا چند گیرنده (حداکثر ۲۰۰ گیرنده در هر فراخوانی).
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| from | String | اجباری | شماره فرستنده |
| recipients | String | اجباری | شماره گیرنده (چندتا با کاما جدا کنید) |
| message | String | اجباری | متن پیام (حداکثر ۹۰۰ کاراکتر) |
| type | Integer | اختیاری | نوع پیام (۰=معمولی، ۱=فلش) – پیشفرض ۰ |
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "پیام با موفقیت در صف ارسال قرار گرفت"
},
"data": {
"messageid": 8792343,
"message": "سلام",
"state": 1,
"from": "+9821xxxxxxxx",
"to": "+989123456789",
"date": 1786619709
}
}
در صورت ارسال پیام به بیش از ۲۰۰ گیرنده، خطای
414 بازگردانده میشود.
ارسال گروهی (چند پیام) GET
GET
https://api-payamak.com/api/v4/{API-KEY}/sms/multi.json?fromArray=21xxxx,21xxxx&recipients=09123456789,09123456789&messageArray=پیام,پیام&typeArray=0,0
ارسال چندین پیام متفاوت به گیرندههای مختلف با شمارههای فرستنده متفاوت. تعداد آرایهها باید برابر باشد.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| fromArray | String | اجباری | شمارههای فرستنده (با کاما جدا کنید) |
| recipients | String | اجباری | شمارههای گیرنده (با کاما جدا کنید) |
| messageArray | String | اجباری | متن پیامها (با کاما جدا کنید) |
| typeArray | String | اجباری | نوع هر پیام (۰ یا ۱، با کاما جدا کنید) |
تعداد آرایهها باید برابر باشد. در صورت عدم برابری، خطای
419 بازگردانده میشود.
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "پیامهای گروهی با موفقیت در صف ارسال قرار گرفتند"
},
"entries": [
{
"index": 0,
"messageid": 8792343,
"message": "پیام",
"state": 1,
"from": "+9821xxxx",
"to": "+989123456789",
"date": 1786619709
}
]
}کنترل وضعیت پیامک GET
GET
https://api-payamak.com/api/v4/{API-KEY}/sms/status.json?messageid=8792343,8792344
دریافت وضعیت پیامهای ارسال شده (حداکثر ۵۰ شناسه در هر فراخوانی).
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| messageid | String | اجباری | شناسههای پیام (با کاما جدا کنید) |
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "وضعیت پیامها"
},
"entries": [
{
"messageid": 8792343,
"from": "+9821000xxx",
"number": "09123456789",
"state": 10,
"status": "رسیده به گیرنده"
}
]
}جزئیات پیامک GET
GET
https://api-payamak.com/api/v4/{API-KEY}/sms/select.json?messageid=8792343
مشابه Status اما با اطلاعات کاملتر (متن پیام، شماره فرستنده، تاریخ).
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| messageid | String | اجباری | شناسه پیام (چندتا با کاما) |
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "جزئیات پیام"
},
"entries": [
{
"messageid": 8792343,
"message": "خدمات پیام کوتاه",
"number": "09123456789",
"state": 10,
"status": "رسیده به گیرنده",
"from": "1000xxxx",
"date": 1786619709
}
]
}لیست ارسالها GET
GET
https://api-payamak.com/api/v4/{API-KEY}/sms/selectoutbox.json?startdate=1759533200&enddate=1809619600
دریافت لیست پیامهای ارسال شده در بازه زمانی (حداکثر ۱ روز).
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| startdate | UnixTime | اجباری | تاریخ شروع |
| enddate | UnixTime | اجباری | تاریخ پایان |
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "لیست ارسالها"
},
"entries": [
{
"messageid": 8792343,
"message": "test",
"number": "09123456789",
"from": "1000xxxx",
"state": 10,
"status": "رسیده به گیرنده",
"date": 1409533200
}
]
}آخرین وضعیت پیام GET
GET
https://api-payamak.com/api/v4/{API-KEY}/sms/latest.json
دریافت آخرین پیام ارسالشده (آخرین رکورد بر اساس شناسه) همراه با جزئیات کامل. این متد نیازی به پارامتر ورودی ندارد.
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "آخرین وضعیت پیام"
},
"data": {
"messageid": 8792340,
"message": "خدمات پیام کوتاه",
"recipients_count": 2,
"recipients": ["+989123456789", "+989123456789"],
"from": "21xxxxxxxx",
"state": 10,
"date": 1786619709
}
}
در صورت عدم وجود پیام، خطای
400 با پیام "هیچ پیامکی یافت نشد" بازگردانده میشود.
آخرین ارسالها GET
GET
https://api-payamak.com/api/v4/{API-KEY}/sms/latestoutbox.json?pagesize=50
دریافت آخرین پیامهای ارسال شده (حداکثر ۲۰۰ مورد).
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| pagesize | Integer | اختیاری | تعداد نتایج (پیشفرض ۲۰۰) |
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "تایید شد"
},
"entries": [
{
"messageid": 8792343,
"from": "1000xxxx",
"to": "09123456789",
"message": "test",
"state": 10,
"status": "رسیده به گیرنده",
"date": 1409533200
}
]
}تعداد ارسالها GET
GET
https://api-payamak.com/api/v4/{API-KEY}/sms/countoutbox.json?startdate=1409533200&enddate=1409619600
تعداد، پارتیشنها و هزینه کل ارسالها در بازه زمانی.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| startdate | UnixTime | اجباری | تاریخ شروع |
| enddate | UnixTime | اجباری | تاریخ پایان |
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "تایید شد"
},
"data": {
"startdate": 1759533200,
"enddate": 1789619600,
"sumpart": 10,
"sumcount": 10,
"cost": 50
}
}تعداد دریافتها GET
GET
https://api-payamak.com/api/v4/{API-KEY}/sms/countinbox.json?startdate=1409533200&enddate=1409619600&number=1000xxxx&isread=0
تعداد پیامهای دریافت شده با فیلتر شماره و وضعیت خواندهشدن.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| startdate | UnixTime | اجباری | تاریخ شروع |
| enddate | UnixTime | اجباری | تاریخ پایان |
| number | String | اختیاری | شماره خط گیرنده |
| isread | Integer | اختیاری | ۰=نخوانده، ۱=خوانده |
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "تایید شد"
},
"data": {
"startdate": 1759533200,
"enddate": 1789619600,
"isread": 0,
"count": 5
}
}دریافت پیامهای دریافتی GET
GET
https://api-payamak.com/api/v4/{API-KEY}/sms/inbox.json?count=50&offset=0
دریافت لیست پیامهای دریافتی کاربر با قابلیت تعیین تعداد و offset (صفحهبندی ساده).
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| count | Integer | اختیاری | تعداد پیامهای مورد نظر (پیشفرض ۵۰) |
| offset | Integer | اختیاری | میزان offset (پیشفرض ۰) |
این متد فقط سه فیلد
message، to و from را بازمیگرداند.
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "لیست پیامهای دریافتی"
},
"entries": [
{
"message": "خدمات پیام کوتاه",
"to": "1000xxxx",
"from": "09123456789",
"date": 1789619600
}
]
}دریافت پیامک (صفحهبندی) GET
GET
https://api-payamak.com/api/v4/{API-KEY}/sms/inboxpaged.json?number=1000xxxx&isread=0&page=1&pagesize=200
دریافت پیامهای دریافتی با صفحهبندی (تا ۵۰۰ مورد در هر صفحه).
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| number | String | اختیاری | شماره خط |
| isread | Integer | اختیاری | ۰=نخوانده، ۱=خوانده |
| page | Integer | اختیاری | شماره صفحه (پیشفرض ۱) |
| pagesize | Integer | اختیاری | تعداد در هر صفحه (پیشفرض ۲۰۰، حداکثر ۵۰۰) |
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "تایید شد"
},
"entries": [
{
"messageid": 35850015,
"message": "خدمات پیام کوتاه",
"from": "09123456789",
"to": "1000xxxx",
"date": 1357206241
}
],
"current": {
"totalcount": "1",
"currentpage": "1",
"totalpages": "1",
"pagesize": "200"
}
}دریافت پیامک GET
GET
https://api-payamak.com/api/v4/{API-KEY}/sms/receive.json?number=1000xxxx&isread=0
دریافت حداکثر ۵۰ پیام خواندهنشده و بروزرسانی خودکار وضعیت به خواندهشده.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| number | String | اختیاری | شماره خط |
| isread | Integer | اختیاری | ۰=نخوانده (پیشفرض)، ۱=خوانده |
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "تایید شد"
},
"entries": [
{
"messageid": 35850015,
"message": "خدمات پیام کوتاه",
"from": "09123456789",
"to": "1000xxxx",
"date": 1757206241
}
]
}کنترل وضعیت با شماره GET
GET
https://api-payamak.com/api/v4/{API-KEY}/sms/statusbynumber.json?number=09123456789&startdate=1785677000&pagesize=50
دریافت وضعیت پیامهای ارسال شده به یک شماره خاص از تاریخ شروع تا حال.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| number | String | اجباری | شماره موبایل گیرنده |
| startdate | UnixTime | اجباری | تاریخ شروع |
| pagesize | Integer | اختیاری | تعداد نتایج (پیشفرض ۵۰، حداکثر ۵۰) |
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "تایید شد"
},
"entries": [
{
"messageid": 8792343,
"message": "خدمات پیام کوتاه",
"to": "09123456789",
"status": 10,
"statustext": "رسیده به گیرنده",
"date": 1785677000
}
]
}اعتبار کاربر GET
GET
https://api-payamak.com/api/v4/{API-KEY}/user/credit.json
دریافت اعتبار باقیمانده حساب کاربری (ریال).
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "اعتبار کاربر"
},
"data": {
"credit": 1500000
}
}اطلاعات کاربر GET
GET
https://api-payamak.com/api/v4/{API-KEY}/user/details.json
دریافت مشخصات کامل کاربر شامل نام، شرکت، اعتبار، تعرفه و ...
📤 مثال پاسخ
{
"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": "نماینده"
}
}ثبتنام کاربر GET
GET
https://api-payamak.com/api/v4/{API-KEY}/user/register.json?uname=amirreza&passwd=123456&passwd_repeat=123456&parent=admin&mobile=09121234567&melli_code=1234567890&package=1&reseller=1
ایجاد حساب کاربری جدید در سامانه. (هر مدیر در روز حداکثر ۲ کاربر ثبتنام میکند.)
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| uname | String | اجباری | نام کاربری (فقط حروف و اعداد انگلیسی) |
| passwd | String | اجباری | رمز عبور |
| passwd_repeat | String | اجباری | تکرار رمز عبور |
| parent | String | اجباری | نام کاربری مدیر |
| mobile | String | اجباری | شماره موبایل (۰۹۱۲... یا ۹۸۹۱۲...) |
| melli_code | String | اجباری | کد ملی ۱۰ رقمی |
| package | Integer | اجباری | شناسه پکیج (بسته تعرفهای) |
| reseller | Integer | اجباری | وضعیت نمایندگی (۰=نیست، ۱=هست) |
در صورت ارسال نام کاربری تکراری یا شماره موبایل نامعتبر، خطای مناسب بازگردانده میشود.
📤 مثال پاسخ موفق
{
"return": {
"status": 200,
"message": "ثبت نام با موفقیت انجام شد"
}
}
📤 مثال پاسخ خطا (محدودیت روزانه)
{
"return": {
"status": 429,
"message": "امکان ثبتنام بیش از ۲ کاربر در یک روز برای این مدیر وجود ندارد"
}
}فهرست دفترچههای تلفن GET
GET
https://api-payamak.com/api/v4/{API-KEY}/phonebook/list.json
دریافت لیست تمام دفترچههای تلفن کاربر.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| name | String | اختیاری | فیلتر بر اساس نام دفترچه |
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "لیست دفترچهها"
},
"entries": [
{
"book_id": 1,
"uname": "user",
"title": "مشتریان",
"count": 45
}
]
}شمارههای دفترچه GET
GET
https://api-payamak.com/api/v4/{API-KEY}/phonebook/numbers.json?bookId=123
دریافت لیست شمارههای یک دفترچه تلفن.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| bookId | Integer | اجباری | شناسه دفترچه |
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "شمارههای دفترچه"
},
"entries": [
{
"number_id": 1,
"number": "09123456789"
}
]
}لیست سیاه GET
GET
https://api-payamak.com/api/v4/{API-KEY}/line/blocked/list.json?number=1000xxxx&page=1&pagesize=200
دریافت لیست شمارههای مسدود شده برای یک خط.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| number | String | اجباری | شماره خط |
| startdate | UnixTime | اختیاری | تاریخ شروع |
| page | Integer | اختیاری | شماره صفحه |
| pagesize | Integer | اختیاری | تعداد در هر صفحه |
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "تایید شد"
},
"entries": [
{
"number": "1000xxxx",
"to": "09123456789",
"user": "username",
"setter": "system"
}
],
"current": {
"totalcount": "1",
"currentpage": "1",
"totalpages": "1",
"pagesize": "200"
}
}افزودن به لیست سیاه GET
GET
https://api-payamak.com/api/v4/{API-KEY}/line/blocked/add.json?number=21xxxxxxxx&to=09123456789,09123456789
افزودن یک یا چند شماره موبایل به لیست سیاه یک خط مشخص (حداکثر ۲۰۰ شماره در هر فراخوانی).
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| number | String | اجباری | شماره خط |
| to | String | اجباری | شماره موبایل(های) مورد نظر (با کاما جدا کنید) |
شمارههای تکراری با وضعیت
تکراری برگردانده میشوند.
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "تایید شد"
},
"entries": [
{
"number": "21xxxxxxxx",
"to": "+989123456789",
"status": "افزوده شد"
}
]
}
کدهای خطا:
400 – پارامترها ارسال نشدهاند، 401 – حساب غیرفعال.
حذف از لیست سیاه GET
GET
https://api-payamak.com/api/v4/{API-KEY}/line/blocked/remove.json?number=21xxxxxxxx&to=09123456789
حذف یک شماره موبایل از لیست سیاه یک خط مشخص.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| number | String | اجباری | شماره خط |
| to | String | اجباری | شماره موبایل برای حذف |
در صورت عدم وجود شماره، خطای
400 با پیام مناسب بازگردانده میشود.
📤 مثال پاسخ
{
"return": {
"status": 200,
"message": "شماره با موفقیت از لیست سیاه حذف شد"
}
}بررسی وجود در لیست سیاه GET
GET
https://api-payamak.com/api/v4/{API-KEY}/line/blocked/exists.json?number=1000xxxx&to=09123456789
بررسی اینکه آیا یک شماره در لیست سیاه خط مورد نظر وجود دارد یا خیر.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| number | String | اجباری | شماره خط |
| to | String | اجباری | شماره موبایل (چندتا با کاما) |
📤 مثال پاسخ
{
"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 پیامکی پیشرو پیامک - نسخه ۴ (فقط GET)