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),
    ...
  ],
  "meta_data": object (MetaData),
  "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),
      ...
    ],
    "meta_data": object (MetaData)
    "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(ریال) باشد.

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

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

پارامترها:

نام توضیحات
order_id

String

شماره‌ی سفارش انجام شده؛ این پارامتر در کانورژن‌هایی با نوع فروش(sale) ارسال می‌شود.

amount

Double

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

products

Array of Product Object

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

meta_data

MetaData Object

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

coupon

String

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

status

Conversion Status Constant

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

recalculate

Boolean

در صورت ویرایش پارامترهای تاثیرگذار در محاسبه پورسانت همانند مبلغ کل سبد خرید، محصولات خریداری شده و ... برای محاسبه مجدد پورسانت باید پارامتر recalculate برابر با مقدار یک یا true باشد.

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

برای دریافت لیست کانورژن‌های ثبت شده از 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,
}

پارامترها:

نام توضیحات

id

String

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

status

Conversion Status Constant

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

type

String

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

order_id

String

شماره سفارش

is_closed

Integer

وضعیت لاک کانورژن را نشان می‌دهد و در صورتی که مقدار آن ۱ باشد امکان ویرایش کانورژن وجود نخواهد داشت.

checked_out

Integer

وضعیت تسویه با بازاریاب را نشان می‌دهد

min_commission_amount

Double

حداقل مبلغ پورسانت کانورژن؛ این پارامتر برای فیلتر کانورژن‌هایی با پورسانت بیش‌تر یا مساوی این مقدار استفاده می‌شود.  

max_commission_amount

Double

حداکثر مبلغ پورسانت کانورژن؛ این پارامتر برای فیلتر کانورژن‌هایی با پورسانت کمتر یا مساوی این مقدار استفاده می‌شود.  

min_created_at

Double

حداقل تاریخ ایجاد کانورژن؛ این پارامتر برای فیلتر کانورژن‌هایی با تاریخ ایجاد بیش‌تر یا مساوی این مقدار استفاده می‌شود.  

max_created_at

Double

حداکثر تاریخ ایجاد کانورژن؛ این پارامتر برای فیلتر کانورژن‌هایی با تاریخ ایجاد کمتر یا مساوی این مقدار استفاده می‌شود.

min_updated_at

Double

حداقل تاریخ ایجاد کانورژن؛ این پارامتر برای فیلتر کانورژن‌هایی با تاریخ ویرایش بیش‌تر یا مساوی این مقدار استفاده می‌شود.

max_updated_at

Double

حداکثر تاریخ ایجاد کانورژن؛ این پارامتر برای فیلتر کانورژن‌هایی با تاریخ ویرایش کمتر یا مساوی این مقدار استفاده می‌شود.

min_amount

Double

حداقل مبلغ سبد خرید؛ این پارامتر برای فیلتر کانورژن‌هایی با مبلغ سبد خرید بیش‌تر یا مساوی این مقدار استفاده می‌شود.

max_amount

Double

حداکثر تاریخ ایجاد کانورژن؛ این پارامتر برای فیلتر کانورژن‌هایی با مبلغ سبد خرید کمتر یا مساوی این مقدار استفاده می‌شود.

موجودیت‌ها

Product

قالب JSON:JSON

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

پارامترها:

name

String

نام محصول

unit_price

Double

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

quantity

Integer

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

total_price

Double

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

Meta Data

قالب JSON: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:JSON

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

پارامترها:

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

ثابت‌ها

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

۰ در انتظار تایید توسط سیستم
۱ تایید شده
۲ تکراری
۳ نیازمند بررسی دستی