دریافت آخرین پیامک‌های ارسالی یک سرشماره

احراز هویت: این سرویس کلید API را از مسیر URL می‌خواند (/v1/{apiKey}/...) و هدر احراز هویتی ندارد. درخواست فقط از آی‌پی‌های وایت‌لیست‌شده پذیرفته می‌شود. به احراز هویت و وایت‌لیست IP نگاه کنید.

آخرین پیامک‌های ارسالی حساب را بدون محدودیت بازه‌ی زمانی و مرتب‌شده از جدید به قدیم برمی‌گرداند. برخلاف selectoutbox.json، در این اندپوینت پارامتر sender اجباری است و باید یکی از خطوط اختصاصی (private) حساب شما باشد؛ در غیر این صورت خطای ۴۱۲ برمی‌گردد. تعداد رکوردها با pagesize کنترل می‌شود که در صورت ارسال نشدن برابر بیشینه‌ی مجاز (۵۰۰) در نظر گرفته می‌شود. پارامترها در هر دو روش GET و POST از query string خوانده می‌شوند و مقدار cost بر حسب ریال است.

نکتهٔ مهم: تمام پارامترها از query string خوانده می‌شوند. این مسیر برای POST هم ثبت شده، ولی حتی در POST هم باید پارامترها در انتهای نشانی بیایند؛ بدنهٔ form-urlencoded یا JSON خوانده نمی‌شود.

این مسیر با متد GET هم ثبت شده و رفتار یکسانی دارد؛ در مستندات فقط شکل POST نشان داده شده است.

پارامترهای مسیر

نام	نوع	الزامی	توضیح
`apiKey`*	string	الزامی	کلید API حساب کاربری که به‌صورت بخشی از مسیر URL ارسال می‌شود. نمونه`3A6B4C2D1E0F9A8B7C6D5E4F`

پارامترهای کوئری

نام	نوع	الزامی	توضیح
`sender`*	string	الزامی	سرشماره‌ای که آخرین پیامک‌های ارسالی آن را می‌خواهید. — سرشماره‌ای که آخرین پیامک‌های ارسالی آن را می‌خواهید. محدودیت: باید یکی از خطوط حساب شما و از نوع اختصاصی (private) باشد؛ مقدار خالی یا خط عمومی/متعلق به دیگری خطای 412 می‌دهد. نمونه`3000505`
`pagesize`	integer	اختیاری	تعداد رکوردهای بازگشتی. در صورت ارسال نشدن، بیشینه‌ی مجاز اعمال می‌شود. — تعداد رکوردهای بازگشتی. در صورت ارسال نشدن، بیشینه‌ی مجاز اعمال می‌شود. محدودیت: عدد صحیح مثبت و حداکثر برابر REQUESTANDRESPONSE_LIMIT (پیش‌فرض 500)؛ مقدار غیرعددی، صفر، منفی یا بزرگ‌تر از سقف خطای 400 می‌دهد. پیش‌فرض`500`نمونه`50`

پاسخ‌ها

ساختار پاسخ

نام	نوع	الزامی	توضیح
`return`	ApiStatus	اختیاری	وضعیت پاسخ. مقدار `status` با کد وضعیت HTTP پاسخ یکسان است.
`status`*	integer	الزامی	کد وضعیت — همان کد وضعیت HTTP پاسخ. نمونه`200`
`message`*	string	الزامی	پیام فارسی قابل نمایش به کاربر. نمونه`درخواست تایید شد.`
`entries`	array<SelectMessageResponse>	اختیاری	جزئیات کامل یک پیامک (`dto.SelectMessageResponse`).
`messageid`	integer· int64	اختیاری	شناسهٔ پیامک. نمونه`18392011`قالب`int64`
`status`	integer	اختیاری	وضعیت پیامک: ۰ دریافت کننده نامعتبر · ۱ در صف ارسال · ۲ زمان‌بندی شده · ۴ ارسال شده به مخابرات · ۶ خطا در ارسال · ۱۰ رسیده به گیرنده · ۱۱ مشکل در رسیدن پیام · ۱۳ لغو شده · ۱۴ بلاک شده · ۱۵ شماره تکراری · ۱۰۰ شناسه نامعتبر. مقادیر مجاز`012461011131415100`نمونه`1`
`statustext`	string	اختیاری	متن فارسی وضعیت. نمونه`رسیده به گیرنده`
`message`	string	اختیاری	متن پیامک.
`sender`	string	اختیاری	سرشمارهٔ ارسال. نمونه`3000505`
`receptor`	string	اختیاری	شمارهٔ گیرنده. نمونه`09121234567`
`date`	integer· int64	اختیاری	زمان ارسال (unix، ثانیه). نمونه`1757145600`قالب`int64`
`cost`	number· float	اختیاری	هزینه به ریال. نمونه`700`قالب`float`

نمونهٔ پاسخ

{
  "return": {
    "status": 200,
    "message": "درخواست تایید شد."
  },
  "entries": [
    {
      "messageid": 8792351,
      "status": 4,
      "statustext": "ارسال شده به مخابرات",
      "message": "کد تایید شما: 78214",
      "sender": "3000505",
      "receptor": "09121234567",
      "date": 1757145900,
      "cost": 1200
    },
    {
      "messageid": 8792350,
      "status": 10,
      "statustext": "رسیده به گیرنده",
      "message": "سفارش شما ثبت شد.",
      "sender": "3000505",
      "receptor": "09351234567",
      "date": 1757142000,
      "cost": 1200
    }
  ]
}