پیاده‌سازی با API

برای ردیابی و مدیرت کانورژن‌ها و علاوه بر پیاده‌سازی اسکریپت افیلی می‌توانید از طریق API‌هایی که توسط افیلی ارائه شده است، اقدام به پیاده‌سازی سرویس همکاری در فروش نمایید. برای این منظور می‌توانید از مستندات ارائه شده در این صفحه استفاده کنید.

تعاریف:

a. لینک افیلیت:

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

پارامترهای لینک افیلیت:

referrer:

توکنی است که در هر بار ارجاع، به لینک ارجاع اختصاص داده می‌شود. این توکن مقدار یکتایی دارد و برای صحت سنجی کلیک‌ها مورد استفاده قرار می‌گیرید.

exp:

تعداد روزهای اعتبار کوکی در مرورگر کاربر است.

dl:

این پارامتر مشخص کننده تعداد دفعات مجاز ثبت کانورژن برای بازاریاب ارجاع‌دهنده خواهد بود. به عبارت دیگر این مقدار به ما می‌گوید تا چند بار در صورت خرید مشتری به بازاریاب پورسانت تعلق خواهد گرفت.

نکته: مقدار -1 به معنای نامحدود است. و در صورت اعمال تا زمان معتبر بودن کوکی در صورت خرید مشتری به بازاریاب پورسانت تعلق می‌گیرد.

b. کانورژن:

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

 c. دوره کوکی:

مدت زمانی است که لینک افیلیت معتبر بوده و در صورت تحقق کانورژن در این بازه زمانی به بازاریاب پورسانت تعلق خواهد گرفت.

d. دوره مرجوعی:

مدت زمانی است که پس از ثبت کانورژن امکان ویرایش آن وجود دارد. پس از این مدت زمان کانورژن لاک شده و در اولین سیکل بررسی کانورژن‌های لاک شده، پورسانت آن از حساب فروشگاه کسر و به بازاریاب پرداخت خواهد شد.

لیست APIها:

برای استفاده از این APIها نیاز به ارسال Bearer توکن است. از طریق ارتباط با پشتیبانی می‌توانید توکن دسترسی را دریافت کنید.

ثبت کانورژن:

POST https://core.affili.ir/services/conversions

بعد از اینکه مشتری از طریق لینک افیلیت وارد وبسایت شما شد

پارامترهای referrer و dl را به مدت زمان طول دورد استفاده کوکی (مقدار پارامتر exp)، در کوکی مرورگر کارسال درخواست ثبرت ذخیا ویره مای‌کنیم.

بعد از تحققش کانورژن (به طور مثال انجام خرید) از طریق API ثبت کانورژن، اطلاعات مربوطه به افیلی ارسال می‌شود. در ادامه به بررسی نمونه دیتای ارسالی برای کانورژن‌های خرید و لید خواهیم پرداخت.

a. خرید:

نمونه دیتای ارسالی:

{
  "referrer": "63b01acf9bf8325c1a3a2325",
  "order_id": "1234598",
  "amount": "12000",
  "type": "sale",
  "products": [
    {
      "name": "محصول نمونه",
      "unit_price": "12000",
      "quantity": "3",
      "total_price": "36000"
    },
    {
      "name": "محصول نمونه شماره دو",
      "unit_price": "43000",
      "quantity": "1",
      "total_price": "43000"
    }
  ],
  "coupon": null
}

توضیح پارامترها:

