پیاده‌سازی با 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	خیر	آرایه محصولات خریداری شده
products.*	Object	-	آبجکت حاوی اطلاعات هر محصول
products.*.name	String	در صورت ارسال اطلاعات محصول، بلی	نام محصول
products.*.unit_price	Double	در صورت ارسال اطلاعات محصول، بلی	قیمت واحد محصول در سبد خرید
products.*.quantity	Integer	در صورت ارسال اطلاعات محصول، بلی	تعداد محصول در سبد خرید
products.*.total_price	Double	در صورت ارسال اطلاعات محصول، بلی	مجموع قیمت محصول در سبد خرید
coupon	String	خیر	کد تخفیف استفاده شده در خرید

نمونه دیتای بازگشتی:

{
  "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
publisher
status
type
is_closed
checked_out
checked_out_at
amount
commission_amount
wage
order_id
created_at
updated_at
currency

{
  "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. لید:

دیتای ارسالی

{
  "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,
    "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"
  }
}