دریافت جزئیات کامل پیامک‌ها با شناسه

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

جزئیات کامل یک یا چند پیامک ارسالی را با شناسه‌ی پیامک (messageid) برمی‌گرداند: متن پیام، سرشماره، گیرنده، زمان و هزینه، به‌علاوه‌ی وضعیت تحویل. ورودی رشته‌ای از شناسه‌های جداشده با کاما است، تکراری‌ها حذف می‌شوند و سقف هر فراخوانی ۵۰۰ شناسه‌ی یکتاست. پارامترها در هر دو روش GET و POST از query string خوانده می‌شوند. برای شناسه‌های ناموجود یا متعلق به حساب دیگر، وضعیت 100 برگردانده می‌شود و بقیه‌ی فیلدها مقدار پیش‌فرض (رشته‌ی خالی / صفر) دارند. مقدار cost بر حسب ریال است (مقدار تومانِ ذخیره‌شده در ۱۰ ضرب می‌شود).

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

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

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

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

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

نام	نوع	الزامی	توضیح
`messageid`*	string	الزامی	شناسه‌های پیامکی که می‌خواهید اطلاعات کامل آن‌ها را دریافت کنید. — شناسه‌های پیامکی که می‌خواهید اطلاعات کامل آن‌ها را دریافت کنید. محدودیت: هر عنصر باید uint64 معتبر باشد؛ پس از حذف تکراری‌ها حداکثر ۵۰۰ شناسه (REQUESTANDRESPONSE_LIMIT، پیش‌فرض 500). نمونه`8792343,8792344`

پاسخ‌ها

ساختار پاسخ

نام	نوع	الزامی	توضیح
`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": 8792343,
      "status": 10,
      "statustext": "رسیده به گیرنده",
      "message": "کد ورود شما: 45213",
      "sender": "3000505",
      "receptor": "09121234567",
      "date": 1757145600,
      "cost": 1200
    },
    {
      "messageid": 8792344,
      "status": 100,
      "statustext": "شناسه پیامک نامعتبر است",
      "message": "",
      "sender": "",
      "receptor": "",
      "date": 0,
      "cost": 0
    }
  ]
}