نام	نوع	اجباری	توضیحات
referrer	String	بلی	توکن ارجاع است
type	String	بلی	نوع کانورژن
order_id	String	بلی	شماره‌ی سفارش انجام شده
amount	Double	بلی	مبلغ کل سبد خرید
products	Array	خیر	آرالیهست محصولات خریداری شده توسط مشتری؛ این پارامتر در کانورژن‌هایی از نوع  فروش(sale) ارسال می‌شود.
products.*	Object	-	آبجکت حاوی اطلاعات هر محصول
products.*.name	String	در صورت ارسال اطلاعات محصول، بلی	نام محصول
products.*.unit_price	Double	در صورت ارسال اطلاعات محصول، بلی	قیمت واحد محصول در سبد خرید
products.*.quantity	Integer	در صورت ارسال اطلاعات محصول، بلی	تعداد محصول در سبد خرید
products.*.total_price	Double	در صورت ارسال اطلاعات محصول، بلی	مجموع قیمت محصول در سبد خرید
coupon	String	خیر	کد تخفیف استفاده شده در خرید
meta_data	Object	برای کانورژن از نوع لید، بلی	آبجکت حاوی اطلاعات لید ثبت شده؛ این پارامتر در کانورژن‌هایی از نوع لید(lead) ارسال می‌گردد.
meta_data.form_id	String	بلی	شناسه یکتای فرم مربوطه در وبسایت فروشگاه
meta_data.uniq_param	Any	بلی	پارامتر یکتای لید ثبت شده که می‌تواند داده‌ای نظیر شماره موبایل، ایمیل، کد ملی یا هر مقدار یکتای دیگری در فرم باشد.
meta_data.*	Any	خیر	سایر اطلاعات مربوط به لید ثبت شده

ن

پارامونترهای استفاده شده در دیتای بازگشتی:

{
  "status": "ok",
  "tag": "saveConversion",
  "api_version": "1.0.0",
  "data": {
    "id": "zbndn",
    "publisher": {
      "id": "gedyj",
      "full_name": "نام بازاریاب" },
    "status": 0,
    "type": "sale",
    "is_closed": null,
    "checked_out": null,
    "checked_out_at": null,
    "amount": 10220,
    "commission_amount": 408.8,
    "wage": 81.76,
    "order_id": 23543,
    "products": [
      {
        "name": "گوشی",
        "unit_price": 2000,
        "quantity": "3",
        "total_price": 40
      }
    ],
    "created_at": "2022-12-31 19:27:32",
    "updated_at": "2022-12-31 19:27:32",
    "currency": "IRT"
  }
}

توضیح پاراسمت سرهاور:

نام	نوع	توضیحات
id	String	شناسه یکتای کانورژن ثبت شده در افیلی
publisher	Object	آبجکت مربوط به اطلاعات بازاریاب
publisher.id	String	شناسه یکتای بازاریاب در افیلی
publisher.full_name	String	نام بازاریاب
status	Integer	وضعیت کانورژن که می‌تواند یکی از اعداد ۰(منتظر تایید توسط سیستم)، ۱(تایید شده)، ۲(رد شده)، ۳(تکراری) یا ۴(نیازمند بررسی دستی) باشد.
type	String	نوع کانورژن که می‌تواند sale یا lead باشد.
is_closed	Integer	وضعیت لاک کانورژن را نشان می‌دهد و در صورتی که مقدار آن ۱ باشد امکان ویرایش کانورژن وجود نخواهد داشت.
checked_out	Integer	تاریخ لاک شدن کانورژن
checked_out_at	DateTime	تاریخ تسویه پورسانت با بازاریاب
amount	Double	مبلغ سبد خرید؛ این پارامتر تنها در صورتی که کانورژن از نوع فروش(sale) باشد ارسال می‌شود.
commission_amount	Double	مبلغ پورسانت
wage	Double	کارمزد افیلی
order_id	String|Integer	شماره سفارش
products	Array	لیست محصولات خریداری شده توسط مشتری؛ این پارامتر تنها در صورتی که کانورژن از نوع فروش(sale) باشد، ارسال می‌شود.
products.*	Object	آبجکت حاوی اطلاعات هر محصول
products.*.name	String	نام محصول
products.*.unit_price	Double	قیمت واحد محصول در سبد خرید
products.*.quantity	Integer	تعداد محصول در سبد خرید
products.*.total_price	Double	مجموع قیمت محصول در سبد خرید
meta_data	Object	آبجکت حاوی اطلاعات لید ثبت شده
meta_data.form_id	String	شناسه یکتای فرم مربوطه در وبسایت فروشگاه
meta_data.uniq_param	Any	پارامتر یکتای لید ثبت شده که می‌تواند داده‌ای نظیر شماره موبایل، ایمیل، کد ملی یا هر مقدار یکتای دیگری در فرم باشد.
meta_data.*	Any	سایر اطلاعات موجود در فرم مربوطه
coupon	String	کد تخفیف استفاده شده در خرید
created_at	DateTime	تاریخ ایجاد
updated_at	DateTime	تاریخ آخرین بروزرسانی
currency	String	واحد پولی کانورژن ثبت شده که می‌تواند یکی از مقادیر IRT(تومان) یا IRR(ریال) باشد.

