گزارش پیامک‌های ارسالی در یک بازه زمانی

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

لیست پیامک‌های ارسالی حساب را در یک بازه‌ی زمانی مشخص برمی‌گرداند. startdate اجباری و به‌صورت timestamp یونیکس (ثانیه) است و نباید بیش از ۶۰ روز قبل باشد؛ اگر enddate داده نشود، به‌طور خودکار برابر startdate + 86400 (۲۴ ساعت بعد) در نظر گرفته می‌شود و در هر حال باید بزرگ‌تر از startdate باشد. با پارامتر اختیاری sender می‌توانید نتایج را به یک سرشماره‌ی اختصاصی متعلق به حساب خود محدود کنید. نتایج بر اساس تاریخ نزولی مرتب می‌شوند و تعداد رکوردهای بازگشتی همیشه حداکثر ۵۰۰ است (این اندپوینت پارامتر صفحه‌بندی ندارد). پارامترها در هر دو روش GET و POST از query string خوانده می‌شوند.

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

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

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

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

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

نام	نوع	الزامی	توضیح
`startdate`*	integer	الزامی	زمان شروع بازه‌ی گزارش‌گیری به‌صورت timestamp یونیکس. — زمان شروع بازه‌ی گزارش‌گیری به‌صورت timestamp یونیکس. محدودیت: عدد صحیح ۶۴ بیتی؛ باید کوچک‌تر از enddate باشد و نباید قدیمی‌تر از ۶۰ روز گذشته باشد (startDate >= now - 60243600). در غیر این صورت خطای 417. نمونه`1757059200`
`enddate`	integer	اختیاری	زمان پایان بازه‌ی گزارش‌گیری. در صورت ارسال نشدن، ۲۴ ساعت پس از startdate در نظر گرفته می‌شود. — زمان پایان بازه‌ی گزارش‌گیری. در صورت ارسال نشدن، ۲۴ ساعت پس از startdate در نظر گرفته می‌شود. محدودیت: عدد صحیح ۶۴ بیتی و اکیداً بزرگ‌تر از startdate؛ در غیر این صورت خطای 417. برای این پارامتر سقف بالایی بررسی نمی‌شود. پیش‌فرض`startdate + 86400`نمونه`1757145600`
`sender`	string	اختیاری	سرشماره‌ای که می‌خواهید گزارش فقط برای آن برگردانده شود. — سرشماره‌ای که می‌خواهید گزارش فقط برای آن برگردانده شود. محدودیت: اگر مقدار داده شود باید یکی از خطوط حساب شما و از نوع اختصاصی (private) باشد؛ در غیر این صورت خطای 412. اگر خالی یا ارسال‌نشده باشد، فیلتر سرشماره اعمال نمی‌شود. نمونه`3000505`

پاسخ‌ها

ساختار پاسخ

نام	نوع	الزامی	توضیح
`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": 8792350,
      "status": 10,
      "statustext": "رسیده به گیرنده",
      "message": "سفارش شما ثبت شد.",
      "sender": "3000505",
      "receptor": "09121234567",
      "date": 1757142000,
      "cost": 1200
    },
    {
      "messageid": 8792349,
      "status": 6,
      "statustext": "خطا در ارسال پیام به سرشماره مشخص شده",
      "message": "سفارش شما ثبت شد.",
      "sender": "3000505",
      "receptor": "09351234567",
      "date": 1757141900,
      "cost": 1200
    }
  ]
}