دریافت پیامک‌های وارده

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

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

پارامتر isread اجباری است و فقط مقادیر 0 یا 1 را می‌پذیرد. با isread=0 تنها پیام‌های جدیدتر از آخرین شناسهٔ خوانده‌شدهٔ آن خط برگردانده می‌شوند و پس از دریافت، نشانگر «آخرین پیام خوانده‌شده» به آخرین پیام همین پاسخ منتقل می‌شود؛ یعنی فراخوانی بعدی پیام‌های تکراری نمی‌دهد. با isread=1 پیام‌ها از ابتدا (بدون در نظر گرفتن نشانگر) برگردانده می‌شوند و نشانگر نیز جابه‌جا نمی‌شود.

پارامتر linenumber اختیاری است اما توصیه می‌شود همیشه ارسال شود: در صورت ارسال نشدن، تنها اولین خط فهرست خطوط حساب کاربری بررسی می‌شود. اگر ارسال شود، خط باید متعلق به حساب و اختصاصی (private) باشد وگرنه خطای ۴۱۲ برگردانده می‌شود. همهٔ پارامترها از query string خوانده می‌شوند و در فراخوانی POST نیز باید در URL باشند.

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

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

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

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

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

نام	نوع	الزامی	توضیح
`isread`*	integer	الزامی	اجباری. مقدار `0`: فقط پیام‌های خوانده‌نشده برگردانده و نشانگر خوانده‌شدن به‌روزرسانی می‌شود. مقدار `1`: پیام‌ها از ابتدا برگردانده می‌شوند و نشانگر تغییر نمی‌کند. ارسال نکردن آن یا هر مقدار خارج از {۰، ۱} خطای ۴۰۰ می‌دهد. — اجباری. مقدار `0`: فقط پیام‌های خوانده‌نشده برگردانده و نشانگر خوانده‌شدن به‌روزرسانی می‌شود. مقدار `1`: پیام‌ها از ابتدا برگردانده می‌شوند و نشانگر تغییر نمی‌کند. ارسال نکردن آن یا هر مقدار خارج از {۰، ۱} خطای ۴۰۰ می‌دهد. محدودیت: فقط 0 یا 1 مقادیر مجاز`01`نمونه`0`
`linenumber`	string	اختیاری	شمارهٔ خط اختصاصی که پیام‌های وارده‌اش خوانده می‌شود. در صورت ارسال نشدن، تنها اولین خط حساب کاربری استفاده می‌شود. خط ارسالی باید متعلق به حساب و اختصاصی (private) باشد. نمونه`9830007650`

پاسخ‌ها

ساختار پاسخ

نام	نوع	الزامی	توضیح
`return`	ApiStatus	اختیاری	وضعیت پاسخ. مقدار `status` با کد وضعیت HTTP پاسخ یکسان است.
`status`*	integer	الزامی	کد وضعیت — همان کد وضعیت HTTP پاسخ. نمونه`200`
`message`*	string	الزامی	پیام فارسی قابل نمایش به کاربر. نمونه`درخواست تایید شد.`
`entries`	array<IncomingMessage>	اختیاری	یک پیامک دریافتی (`dto.IncomingMessage`).
`messageid`	integer· int64	اختیاری	شناسهٔ پیامک دریافتی. نمونه`77001`قالب`int64`
`message`	string	اختیاری	متن پیامک دریافتی. نمونه`لغو`
`sender`	string	اختیاری	شمارهٔ فرستنده (کاربر نهایی). نمونه`09121234567`
`receptor`	string	اختیاری	سرشمارهٔ شما که پیامک روی آن دریافت شده. نمونه`3000505`
`date`	integer· int64	اختیاری	زمان دریافت (unix، ثانیه). نمونه`1757145600`قالب`int64`

نمونهٔ پاسخ

{
  "return": {
    "status": 200,
    "message": "درخواست تایید شد."
  },
  "entries": [
    {
      "messageid": 98217345,
      "message": "سلام، لطفا موجودی حساب من را ارسال کنید",
      "sender": "09121234567",
      "receptor": "9830007650",
      "date": 1757003412
    },
    {
      "messageid": 98217346,
      "message": "لغو11",
      "sender": "09351234567",
      "receptor": "9830007650",
      "date": 1757003890
    }
  ]
}