ارسال رویداد RetenX از سمت سرور

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

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

پارامترها

نمونه 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"

نمونه تأیید تبدیل و درآمد از سمت سرور

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

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
    }
  }'

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

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

پاسخ موفق (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) فقط پروفایل‌های دارای توکن معتبر را وارد صف FCM می‌کند.

معنی فیلد conversion

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