سرویس کانورژن
برای ردیابی و مدیرت کانورژنها و علاوه بر پیادهسازی اسکریپت میتوانید از طریق APIهای سرویس کانورژن، اقدام به پیادهسازی سرویس همکاری در فروش نمایید. در ادامه به بررسی APIهای این سرویس و نحوه استفاده از آنها خواهیم پرداخت.
تعاریف
لینک افیلیت
به لینک کوتاه شدهای که توسط بازاریاب در افیلی ساخته میشود و مشتری پس از کلیک روی آن به وبسایت شما ارجاع داده میشود لینک افیلیت میگویند. هر لینک افیلیت پس از ارجاع به وبسایت فروشگاه شامل پارامترهای زیر خواهد بود.
- referrer: توکنی است که در هر بار ارجاع، به لینک ارجاع اختصاص داده میشود. این توکن مقدار یکتایی دارد و برای صحت سنجی کلیکها مورد استفاده قرار میگیرید.
- exp: تعداد روزهای اعتبار کوکی در مرورگر کاربر است.
-
dl: این پارامتر مشخص کننده تعداد دفعات مجاز ثبت کانورژن برای بازاریاب ارجاعدهنده خواهد بود. به عبارت دیگر این مقدار به ما میگوید تا چند بار در صورت خرید مشتری به بازاریاب پورسانت تعلق خواهد گرفت.
نکته: مقدار 1- به معنای نامحدود است. و در صورت اعمال تا زمان معتبر بودن کوکی در صورت خرید مشتری به بازاریاب پورسانت تعلق میگیرد.
کانورژن
به هر اقدامی که فروشگاه در ازای آن به بازاریاب پورسانت پرداخت میکند کانورژن میگویند. افیلی دو نوع کانورژن فروش و لید را پشتیبانی میکند.
دوره کوکی
مدت زمانی است که لینک افیلیت معتبر بوده و در صورت تحقق کانورژن در این بازه زمانی به بازاریاب پورسانت تعلق خواهد گرفت.
دوره مرجوعی
مدت زمانی است که پس از ایجاد کانورژن امکان ویرایش آن وجود دارد. پس از این مدت زمان کانورژن لاک شده و در اولین سیکل بررسی کانورژنهای لاک شده، پورسانت آن از حساب فروشگاه کسر و به بازاریاب پرداخت خواهد شد.
پیشنیازها
برای استفاده از سرویسهای تعریف شده، نیاز به ارسال Bearer توکن است. از طریق ارتباط با پشتیبانی میتوانید توکن دسترسی را دریافت کنید.
آدرس پایه ارسال درخواستها
https://core.affili.ir/services/conversions
API کانورژنها
طبق توضیحات داده شده در جدول زیر، از سه API تعریف شده میتوانید برای ایجاد، ویرایش و دریافت کانورژنها استفاده کنید.
نوع عملیات | نوع درخواست | توضیحات | uri |
ایجاد | POST | ایجاد کانورژن جدید | / |
ویرایش | POST | ویرایش کانورژن ایجاد شده؛ conversionId شناسه کانورژن ایجاد شده در افیلی است. | /{conversionId} |
لیست | GET | دریافت لیست کانورژنهای ثبت شده | / |
ایجاد کانورژن
بعد از اینکه مشتری از طریق لینک افیلیت وارد وبسایت شما شد پارامترهای referrer و dl را به مدت زمان طول دوره کوکی (مقدار پارامتر exp)، در کوکی مرورگر کاربر ذخیره میکنیم.
بعد از تحقق کانورژن (به طور مثال انجام خرید توسط مشتری) از طریق API ایجاد کانورژن، اطلاعات مربوطه به افیلی ارسال میشود. در ادامه به بررسی نمونه دیتای ارسالی و دریافتی در ایجاد کانورژنهای فروش و لید خواهیم پرداخت.
تذکر: در صورتی که از قبل مشتری را تعریف کرده باشید و در API کانورژن شناسه مشتری را ارسال کنید نیازی به ارسال referrer نیست.
آدرس ارسال درخواست
POST https://core.affili.ir/services/conversions
قالب درخواست ایجاد کانورژن
{
"referrer": string,
"order_id": string,
"amount": double,
"type": string,
"products": [
object (Product),
...
],
"is_first_order": boolean,
"meta_data": object (MetaData),
"coupon": string,
"customer_id": string,
}
پارامترها
نام | اجباری | توضیحات |
referrer | بلی |
String توکن ارجاع که قبلا در مرورگر کاربر ذخیر شده. ارسال این پارامتر زمانی که customer_id ارسال میشود، اختیاری است. |
type | بلی |
String نوع کانورژن که میتواند یکی از مقادیر "sale" یا "lead" باشد. |
order_id | بلی |
String شمارهی سفارش انجام شده |
amount | بلی |
Double مبلغ کل سبد خرید |
products | خیر |
لیست محصولات خریداری شده توسط مشتری؛ این پارامتر در کانورژنهایی با نوع فروش(sale) ارسال میشود. |
coupon | خیر |
String کد تخفیف استفاده شده در خرید |
is_first_order | خیر |
Boolean پارامتر مشخصکننده اولین خرید |
meta_data | بلی |
آبجکت حاوی اطلاعات لید ثبت شده؛ این پارامتر در کانورژنهایی با نوع لید(lead) ارسال میشود. |
customer_id | خیر |
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),
...
],
"is_first_order": boolean,
"meta_data": object (MetaData)
"created_at": dateTime,
"updated_at": dateTime,
"currency": string,
"customer_id": string,
}
}
پارامترها
نام | توضیحات |
id |
String شناسه یکتای کانورژن ایجاد شده در افیلی |
publisher |
آبجکت مربوط به اطلاعات بازاریاب. |
status |
وضعیت کانورژن که میتواند یکی از اعداد ۰(در انتظار تایید توسط سیستم)، ۱(تایید شده)، ۲(رد شده)، ۳(تکراری) یا ۴(نیازمند بررسی دستی) باشد. |
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 |
لیست محصولات خریداری شده توسط مشتری؛ این پارامتر تنها در صورتی که کانورژن از نوع فروش(sale)، نمایش داده میشود. |
is_first_order |
Boolean پارامتر مشخصکننده اولین خرید |
meta_data |
آبجکت حاوی اطلاعات لید ایجاد شده؛ این پارامتر تنها در کانورژنهایی از نوع لید(lead) نمایش میشود. |
coupon |
String کد تخفیف استفاده شده در خرید؛ این پارامتر تنها در صورتی که کانورژن از نوع فروش(sale)، نمایش داده میشود. |
created_at |
DateTime تاریخ ایجاد |
updated_at |
DateTime تاریخ آخرین بروزرسانی |
currency |
String واحد پولی کانورژن ثبت شده که میتواند یکی از مقادیر IRT(تومان) یا IRR(ریال) باشد. |
customer_id |
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"
}
],
"is_first_order": false,
"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"
}
],
"is_first_order": false,
"created_at": "2022-12-31 19:27:32",
"updated_at": "2022-12-31 19:27:32",
"currency": "IRT",
"customer_id": null
}
}
درخواست نمونه برای ایجاد کانورژن از نوع لید
{
"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"
},
"customer_id": null
}
}
ویرایش کانورژن
میتوانید تا قبل از پایان دوره مرجوعی و لاک شدن کانورژن، آن را ویرایش کنید. دقت داشته باشید که بعد از لاک شدن امکان اعمال تغییرات وجود نخواهد داشت.
آدرس ارسال درخواست
POST https://core.affili.ir/services/conversions/{conversionId}
*پارامتر conversionId در آدرس، شناسه کانورژن ثبت شده در افیلی است.
قالب درخواست ویرایش کانورژن
{
"order_id": string,
"amount": double,
"products": [
object (Product),
...
],
"is_first_order": boolean,
"meta_data": object (MetaData),
"coupon": string,
"status": integer,
"recalculate": integer
}
پارامترها
نام | توضیحات |
order_id |
String شمارهی سفارش انجام شده؛ این پارامتر در کانورژنهایی با نوع فروش(sale) ارسال میشود. |
amount |
Double مبلغ کل سبد خرید؛ این پارامتر در کانورژنهایی با نوع فروش(sale) ارسال میشود. |
products |
لیست محصولات خریداری شده توسط مشتری؛ این پارامتر در کانورژنهایی با نوع فروش(sale) ارسال میشود. |
is_first_order |
Boolean پارامتر مشخصکننده اولین خرید |
meta_data |
آبجکت حاوی اطلاعات لید ثبت شده؛ این پارامتر در کانورژنهایی با نوع لید(lead) ارسال میشود. |
coupon |
String کد تخفیف استفاده شده در خرید؛ این پارامتر در کانورژنهایی با نوع فروش(sale) ارسال میشود. |
status |
وضعیت کانورژن که میتواند یکی از اعداد ۱(تایید شده)، ۲(رد شده) یا ۴(نیازمند بررسی دستی) باشد. |
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 |
وضعیت کانورژن که میتواند یکی از اعداد ۰(در انتظار تایید توسط سیستم)، ۱(تایید شده)، ۲(رد شده)، ۳(تکراری) یا ۴(نیازمند بررسی دستی) باشد. |
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
{
"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 | نام بازاریاب |
ثابتها
وضعیت کانورژن
۰ | در انتظار تایید توسط سیستم |
۱ | تایید شده |
۲ | تکراری |
۳ | نیازمند بررسی دستی |