استعلام وضعیت ارسال پیامک‌ها

وضعیت تحویل مجموعه‌ای از پیامک‌ها را بر اساس messageid برمی‌گرداند. شناسه‌های تکراری پیش از پردازش حذف می‌شوند و پس از حذف تکرار، حداکثر ۱۰۰۰ شناسه در هر فراخوانی مجاز است. فقط پیام‌های متعلق به حساب احرازهویت‌شده بازیابی می‌شوند؛ شناسه‌ای که متعلق به حساب شما نباشد یا وجود نداشته باشد، با وضعیت ۱۰۰ «شناسه پیامک نامعتبر است» برمی‌گردد و پیامی که هنوز رویدادی برایش ثبت نشده، وضعیت ۱ «در صف ارسال» می‌گیرد. ترتیب و تعداد اعضای entries دقیقاً مطابق فهرست شناسه‌های ارسالی (پس از حذف تکرار) است.

احراز هویت

نوع احراز هویتتوکن BearerbearerAuth

کلید API را در هدر Authorization با پیشوند Bearer بفرستید:

``` Authorization: Bearer YOURAPIKEY ```

این روش برای سرویس‌های نسخهٔ ۲، نسخهٔ ۳ و بارگذاری فایل به کار می‌رود. سرویس‌های نسخهٔ ۱ کلید را از مسیر URL می‌گیرند و هدری نمی‌خواهند.

هدر لازم

Authorization: Bearer YOUR_ACCESS_TOKEN

کلید خود را کجا پیدا کنم؟

اطلاعات ورود را از پنل کاربری خود بگیرید و توکن را فقط روی سرور و در یک متغیر محیطی نگه دارید؛ هرگز آن را در کد سمت کاربر قرار ندهید.

بدنهٔ درخواست

application/jsonالزامی

بدنه JSON شامل فهرست شناسه پیامک‌ها.

نام	نوع	الزامی	توضیح
`messageids`*	array<string>	الزامی	فهرست شناسه‌های پیامک (همان `messageid` بازگشتی از APIهای ارسال). مقادیر تکراری حذف می‌شوند و بیش از ۱۰۰۰ شناسهٔ یکتا خطای ۴۱۴ می‌دهد. محدودیت: حداقل ۱ عضو؛ پس از حذف موارد تکراری حداکثر ۱۰۰۰ عضو

نمونهٔ درخواست

{
  "messageids": [
    18392011,
    18392012,
    999999999
  ]
}

پاسخ‌ها

ساختار پاسخ

نام	نوع	الزامی	توضیح
`return`	ApiStatus	اختیاری	وضعیت پاسخ. مقدار `status` با کد وضعیت HTTP پاسخ یکسان است.
`status`*	integer	الزامی	کد وضعیت — همان کد وضعیت HTTP پاسخ. نمونه`200`
`message`*	string	الزامی	پیام فارسی قابل نمایش به کاربر. نمونه`درخواست تایید شد.`
`entries`	array<GetStatusResponse>	اختیاری
`messageid`	integer· int64	اختیاری	شناسهٔ پیامک. نمونه`18392011`قالب`int64`
`status`	integer	اختیاری	وضعیت پیامک: ۰ دریافت کننده نامعتبر · ۱ در صف ارسال · ۲ زمان‌بندی شده · ۴ ارسال شده به مخابرات · ۶ خطا در ارسال · ۱۰ رسیده به گیرنده · ۱۱ مشکل در رسیدن پیام · ۱۳ لغو شده · ۱۴ بلاک شده · ۱۵ شماره تکراری · ۱۰۰ شناسه نامعتبر. مقادیر مجاز`012461011131415100`نمونه`1`
`statustext`	string	اختیاری	متن فارسی وضعیت. نمونه`رسیده به گیرنده`

نمونهٔ پاسخ

{
  "return": {
    "status": 200,
    "message": "درخواست تایید شد."
  },
  "entries": [
    {
      "messageid": 18392011,
      "status": 10,
      "statustext": "رسیده به گیرنده"
    },
    {
      "messageid": 18392012,
      "status": 1,
      "statustext": "در صف ارسال"
    },
    {
      "messageid": 999999999,
      "status": 100,
      "statustext": "شناسه پیامک نامعتبر است"
    }
  ]
}

curl --request POST \ --url 'https://sms.najva.com/v2/sms/status' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --data '{ "messageids": [ 18392011, 18392012, 999999999 ] }'

{ "return": { "status": 200, "message": "درخواست تایید شد." }, "entries": [ { "messageid": 18392011, "status": 10, "statustext": "رسیده به گیرنده" }, { "messageid": 18392012, "status": 1, "statustext": "در صف ارسال" }, { "messageid": 999999999, "status": 100, "statustext": "شناسه پیامک نامعتبر است" } ] }