API استعلام وضعیت پوش؛ بررسی گزارش ارسال پیام
وضعیت پیام ارسال‌شده را از API پوشفا استعلام کنید؛ ورودی‌ها و پاسخ check-notification-status را برای پیگیری گزارش پیام در سیستم خود ببینید.
POST
https://pushfa.com/api/webservices/check-notification-status
کاربرد
پس از ارسال اعلان، notification_id دریافتی را نگه دارید و با این API وضعیت هر گیرنده را بررسی کنید.
شفاف‌سازی وضعیت‌ها و نحوه محاسبه هزینه
هزینه هر مرحله فقط پس از ثبت همان رویداد محاسبه می‌شود. وضعیت ناموفق با دریافت‌نشدن پیام توسط مشترک یکسان نیست و بر اساس پاسخ Firebase تعیین می‌شود.
اگر Firebase شناسه تأیید ارسال را صادر کند، پیام از جانب پوشفا «ارسال‌شده» محسوب می‌شود و هزینه ارسال کسر خواهد شد؛ حتی اگر مشترک در آن زمان به اینترنت دسترسی نداشته باشد یا به دلیل اختلالات شبکه پیام را دریافت نکند.
| وضعیت | معیار ثبت وضعیت | اثر مالی |
|---|---|---|
| ناموفق (failed) | Firebase توکن یا شناسه دستگاه را نامعتبر اعلام کند، یا به هر دلیل شناسه تأیید ارسال را صادر نکند. | هزینه ارسال به‌صورت خودکار به اعتبار کاربر عودت داده می‌شود. |
| ارسال‌شده (sent) | Firebase شناسه تأیید ارسال را صادر کرده باشد. | هزینه ارسال مطابق تعرفه کسر می‌شود. |
| تحویل‌شده (delivered) | دستگاه یا مرورگر دریافت پیام را به پوشفا تأیید کند. | در صورت فعال‌بودن گزارش تحویل، هزینه تحویل مطابق تعرفه کسر می‌شود. |
| کلیک‌شده (clicked) | کلیک مشترک روی اعلان یا دکمه آن در پوشفا ثبت شود. | در صورت فعال‌بودن گزارش کلیک، هزینه کلیک مطابق تعرفه کسر می‌شود. |
پارامترهای ورودی
| پارامتر | مقدار | اجباری |
|---|---|---|
| api_public_key | کلید عمومی سرویس | بله |
| api_private_key | کلید خصوصی سرویس | بله |
| notification_ids[] | آرایه‌ای از شناسه‌های اعلان‌های ارسالی | بله |
نمونه درخواست
curl -X POST https://pushfa.com/api/webservices/check-notification-status \
-H "Content-Type: application/json" \
-d '{
"api_public_key": "YOUR_PUBLIC_KEY",
"api_private_key": "YOUR_PRIVATE_KEY",
"notification_ids": ["MESSAGE_ID_1", "MESSAGE_ID_2"]
}'علت ناموفق‌بودن ارسال (failure_code)
برای هر اعلان با وضعیت failed، فیلد failure_code علت را با یک کد ثابت مشخص می‌کند؛ برای سایر وضعیت‌ها مقدار آن null است. همین فیلد در درخواست وب‌هوک تحویل (webhook_url) هم ارسال می‌شود. برای مثال PUSH_TOKEN_EXPIRED یعنی Firebase توکن مخاطب را منقضی اعلام کرده است؛ پوشفا آن توکن را غیرفعال می‌کند و ارسال بعدی به همین مخاطب با خطای 410 رد می‌شود.
INVALID_SEND_TIME خطای هنگام پذیرش درخواست است، نه failure_code تحویل؛ زمان گذشته یا همین لحظه پیش از ساخت پیام و کسر اعتبار رد می‌شود و notification_id ندارد.{
"message": "Getting notifications status successfully",
"status_code": 1,
"data": [
[
{
"id": "9b2e0c0e-5c1f-4a39-9d55-0d6c1e2f7a10",
"receptor_token": "DEVICE_FCM_TOKEN",
"status": "failed",
"is_clicked": false,
"send_at": "2026-10-15T08:30:00.000000Z",
"sent_at": "2026-10-15T08:30:02.000000Z",
"fcm_sent_id": null,
"delivered_at": null,
"clicked_at": null,
"is_read_widget": false,
"failure_code": "PUSH_TOKEN_EXPIRED"
}
]
],
"errors": false
}