ارسال نظیربه‌نظیر (متن متفاوت برای هر گیرنده)

برای هر گیرنده یک متن اختصاصی ارسال می‌کند؛ همه پیام‌ها با یک سرشماره مشترک فرستاده می‌شوند. حداکثر ۱۰٬۰۰۰ پیام در هر فراخوانی مجاز است. شماره‌ها به قالب 09xxxxxxxxx نرمال‌سازی می‌شوند؛ رکوردهای با شماره نامعتبر و شماره‌های تکراری (اولین رخداد نگه داشته می‌شود) از ارسال کنار می‌روند ولی در پاسخ با وضعیت ۰ و ۱۵ گزارش می‌شوند و اگر هیچ رکورد معتبری نماند خطای ۴۱۱ برمی‌گردد. سرشماره باید مجوز can_send_api_campaign داشته باشد و اعتبار حساب برای مجموع هزینه بررسی می‌شود.

احراز هویت

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

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

``` Authorization: Bearer YOURAPIKEY ```

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

هدر لازم

Authorization: Bearer YOUR_ACCESS_TOKEN

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

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

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

application/jsonالزامی

بدنه JSON درخواست ارسال نظیربه‌نظیر. با `ctx.ShouldBindJSON` خوانده می‌شود.

نام	نوع	الزامی	توضیح
`sender`*	string	الزامی	سرشماره مشترک همه پیام‌های این درخواست. در صورت نامعتبر بودن، خطای ۴۱۲ برمی‌گردد. محدودیت: باید یکی از خطوط حساب کاربر با مجوز cansendapi_campaign باشد نمونه`3000505`
`messages`*	array<object>	الزامی	فهرست پیام‌ها؛ هر عضو یک جفت «گیرنده و متن» است. بیش از ۱۰٬۰۰۰ عضو خطای ۴۱۴ می‌دهد. محدودیت: حداکثر ۱۰٬۰۰۰ عضو. آرایهٔ خالی از اعتبارسنجی عبور می‌کند ولی چون هیچ گیرندهٔ معتبری ندارد با خطای ۴۱۱ رد می‌شود.
`message`*	string	الزامی	متن اختصاصی این گیرنده. برای خطوط پیامکی، عبارت «\nلغو۱۱» به‌طور خودکار به انتهای متن افزوده یا یکسان‌سازی می‌شود؛ برای خطوط پیام‌رسان (بله/روبیکا) این کار انجام نمی‌شود. محدودیت: حداقل ۱ کاراکتر نمونه`کد تخفیف شما: A1B2C3`
`receiver`*	string	الزامی	شماره گیرنده. به قالب `09xxxxxxxxx` نرمال می‌شود. شمارهٔ نامعتبر، تکراری یا خالی باعث خطای اعتبارسنجی نمی‌شود: آن عضو از ارسال کنار گذاشته و در `entries` با وضعیت ۰ (دریافت کننده نامعتبر) یا ۱۵ (شماره تکراری) گزارش می‌شود. تنها وقتی خطای ۴۱۱ برمی‌گردد که هیچ گیرندهٔ معتبری باقی نماند. محدودیت: مطابق الگوی ^((\+?98)\|0)?9[0-9]{9}$ — در غیر این صورت حذف می‌شود، نه رد درخواست نمونه`09121234567`
`file_id`	string	اختیاری	شناسه فایل بازگشتی از `POST /upload-file/bale`. باید متعلق به همان حساب باشد و ارائه‌دهنده آن با ارائه‌دهنده سرشماره یکی باشد، وگرنه خطای ۴۰۰ برمی‌گردد. محدودیت: حداکثر ۱۰۰ کاراکتر نمونه`3f2b7c1e-9a4d-4f1c-8b77-2c0f9e6a5d31`می‌تواند null باشد

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

{
  "sender": "3000505",
  "messages": [
    {
      "receiver": "09121234567",
      "message": "کد تخفیف شما: A1B2C3"
    },
    {
      "receiver": "09351234567",
      "message": "سفارش ۲۳۴۵ شما ارسال شد."
    }
  ],
  "file_id": null
}

پاسخ‌ها

ساختار پاسخ

نام	نوع	الزامی	توضیح
`return`	ApiStatus	اختیاری	وضعیت پاسخ. مقدار `status` با کد وضعیت HTTP پاسخ یکسان است.
`status`*	integer	الزامی	کد وضعیت — همان کد وضعیت HTTP پاسخ. نمونه`200`
`message`*	string	الزامی	پیام فارسی قابل نمایش به کاربر. نمونه`درخواست تایید شد.`
`entries`	array<MessageInfo>	اختیاری	اطلاعات یک پیامک ثبت‌شده (`dto.MessageInfo`).
`messageid`	integer· int64	اختیاری	شناسهٔ پیامک در نجوا. برای رکوردهای نامعتبر/تکراری صفر است. نمونه`18392011`قالب`int64`
`message`	string	اختیاری	متن نهایی پیامک پس از افزودن «لغو۱۱».
`status`	integer	اختیاری	وضعیت پیامک: ۰ دریافت کننده نامعتبر · ۱ در صف ارسال · ۲ زمان‌بندی شده · ۴ ارسال شده به مخابرات · ۶ خطا در ارسال · ۱۰ رسیده به گیرنده · ۱۱ مشکل در رسیدن پیام · ۱۳ لغو شده · ۱۴ بلاک شده · ۱۵ شماره تکراری · ۱۰۰ شناسه نامعتبر. مقادیر مجاز`012461011131415100`نمونه`1`
`statustext`	string	اختیاری	متن فارسی وضعیت. نمونه`در صف ارسال`
`sender`	string	اختیاری	سرشمارهٔ ارسال. نمونه`3000505`
`receptor`	string	اختیاری	شمارهٔ گیرنده، نرمال‌شده به قالب `09xxxxxxxxx`. نمونه`09121234567`
`date`	integer· int64	اختیاری	زمان ثبت درخواست (unix، ثانیه). نمونه`1757145600`قالب`int64`
`cost`	number· float	اختیاری	هزینه به ریال (مقدار داخلی تومان × ۱۰). نمونه`700`قالب`float`

نمونهٔ پاسخ

{
  "return": {
    "status": 200,
    "message": "درخواست تایید شد."
  },
  "entries": [
    {
      "messageid": 18392101,
      "message": "کد تخفیف شما: A1B2C3\nلغو۱۱",
      "status": 1,
      "statustext": "در صف ارسال",
      "sender": "3000505",
      "receptor": "09121234567",
      "date": 1757145600,
      "cost": 700
    },
    {
      "messageid": 18392102,
      "message": "سفارش ۲۳۴۵ شما ارسال شد.\nلغو۱۱",
      "status": 1,
      "statustext": "در صف ارسال",
      "sender": "3000505",
      "receptor": "09351234567",
      "date": 1757145600,
      "cost": 1400
    },
    {
      "messageid": 0,
      "message": "",
      "status": 15,
      "statustext": "شماره تکراری",
      "sender": "",
      "receptor": "09121234567",
      "date": 0,
      "cost": 0
    }
  ]
}