مستندات وب‌سرویس‌ها وب‌سرویس Profile و RetenX ارسال رویداد RetenX از Backend

ارسال رویداد RetenX از Backend

ثبت Custom Event سروری برای شروع، خروج، ادامه Wait Until و تأیید Conversion و درآمد واقعی Journey.

POST
https://pushfa.com/api/webservices/retention/events
دانلود کالکشن Postman

شناسایی مخاطب

رویداد می‌تواند با subscriber_id، external_id، یک Custom Alias مانند mobile یا fcm_token به پروفایل متصل شود. external_id همان Alias عادی و اصلی است و با Custom Aliasهای برچسب‌دار در aliases[label] تفاوت دارد. اگر پروفایل وجود نداشته باشد و external_id یا Custom Alias ارسال شود، پروفایل SMS-only به‌صورت خودکار ساخته می‌شود. idempotency_key از ثبت دوباره یک رویداد در retryهای سرور جلوگیری می‌کند.

پارامترها

فیلدتوضیحالزام
api_public_key کلید عمومی سرویس پوشفا بله
api_private_key کلید خصوصی سرویس پوشفا بله
event_name نام event مطابق Start، رویداد هدف/Exit یا Wait Until سفر بله
subscriber_id Subscriber ID پایدار یکی از روش‌های شناسایی
external_id Alias عادی و اصلی کاربر؛ متفاوت از Custom Alias یکی از روش‌های شناسایی
aliases[mobile] Custom Alias برچسب‌دار برای جستجو یا ساخت پروفایل یکی از روش‌های شناسایی
params[key] properties رویداد برای شرط، شخصی‌سازی یا Conversion خیر
params[order_id] شناسه یکتای سفارش مطابق پارامتر شناسه تنظیم‌شده در Journey برای درآمد تأییدشده بله
params[amount] مبلغ سفارش مطابق پارامتر مبلغ تنظیم‌شده در Journey برای محاسبه درآمد بله
event_time زمان ISO 8601 رویداد؛ پیش‌فرض زمان دریافت خیر
idempotency_key UUID یکتا برای جلوگیری از رویداد تکراری خیر ولی پیشنهادی

نمونه form-data 

curl -X POST https://pushfa.com/api/webservices/retention/events \
  -F "api_public_key=YOUR_PUBLIC_KEY" \
  -F "api_private_key=YOUR_PRIVATE_KEY" \
  -F "event_name=add_to_cart" \
  -F "aliases[mobile]=09120000000" \
  -F "params[mobile]=09120000000" \
  -F "params[product_id]=123" \
  -F "idempotency_key=550e8400-e29b-41d4-a716-446655440000"

نمونه تأیید Conversion و درآمد از Backend

بعد از تأیید قطعی پرداخت، Event هدف Journey را از Backend بفرستید. درخواست دارای api_private_key و شناسه سفارش معتبر، Conversion را سروری تأیید می‌کند و مبلغ آن وارد درآمد تأییدشده می‌شود. api_private_key نباید در مرورگر یا اپلیکیشن قرار بگیرد.

order_id در سطح هر سرویس یکتا است. ارسال دوباره همان سفارش آن را دوباره نمی‌شمارد؛ اگر قبلاً از کلاینت ثبت شده باشد، همان رکورد به تأیید سرور ارتقا پیدا می‌کند.
curl -X POST https://pushfa.com/api/webservices/retention/events \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "subscriber_id": "SUBSCRIBER_UUID",
    "event_name": "checkout_completed",
    "event_time": "2026-08-23T14:35:00+03:30",
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
    "params": {
      "order_id": "ORD-1042",
      "amount": 850000
    }
  }'
راهنمای کامل Conversion و مدل Last-touch

تشخیص پذیرش رویداد

رویداد زمانی پذیرفته می‌شود که نام آن با Start یک Journey فعال، رویداد هدف/Exit یا یک گره Wait Until در Journey واجد شرایط مطابقت داشته باشد. برای تشخیص نتیجه، HTTP status و فیلد status پاسخ را بررسی کنید؛ پاسخ 200 یا 201 با status برابر success یعنی رویداد پذیرفته شده و پاسخ 404 با status برابر error یعنی پذیرفته نشده است.

وجود subscriber_id در پاسخ موفق، شناسه پایدار پروفایلی را نشان می‌دهد که رویداد برای آن ثبت شده است.
HTTP statusنتیجهتوضیح
201 پذیرفته شد رویداد جدید با موفقیت ثبت شده است.
200 پذیرفته شد رویداد با همین idempotency_key قبلاً ثبت شده و دوباره ساخته نشده است.
404 پذیرفته نشد نام رویداد توسط هیچ کمپین جاری پذیرفته نمی‌شود.

پاسخ موفق (201) 

{
  "status": "success",
  "message": "Event recorded successfully.",
  "subscriber_id": "462c6a8d-5997-4b38-a7a5-17b795d8d20a",
  "profile": {
    "external_id": null,
    "aliases": {
      "mobile": "09120000000"
    }
  },
  "conversion": {
    "attributed": true,
    "campaign_id": 42,
    "value": 850000,
    "currency": "IRT",
    "verified": true
  }
}

پاسخ رویداد پذیرفته‌نشده (404) 

{
  "status": "error",
  "message": "This event is not accepted by any current campaign."
}

ارسال‌های Push و پروفایل بدون توکن

پروفایل‌های SMS-only در صفحه مشترکین و Segmentها قابل مشاهده‌اند، اما ارسال گروهی Push، Topic، ارسال API/پنل، A/B Test و هدف‌گیری alias یا Subscriber ID فقط پروفایل‌های دارای token معتبر را وارد صف FCM می‌کند.

معنی فیلد conversion

attributed فقط وقتی true است که پیش از Event هدف، Push یا SMS یک Journey برای همان مخاطب ارسال شده و تماس داخل پنجره انتساب باشد. verified برای درخواست Backend دارای شناسه سفارش true است. ممکن است Event با status=success ثبت شود اما به دلیل نبود تماس معتبر، conversion.attributed برابر false باشد.

Ctrl+I