پیاده‌سازی اسکریپت از طریق API

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

تعاریف

لینک افیلیت:

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

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

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

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

کانورژن:

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

دوره کوکی:

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

دوره مرجوعی:

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

پیش‌نیازها

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

آدرس پایه ارسال درخواست‌های مربوط به سرویس‌ها:

https://core.affili.ir/services/{uri}

API کانورژن‌ها

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

ایجاد کانورژن:

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

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

آدرس ارسال درخواست:

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

قالب درخواست ایجاد کانورژن:

{
  "referrer": string,
  "order_id": string,
  "amount": double,
  "type": string,
  "products": [
    object (Product),
    ...
  ],
  "meta_data": object (MetaData),
  "coupon": string
}

پارامترها:

قالب پاسخ ایجاد کانورژن:

{
  "status": "ok",
  "tag": "saveConversion",
  "api_version": "1.0.0",
  "data": {
    "id": string,
    "publisher": object (Publisher),
    "status": integer,
    "type": string,
    "is_closed": integer,
    "checked_out": integer,
    "checked_out_at": dateTime,
    "order_id": string,
  	"amount": double,
    "commission_amount": double,
    "wage": double,
    "products": [
      object (Product),
      ...
    ],
    "meta_data": object (MetaData)
    "created_at": dateTime,
    "updated_at": dateTime,
    "currency": string
  }
}

پارامترها:

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

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

پاسخ نمونه برای ایجاد کانورژن از نوع فروش:

{
  "status": "ok",
  "tag": "saveConversion",
  "api_version": "1.0.0",
  "data": {
    "id": "zbndn",
    "publisher": {
      "id": "gedyj",
      "full_name": "نام بازاریاب"
    },
    "status": 0,
    "type": "sale",
    "is_closed": 0,
    "checked_out": 0,
    "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": 1,
    "type": "lead",
    "is_closed": 0,
    "checked_out": 0,
    "checked_out_at": null,
    "commission_amount": 2000,
    "wage": 400,
    "order_id": "7007e72b-10d8-540e-9b48-32c14a4f5f6d",
    "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}

*پارامتر conversionId در آدرس، شناسه کانورژن ثبت شده در افیلی است.

قالب درخواست ویرایش کانورژن:

{
  "order_id": string,
  "amount": double,
  "products": [
    object (Product),
    ...
  ],
  "meta_data": object (MetaData),
  "coupon": string,
  "status": integer,
  "recalculate": integer
}

پارامترها:

لیست کانورژن‌ها:

برای دریافت لیست کانورژن‌های ثبت شده از API زیر استفاده کنید.

آدرس ارسال درخواست:

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

قالب پارامترهای ارسالی برای اعمال فیلتر:

{
  "id": string,
  "status" integer,
  "type": string,
  "external_id": string,
  "is_closed": integer,
  "checked_out" integer,
  "min_commission_amount": double,
  "max_commission_amount": double,
  "min_created_at": dateTime,
  "max_created_at": dateTime,
  "min_updated_at": dateTime,
  "max_updated_at": dateTime,
  "min_amount": double,
  "max_amount" double,
}

پارامترها:

موجودیت‌ها

Product

Product

قالب JSON:

{
  "name": string,
  "unit_price": double,
  "quantity": integer,
  "total_price": double
}

پارامترها:

Meta Data

"meta_data": {
  "form_id": string,
  "uniq_param": string,
  
  // Any other fields can be added as extra data.
}

Publisher

قالب JSON:

{
  "id": string,
  "full_name": string
}

پارامترها:

ثابت‌ها

وضعیت کانورژن