Skip to main content

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

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

تعاریف:

لینک افیلیت:

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

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

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

کانورژن:

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

دوره کوکی:

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

دوره مرجوعی:

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

پیش‌نیازها:

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

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

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

API کانورژن‌ها:

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

نوع عملیات نوع درخواست توضیحات uri
ایجاد POST ایجاد کانورژن جدید /conversions
ویرایش POST ویرایش کانورژن ایجاد شده؛ conversionId شناسه کانورژن ایجاد شده در افیلی است. /conversions/{conversionId}
لیست GET دریافت لیست کانورژن‌های مربوط به فروشگاه شده در افیلی /conversions

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

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

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

آدرس ارسال درخواست:
POST https://core.affili.ir/services/conversions
قالب ایجاد کانورژن:
{
  "referrer": string,
  "order_id": string,
  "amount": double,
  "type": string,
  "products": [
    object (Product),
    ...
  ],
  "coupon": string
}
پارامترها:
نام اجباری توضیحات
referrer بلی

String

توکن ارجاع که قبلا در مرورگر کاربر ذخیر شده.

type بلی

String

نوع کانورژن که می‌تواند یکی از مقادیر "sale" یا "lead" باشد.

order_id بلی

String

شماره‌ی سفارش انجام شده

amount بلی

Double

مبلغ کل سبد خرید

products خیر

Array of Product Object

لیست محصولات خریداری شده توسط مشتری؛ این پارامتر در کانورژن‌هایی از نوع  فروش(sale) ارسال می‌شود.

coupon خیر

String

کد تخفیف استفاده شده در خرید

meta_data بلی

MetaData Object

آبجکت حاوی اطلاعات لید ثبت شده؛ این پارامتر در کانورژن‌هایی از نوع لید(lead) ارسال می‌شود.

قالب پاسخ دریافتی:
{
  "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),
      ...
    ],
    "created_at": dateTime,
    "updated_at": dateTime,
    "currency": string
  }
}
پارامترها:
نام توضیحات
id

String

شناسه یکتای کانورژن ایجاد شده در افیلی

publisher

Publisher Object

آبجکت مربوط به اطلاعات بازاریاب.

status

Conversion Status Constant

وضعیت کانورژن که می‌تواند یکی از اعداد ۰(در انتظار تایید توسط سیستم)، ۱(تایید شده)، ۲(رد شده)، ۳(تکراری) یا ۴(نیازمند بررسی دستی) باشد.

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

شماره سفارش

products

Array of Product Object

لیست محصولات خریداری شده توسط مشتری؛ این پارامتر تنها در صورتی که کانورژن از نوع فروش(sale)، نمایش داده می‌شود.

meta_data

MetaData Object

آبجکت حاوی اطلاعات لید ایجاد شده؛ این پارامتر تنها در کانورژن‌هایی از نوع لید(lead) نمایش می‌شود.

coupon

String

کد تخفیف استفاده شده در خرید؛ این پارامتر تنها در صورتی که کانورژن از نوع فروش(sale)، نمایش داده می‌شود.

created_at

DateTime

تاریخ ایجاد

updated_at

DateTime

تاریخ آخرین بروزرسانی

currency

String

واحد پولی کانورژن ثبت شده که می‌تواند یکی از مقادیر IRT(تومان) یا IRR(ریال) باشد.


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

نمونه دیتای ارسالی برای ایجاد کانورژن از نوع فروش:
{
  "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": 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": 1,
    "type": "lead",
    "is_closed": null,
    "checked_out": null,
    "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}

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

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

 

آبجکت‌ها:

آبجکت Product

قالب JSON:

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

پارامترها:

name

String

نام محصول

unit_price

Double

قیمت واحد محصول در سبد خرید

quantity

Integer

تعداد محصول در سبد خرید

total_price

Double

مجموع قیمت محصول در سبد خرید


آبجکت Meta Data

قالب JSON:

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

پارامترها:

 form_id

String

شناسه یکتای فرم مربوطه در وبسایت فروشگاه

uniq_param

String

پارامتر یکتای لید ثبت شده که می‌تواند داده‌ای نظیر شماره موبایل، ایمیل، کد ملی یا هر مقدار یکتای دیگری در فرم باشد.

آبجکت Publisher

قالب JSON:

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

پارامترها:

id شناسه یکتای بازاریاب در افیلی
full_name نام بازاریاب