ثبت کانورژن:

POST https://core.affili.ir/services/conversions

بعد از اینکه مشتری از طریق لینک افیلیت وارد وبسایت شما شد پارامترهای referrer و dl را به مدت زمان طول دوره کوکی (مقدار پارامتر exp)، در کوکی مرورگر کاربر ذخیره می‌کنیم.

بعد از تحقق کانورژن (به طور مثال انجام خرید توسط مشتری) از طریق API ثبت کانورژن، اطلاعات مربوطه به افیلی ارسال می‌شود. در ادامه به بررسی نمونه دیتای ارسالی و دریافتی در ثبت کانورژن‌های فروش و لید خواهیم پرداخت.

نمونه دیتای ارسالی در ثبت کانورژن از نوع فروش:

{
  "referrer": "63b01acf9bf8325c1a3a2325",
  "order_id": "1234598",
  "amount": "12000",
  "type": "sale",
  "products": [
    {
      "name": "محصول نمونه",
      "unit_price": "12000",
      "quantity": "3",
      "total_price": "36000"
    },
    {
      "name": "محصول نمونه شماره دو",
      "unit_price": "43000",
      "quantity": "1",
      "total_price": "43000"
    }
  ],
  "coupon": null
}

b.نمونه لدیتای بازگشتی در ثبت کانورژن از نوع فروش:

{
  "status": "ok",
  "tag": "saveConversion",
  "api_version": "1.0.0",
  "data": {
    "id": "zbndn",
    "publisher": {
      "id": "gedyj",
      "full_name": "نام بازاریاب"
    },
    "status": 0,
    "type": "sale",
    "is_closed": null,
    "checked_out": null,
    "checked_out_at": null,
    "order_id": "1234598",
  	"amount": 12000,
    "commission_amount": 408.8,
    "wage": 81.76,
    "products": [
      {
        "name": "محصول نمونه",
        "unit_price": "12000",
        "quantity": "3",
        "total_price": "36000"
      },
      {
        "name": "محصول نمونه شماره دو",
        "unit_price": "43000",
        "quantity": "1",
        "total_price": "43000"
      }
    ],
    "created_at": "2022-12-31 19:27:32",
    "updated_at": "2022-12-31 19:27:32",
    "currency": "IRT"
  }
}

نمونه دیتای ارسالی

 در ثبت کانورژن از نوع لید:

{
  "referrer": "63abe5089bf8325c1a3a231a",
  "type": "lead",
  "meta_data": {
    "form_id": "register-form",
    "uniq_param": "09123456789",
	"first_name": "First Name",
	"last_name": "Last Name"
  }
}

نمونه دیتای بازگشتی در ثبت کانورژن از نوع لید:

{
  "status": "ok",
  "tag": "saveConversion",
  "api_version": "1.0.0",
  "data": {
    "id": "ydnak",
    "publisher": {
      "id": "gedyj",
      "full_name": "نام بازاریاب"
    },
    "status": 0,1,
    "type": "lead",
    "is_closed": null,
    "checked_out": null,
    "checked_out_at": null,
    "amount": 0,
    "commission_amount": 2000,
    "wage": 400,
    "order_id": "7007e72b-10d8-540e-9b48-32c14a4f5f6d",
    "products": [],
    "created_at": "2022-12-31 19:36:20",
    "updated_at": "2022-12-31 19:36:20",
    "currency": "IRT",
    "meta_data": {
      "form_id": "register-form",
      "uniq_param": "09123456789",
      "first_name": "First Name",
      "last_name": "Last Name"
    }
  }
}

ویرایش کانورژن:

POST https://core.affili.ir/services/conversions/{conversionId}

می‌توانید تا قبل از پایان دوره مرجوعی و لاک شدن کانورژن، آن را ویرایش کنید. دقت داشته باشید که بعد از لاک شدن امکان اعمال تغییرات وجود نخواهد داشت. در ادامه به بررسی API مربوطه می‌پردازیم.

پارامترهای قابل ویرایش: