شمارش پیامک‌های ارسالی

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

تعداد پیامک‌های ارسال‌شده حساب کاربری را در یک بازه زمانی برمی‌گرداند: مجموع تعداد پیام‌ها (sumcount)، مجموع بخش‌ها/پارت‌های پیامک (sumpart) و هزینه کل (cost).

پارامتر startdate اجباری است و باید timestamp یونیکس بر حسب ثانیه باشد. اگر enddate ارسال نشود، به‌صورت خودکار برابر startdate + 86400 (۲۴ ساعت بعد) در نظر گرفته می‌شود. startdate باید کوچک‌تر از enddate باشد و نمی‌تواند مربوط به بیش از ۶۰ روز گذشته باشد؛ در غیر این صورت خطای ۴۱۷ برگردانده می‌شود.

با پارامتر اختیاری status می‌توان فقط پیام‌هایی را شمرد که آخرین وضعیت ثبت‌شده‌شان در سامانه گزارش‌گیری برابر همان وضعیت است. پیام‌هایی که هنوز هیچ رویدادی برایشان ثبت نشده، تنها زمانی شمرده می‌شوند که status برابر ۱ یا ۲ (در صف ارسال / زمان‌بندی‌شده) باشد. مقدار cost به ریال برگردانده می‌شود (هزینه ذخیره‌شده به تومان، ضربدر ۱۰).

همهٔ پارامترها از query string خوانده می‌شوند (ctx.Query)، بنابراین حتی در فراخوانی با متد POST نیز باید در انتهای URL قرار بگیرند، نه در بدنهٔ درخواست. این سرویس هیچ محدودیتی روی تعداد رکوردهای بررسی‌شده اعمال نمی‌کند و پارامتر sender را نادیده می‌گیرد.

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

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

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

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

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

نام	نوع	الزامی	توضیح
`startdate`*	integer	الزامی	زمان شروع بازه به‌صورت timestamp یونیکس (ثانیه). اجباری است و نمی‌تواند مربوط به بیش از ۶۰ روز گذشته باشد. — زمان شروع بازه به‌صورت timestamp یونیکس (ثانیه). اجباری است و نمی‌تواند مربوط به بیش از ۶۰ روز گذشته باشد. محدودیت: باید عدد صحیح باشد؛ باید کوچک‌تر از enddate باشد؛ باید بزرگ‌تر یا مساوی (اکنون − ۶۰ روز) باشد نمونه`1757000000`
`enddate`	integer	اختیاری	زمان پایان بازه به‌صورت timestamp یونیکس (ثانیه). در صورت ارسال نشدن، برابر `startdate + 86400` در نظر گرفته می‌شود. — زمان پایان بازه به‌صورت timestamp یونیکس (ثانیه). در صورت ارسال نشدن، برابر `startdate + 86400` در نظر گرفته می‌شود. محدودیت: باید عدد صحیح و بزرگ‌تر از startdate باشد پیش‌فرض`startdate + 86400`نمونه`1757086400`
`status`	integer	اختیاری	فیلتر وضعیت پیام. تنها مقادیر ۱ (در صف ارسال)، ۲ (زمان‌بندی‌شده)، ۴ (ارسال‌شده به مخابرات)، ۶ (خطا در ارسال)، ۱۰ (رسیده به گیرنده)، ۱۱ (مشکل در رسیدن پیام) و ۱۴ (بلاک شده) پذیرفته می‌شوند؛ هر مقدار دیگری خطای ۴۰۰ می‌دهد. مقادیر ۱ و ۲ هر دو به وضعیت «در صف ارسال» نگاشت می‌شوند. در صورت ارسال نشدن، همهٔ پیام‌های بازه شمرده می‌شوند. — فیلتر وضعیت پیام. تنها مقادیر ۱ (در صف ارسال)، ۲ (زمان‌بندی‌شده)، ۴ (ارسال‌شده به مخابرات)، ۶ (خطا در ارسال)، ۱۰ (رسیده به گیرنده)، ۱۱ (مشکل در رسیدن پیام) و ۱۴ (بلاک شده) پذیرفته می‌شوند؛ هر مقدار دیگری خطای ۴۰۰ می‌دهد. مقادیر ۱ و ۲ هر دو به وضعیت «در صف ارسال» نگاشت می‌شوند. در صورت ارسال نشدن، همهٔ پیام‌های بازه شمرده می‌شوند. محدودیت: باید عددی در بازهٔ uint8 و یکی از مقادیر مجاز بالا باشد مقادیر مجاز`1246101114`نمونه`10`

پاسخ‌ها

ساختار پاسخ

نام	نوع	الزامی	توضیح
`return`	ApiStatus	اختیاری	وضعیت پاسخ. مقدار `status` با کد وضعیت HTTP پاسخ یکسان است.
`status`*	integer	الزامی	کد وضعیت — همان کد وضعیت HTTP پاسخ. نمونه`200`
`message`*	string	الزامی	پیام فارسی قابل نمایش به کاربر. نمونه`درخواست تایید شد.`
`entries`	object	اختیاری	ساختار پاسخ در کد سرویس تعریف نشده است.

نمونهٔ پاسخ

{
  "return": {
    "status": 200,
    "message": "درخواست تایید شد."
  },
  "entries": {
    "startdate": 1757000000,
    "enddate": 1757086400,
    "sumpart": 128,
    "sumcount": 97,
    "cost": 1940
  }
}