API ارسال پوش تکی Lite؛ نمونه درخواست و ورودی‌ها
پوش تکی سبک را از API پوشفا ارسال کنید؛ مسیر send-single-lite-message و پارامترهای درخواست را برای اتصال سرویس سمت سرور ببینید.
کاربرد
زمانی استفاده کنید که فقط باید یک پیام ساده به یک گیرنده بفرستید و به گزارش تحویل یا دکمه‌های پیشرفته نیاز ندارید. این API سبک‌تر و سریع‌تر از نسخه کامل است.
subscriber_id) به جای توکن فایربیس (fcm_token) در ذخیره و ارسالبرای ارسال تکی به یک مخاطب از
subscriber_id و برای ارسال گروهی به چند مخاطب از subscriber_ids[] استفاده کنید. این شناسه‌ها با چرخش توکن تغییر نمی‌کنند و پایداری بیشتری دارند.در حال حاضر، کلیدهای
fcm_token برای ارسال تکی و fcm_tokens[] برای ارسال گروهی به دلیل پایداری کمتر منسوخ شده‌اند؛ بااین‌حال، برای حفظ سازگاری همچنان پشتیبانی می‌شوند.ارسال همزمان
subscriber_id و fcm_token یا subscriber_ids و fcm_tokens، حتی با مقدار خالی، باعث خطای اعتبارسنجی ۴۲۲ می‌شود.برای اطلاعات بیشتر به مستندات دریافت توکن مراجعه کنید.
پارامترهای ورودی
| پارامتر | مقدار | اجباری |
|---|---|---|
| subscriber_id پیشنهادی یا fcm_token | شناسه ثابت مخاطب (UUID) یا توکن fcm_token گیرنده اعلان | بله |
| api_public_key | کلید عمومی سرویس پوشفا | بله |
| api_private_key | کلید خصوصی سرویس پوشفا | بله |
| title | عنوانی که بالای اعلان نمایش داده می‌شود | بله |
| body | متن اصلی که زیر عنوان اعلان نمایش داده می‌شود | بله |
| link_url | لینک مقصد پس از کلیک روی اعلان (مثال: https://example.com) | خیر |
| image_url | آدرس تصویر ضمیمه اعلان | خیر |
| last_visit[operator] | شرط اختیاری آخرین بازدید مخاطب — عملگر مقایسه: >=، >، <=، < یا = | اگر last_visit ارسال شود، الزامی است |
| last_visit[date] | تاریخ مبنای شرط: today (امروز)، today-N (N روز قبل، مثلاً today-7) یا تاریخ میلادی با قالب Y-m-d. پیام فقط برای مخاطبانی ارسال می‌شود که روز آخرین بازدیدشان (به وقت تهران) با این شرط بخواند؛ مثلاً operator برابر >= و date برابر today یعنی فقط کسانی که امروز بازدید داشته‌اند. اگر last_visit را نفرستید، ارسال بدون این شرط انجام می‌شود. | اگر last_visit ارسال شود، الزامی است |
| send_time | زمان ارسال؛ current برای ارسال فوری و delay برای زمان‌بندی‌شده. اختیاری و پیش‌فرض current است. نام قدیمی sendTime فعلاً پشتیبانی می‌شود، اما نباید هر دو نام همزمان ارسال شوند. | خیر |
| time | تاریخ میلادی و ساعت تهران (Asia/Tehran) را با قالب Y-m-d H:i وارد کنید؛ ثانیه صفر در نظر گرفته می‌شود. در حالت delay زمان باید بعد از اکنون باشد. تاریخ شمسی پذیرفته نمی‌شود. این قرارداد برای همه وب‌سرویس‌های ارسال، از جمله ارسال به تاپیک، یکسان است. | اگر send_time برابر delay باشد، الزامی است |
| ttl | مدت اعتبار پیام برای تحویل، بر حسب ثانیه. مقدار پیش‌فرض 86400 ثانیه، یعنی ۲۴ ساعت است. | خیر |
شرط اختیاری آخرین بازدید (last_visit)
با پارامتر اختیاری last_visit پیام فقط برای مخاطبانی ارسال می‌شود که روز آخرین بازدیدشان از سایت یا اپ (به وقت تهران) با شرط شما بخواند. نمونه زیر فقط برای کسانی ارسال می‌شود که امروز بازدید داشته‌اند. اگر مخاطب شرط را نداشته باشد، پیامی ساخته نمی‌شود، هزینه‌ای کسر نمی‌شود و خطای 422 با کد LAST_VISIT_CONDITION_NOT_MET برمی‌گردد.
{
"api_public_key": "YOUR_PUBLIC_KEY",
"api_private_key": "YOUR_PRIVATE_KEY",
"subscriber_id": "SUBSCRIBER_UUID",
"title": "پیشنهاد امروز",
"body": "ویژه کاربرانی که امروز به ما سر زده‌اند",
"last_visit": { "operator": ">=", "date": "today" },
"send_time": "current"
}خطاها و کدهای پاسخ
خطاهای عمومی مانند INVALID_API_KEYS، VALIDATION_ERROR و INSUFFICIENT_BALANCE در همه وب‌سرویس‌های ارسال مشترک‌اند. اگر مخاطب قابل ارسال نباشد، درخواست با یکی از کدهای SUBSCRIBER_NOT_FOUND، FCM_TOKEN_NOT_FOUND، PUSH_TOKEN_EXPIRED یا PUSH_NOT_SUBSCRIBED رد می‌شود و شناسه مشکل‌دار همراه نوع آن در data برمی‌گردد. اگر شرط اختیاری last_visit را بفرستید، LAST_VISIT_TRACKING_DISABLED و LAST_VISIT_CONDITION_NOT_MET هم ممکن است برگردند. معنی هر کد و اینکه چه زمانی باید توکن یا شناسه را حذف کنید در صفحه خطاها آمده است.
send_time برابر delay)، time باید تاریخ میلادی با قالب Y-m-d H:i و ساعت تهران (Asia/Tehran) باشد. قالب نامعتبر با VALIDATION_ERROR و زمان گذشته یا همین لحظه با خطای 422 و کد INVALID_SEND_TIME رد می‌شود؛ در هر دو حالت پیامی ساخته نمی‌شود و هزینه‌ای کسر نمی‌شود.