توسعه‌دهندگان
در این بخش روش‌های مختلف پیاده‌سازی و استفاده از سرویس‌های ارائه شده به فروشگاه‌ها، توضیح داده خواهد شد.
اسکریپت ردیابی
در صورتی که تیم فنی شما امکان پیاده‌سازی سرویس‌ها را ندارد یا تمایلی به پیاده‌سازی API ندارید می‌توانید برای ردیابی خریدهای انجام شده از اسکریپت ردیابی افیلی استفاده کنید.
ردیابی لینک‌ها:
قطعه کد زیر را در تگ هد همه صفحات سایت خود قرار دهید.
ثبت مشتری:
در صورتی که ارائه دهنده سرویس SaaS هستید یا مشتری در ازای پرداخت حق عضویت از خدمات شما استفاده می‌کند و می‌خواهید در طول یک مدت زمان خاص یا برای تکرار خرید به بازاریاب پورسانت پرداخت کنید. نیاز است بعد از ثبت‌نام مشتری در سیستم شما از طریق قطعه کدی که در ادامه می‌آوریم، یک مشتری ایجاد کنید.
پس از اینکه مشتری در افیلی تعریف ثبت شد شناسه مشتری در افیلی توسط تابع callback بازگردانده می‌شود. شما باید این مقدار را در دیتابیس خود ذخیره کنید. در قطعه کد بالا متغیرهای customerId و metaData باید با مقادیر صحیح توسط شما پر شوند که توضیح هر کدام را در ادامه می‌دهیم.
customerId:
شناسه یکتای مشتری در سیستم شماست.
metaData:
آبجکتی حاوی اطلاعات اضافه راجع به مشتری است. ارسال این پارامتر اختیاری است.
تذکر: در صورتی که مشتری از سمت افیلی نباشد، دیتایی سمت افیلی ذخیره نشده و تابع callback نیز فراخوانی نمی‌شود.
ثبت فروش:
برای ثبت فروش‌های انجام شده در thank you page قطعه کد زیر را قرار دهید.
دقت داشته باشید در کد بالا متغیرهای uniqueSaleId ،saleAmount ،couponCode ،products و affiliCustomerId باید توسط شما با مقادیر صحیح پر شود؛ که توضیح هر کدام در زیر آمده است.
uniqueSaleId:
یک شناسه یکتاست که باید در سیستم خود برای هر فروش ایجاد کنید. شما باید این متغیر را با یک تگ یا متغیر واقعی جایگزین کنید تا مقدار مربوطه را در هر فروش به صورت خودکار مقداردهی کند. شناسه یکتا میتواند هر چیزی که برای شما معنادار است باشد و باید برای هر فروش نیز منحصربفرد باشد. به طور مثال: شماره سفارش، شماره تراکنش و ... پس از ثبت فروش می‌توانید این شناسه را در پنل افیلی بخش کانورژنها مشاهده کنید. این امر باعث می‌شود که مدیریت داده‌های موجود در افیلی و سیستم شما آسانتر شود.
saleAmount:
مبلغ کل فروش یا همان مبلغ پرداختی کاربر بابت خرید است. دقت داشته باشید مبلغ مربوط به کرایه حمل و نقل و مالیات نباید لحاظ شده باشد.
couponCode:
در صورتی که مشتری هنگام خرید از کد تخفیف استفاده کرده باشد کد تخفیف مربوطه را باید وارد کنید در غیر اینصورت با مقدار null پر شود.
products:
آرایه‌ای از محصولاتی است که توسط مشتری خریداری شده، که به صورت زیر پر می‌شود.
products = [
{
"name": "محصول نمونه",
"unit_price": 12000,
"quantity": 3,
"total_price": 36000
},
{
"name": "محصول نمونه شماره دو",
"unit_price": 43000,
"quantity": 1,
"total_price": 43000
}
]
affiliCusomerId:
شناسه یکتای مشتری در افیلی است. ارسال این پارامتر اختیاری است.
واحد پولی:
به صورت پیش‌فرض واحد پولی فروشگاه‌ها در افیلی ریال است در صورتی که از واحد پولی تومان استفاده می‌کنید به پشتیبانی فروشگاه‌ها اطلاع دهید تا واحد پولی شما تغییر کند.
ثبت لید:
برای ثبت لید هنگامی که اقدام مورد نظر رخ داد، قطعه کد زیر را فراخوانی کنید.
پارامتر form_id در متا دیتا برای هر فرم باید مقدار یکتایی داشته باشد. و ارسال آن الزامی است. این مقدار میتواند از نوع عدد یا یک رشته باشد. همچنین برای فرمهای لید همانند بالا می‌توانید سایر داده‌های فرم را در متغیر متا دیتا برای ما ارسال کنید. ارسال این اطلاعات برای تطبیق و جلوگیری از تقلب ناشران الزامی است.سرویس کانورژن
برای ردیابی و مدیرت کانورژنها و علاوه بر پیاده‌سازی اسکریپت می‌توانید از طریق 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
خیر
Array of Product Object
لیست محصولات خریداری شده توسط مشتری؛ این پارامتر در کانورژن‌هایی با نوع فروش(sale) ارسال می‌شود.
coupon
خیر
String
کد تخفیف استفاده شده در خرید
is_first_order
خیر
Boolean
پارامتر مشخص‌کننده اولین خرید
meta_data
بلی
MetaData Object
آبجکت حاوی اطلاعات لید ثبت شده؛ این پارامتر در کانورژن‌هایی با نوع لید(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
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)، نمایش داده می‌شود.
is_first_order
Boolean
پارامتر مشخص‌کننده اولین خرید
meta_data
MetaData Object
آبجکت حاوی اطلاعات لید ایجاد شده؛ این پارامتر تنها در کانورژن‌هایی از نوع لید(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
Array of Product Object
لیست محصولات خریداری شده توسط مشتری؛ این پارامتر در کانورژن‌هایی با نوع فروش(sale) ارسال می‌شود.
is_first_order
Boolean
پارامتر مشخص‌کننده اولین خرید
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
{
"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
نام بازاریاب
ثابت‌ها
وضعیت کانورژن
۰
در انتظار تایید توسط سیستم
۱
تایید شده
۲
تکراری
۳
نیازمند بررسی دستی
سرویس محصول
در صورتی که بخواهید لیست محصولات شما به بازاریابان نمایش داده شود یا برای دسته‌بندی‌ها و محصولات مختلف پورسانت‌های متفاوتی را از طریق پنل کاربری اعمال کنید؛ نیاز است که محصولات فروشگاه خود را درون‌ریزی کنید. می‌توانید از طریق پیاده‌سازی وب سرویس یا از طریق ست کردن وب هوک این کار را انجام دهید.
وب سرویس
پیش‌نیازها
برای استفاده، نیاز به ارسال Bearer توکن است. از طریق ارتباط با پشتیبانی می‌توانید توکن فروشگاه خود را دریافت کنید.
آدرس پایه ارسال درخواست‌ها
https://core.affili.ir/services/products
API محصولات
طبق توضیحات داده شده در جدول زیر، از API تعریف شده می‌توانید برای ایمپورت محصولات فروشگاه خود در افیلی استفاده کنید.
نوع عملیات
نوع درخواست
توضیحات
uri
درون‌ریزی
POST
درون‌ریزی محصولات؛ می‌توانید حداکثر ۱۰۰۰ محصول را در هر بار فراخوانی سرویس درون‌ریزی کنید. برای بروزرسانی هم می‌توانید از همین وب سرویس استفاده کنید.
/import
درون‌ریزی محصولات
آدرس ارسال درخواست
POST https://core.affili.ir/services/products/import
قالب درخواست درون‌ریزی
{
"products": [
object (Product),
...
]
}
پارامترها
نام
اجباری
توضیحات
products
بلی
Array of Product Object
لیست محصولات
وب هوک
کافی است APIای با قالب پاسخی مطابق زیر آماده کرده و در اختیار پشتیبانی قرار دهید. تا کار ست کردن وب هوک توسط پشتیبانی برای فروشگاه شما انجام شود.
{
"data": {
"products": [
object (Product),
...
]
},
"meta": {
"page": object (Page)
}
}
پارامترها
products
Product Object
لیست محصولات فروشگاه
page
Page Object
اطلاعات مربوط به صفحه دریافتی شامل شماره صفحه، تعداد آیتم‌ها در هر صفحه و ...
اعمال فیلتر
پیاده‌سازی بخش فیلتر نیازمند پیروی از قوانینی است که در ادامه به شرح آنها خواهیم پرداخت.
۱- قابلیت اعمال فیلتر روی تمامی آیتم‌‌های آبجکت محصول و دسته‌بندی باید فعال باشد.
۲- برای اعمال فیلتر روی مقادیر old_price ،price و last_update که می‌توانند به صورت بازه‌ای از مقادیر باشند؛ از پیشوند _min برای تعریف پارامتر ارسالی حداقل و از پیشوند _max برای تعریف پارامتر ارسالی حداکثر استفاده می‌شود. به طور مثال برای اعمال فیلتر روی قیمت محصول در صورتی که پارامتر min_price از سمت افیلی ارسال شود به معنای فیلتر محصولاتی است که قیمت آنها بزرگتر مساوی مقدار پارامتر min_price باشد. برای پارامتر max_price هم به طور مشابه منظور فیلتر محصولاتی است که قیمت آنها کمتر مساوی مقدار پارامتر max_price باشد.
صفحه‌بندی
برای پیمایش در صفحات از پارامتر page برای ارسال شماره صفحه مدنظر و از پارامتر per_page برای تعیین تعداد محصولات هر صفحه استفاده می‌شود.
موجودیت‌ها
product
قالب JSON
{
"pid": string,
"name": string,
"url": string,
"price": double,
"old_price": double,
"in_stock": boolean,
"images": [
string,
...
],
"categories": [
object (Category)
],
"created_at": dateTime,
"updated_at": datetime
}
پارامترها
pid
String
شناسه یکتای محصول در وبسایت فروشگاه
name
String
نام محصول
url
String
آدرس صفحه محصول در وبسایت فروشگاه
price
Double
قیمت محصول
old_price
Double
قیمت قدیمی محصولی؛ در صورتی که محصول قیمت قدیمی ندارد مقدار این پارامتر برابر با null می‌شود.
in_stock
Boolean
وضعیت موجود بودن محصول؛ که میتواند یکی از مقادیر 0، 1، true یا false را داشته باشد.
images
Array
آرایه‌ای از آدرس عکس‌های محصول
categories
Array of Category Object
لیست دسته‌بندی‌های محصول
created_at
DateTime
تاریخ ایجاد محصول
updated_at
DateTime
تاریخ آخرین بروزرسانی محصول
Category
قالب JSON
{
"cid": string,
"name": string,
"url": string,
"parent_cid": string,
"is_primary": boolean
}
پارامترها
cid
String
شناسه یکتای دسته‌بندی در وبسایت فروشگاه
name
String
نام دسته‌بندی
url
String
آدرس صفحه دسته‌بندی در وبسایت فروشگاه
parent_cid
String
دسته والد؛ در صورتی که دسته‌بندی، دسته والد ندارد مقدار این پارامتر برابر با null می‌شود.
is_primary
Boolean
دسته‌بندی شاخص؛ در صورتی که این دسته‌بندی، دسته‌بندی شاخص محصول است مقدار این پارامتر برابر با ۱ یا true و در غیر این صورت برابر با ۰ یا false می‌شود.
Page
قالب JSON
{
"current": integer,
"per": integer,
"last": integer,
"total": integer
}
پارامترها
current
Integer
شماره صفحه فعلی
per
Integer
تعداد محصولات در هر صفحه، مقدار این پارامتر میتواند حداکثر ۱۰۰۰ باشد.
last
Integer
شماره آخرین صفحه
total
Integer
تعداد کل محصولات
سرویس مشتری
در صورتی که ارائه دهنده سرویس SaaS هستید یا مشتری در ازای پرداخت حق عضویت از خدمات شما استفاده می‌کند و می‌خواهید در طول یک مدت زمان خاص یا برای تکرار خرید به بازاریاب پورسانت پرداخت کنید. نیاز است از طریق APIهای ارائه شده در این صفحه مشتریانی که از طریق بازاریابهای افیلی در سیستم شما ثبت نام می‌کنند را در افیلی تعریف کنید.
تعاریف
مشتری:
کاربری که برای استفاده از خدمات در سایت یا اپلیکیشن شما ثبت نام کرده است.
پیش‌نیازها
برای استفاده از سرویس‌های تعریف شده، نیاز به ارسال Bearer توکن است. از طریق ارتباط با پشتیبانی می‌توانید توکن دسترسی را دریافت کنید.
آدرس پایه ارسال درخواست‌ها
https://core.affili.ir/services/customers
API مشتری‌ها
طبق توضیحات داده شده در جدول زیر، از سه API تعریف شده می‌توانید برای ایجاد، ویرایش و دریافت مشتری‌ها استفاده کنید.
نوع عملیات
نوع درخواست
توضیحات
uri
ایجاد
POST
ایجاد مشتری جدید
ویرایش
POST
ویرایش مشتری ایجاد شده؛ customerId شناسه مشتری ایجاد شده در افیلی است.
/{customerId}
لیست
GET
دریافت لیست مشتری‌های ثبت شده
ایجاد مشتری
بعد از اینکه کاربر از طریق لینک افیلیت وارد وبسایت شما شد پارامتر referrer را به مدت زمان طول دوره کوکی (مقدار پارامتر exp)، در کوکی مرورگر وی ذخیره می‌کنیم.
بعد از ثبت نام کاربر، از طریق API مربوط به ایجاد مشتری اطلاعات مربوطه به افیلی ارسال می‌شود. همچنین دقت داشته باشید که مقدار شناسه مشتری در افیلی باید توسط شما ذخیره گردد تا در زمان ثبت کانورژن بتوانید از آن استفاده کنید. در ادامه به بررسی نمونه دیتای ارسالی و دریافتی در ایجاد مشتری خواهیم پرداخت.
آدرس ارسال درخواست
POST https://core.affili.ir/services/customers
قالب درخواست ایجاد مشتری
{
"referrer": string,
"mcs_id": string,
"meta_data": object (MetaData)
}
پارامترها
نام
اجباری
توضیحات
referrer
بلی
String
توکن ارجاع که قبلا در مرورگر کاربر ذخیر شده.
mcs_id
بلی
String
شناسه یکتای مشتری در سیستم شما
meta_data
خیر
MetaData Object
آبجکت حاوی اطلاعات اضافه راجع به مشتری
قالب پاسخ ایجاد مشتری
{
"status": "ok",
"tag": "saveCustomer",
"api_version": "1.0.0",
"data": {
"id": string,
"mcs_id": string,
"meta_data": object (MetaData)
"created_at": dateTime,
"updated_at": dateTime,
"publisher": object (Publisher)
}
}
پارامترها
نام
توضیحات
id
String
شناسه یکتای مشتری ایجاد شده در افیلی
mcs_id
String
شناسه مشتری در سیستم شما
meta_data
MetaData Object
آبجکت حاوی اطلاعات اضافه راجع به مشتری
publisher
Publisher Object
آبجکت حاوی اطلاعات بازاریاب
created_at
DateTime
تاریخ ایجاد
updated_at
DateTime
تاریخ آخرین بروزرسانی
ویرایش مشتری
برای تغییر در اطلاعات مشتری می‌توانید از API زیر استفاده کنید.
POST https://core.affili.ir/services/customers/{customerId}
*پارامتر customerId در آدرس، شناسه مشتری ثبت شده در افیلی است.
قالب درخواست ویرایش مشتری
{
"mcs_id": string,
"meta_data": object (MetaData)
}
لیست مشتری‌ها
برای دریافت لیست مشتری‌های ثبت شده از API زیر استفاده کنید.
آدرس ارسال درخواست
GET https://core.affili.ir/services/customers
قالب پارامترهای ارسالی برای اعمال فیلتر
{
"id": string,
"mcs_id" string,
"min_created_at": dateTime,
"max_created_at": dateTime,
"min_updated_at": dateTime,
"max_updated_at": dateTime,
"publisher_id": integer
}
موجودیت‌ها
Meta Data
قالب JSON
{
"first_name": string,
"last_name": string,
"mobile": string,
"email": string
// Any other fields can be added as extra data.
}
Publisher
قالب JSON
{
"id": string,
"full_name": string
}پیاده‌سازی برای سایت‌ساز پرتال
برای پیاده‌سازی کافی است فایل payment.html را مطابق زیر تغییر دهید.
سرویس ساب دامنه
برای پیاده‌سازی سرویس ساب دامنه بعد از خرید و فعال‌سازی سرویس، می‌توانید برای ردیابی خریدهای انجام شده از اسکریپت ردیابی افیلی استفاده کنید.
ردیابی لینک‌ها:
قطعه کد زیر را در تگ هد همه صفحات سایت خود قرار دهید.
ثبت مشتری:
در صورتی که ارائه دهنده سرویس SaaS هستید یا مشتری در ازای پرداخت حق عضویت از خدمات شما استفاده می‌کند و می‌خواهید در طول یک مدت زمان خاص یا برای تکرار خرید به بازاریاب پورسانت پرداخت کنید. نیاز است بعد از ثبت‌نام مشتری در سیستم شما از طریق قطعه کدی که در ادامه می‌آوریم، یک مشتری ایجاد کنید.
پس از اینکه مشتری در سرویس ثبت شد شناسه مشتری توسط تابع callback بازگردانده می‌شود. شما باید این مقدار را در دیتابیس خود ذخیره کنید. در قطعه کد بالا متغیرهای customerId و metaData باید با مقادیر صحیح توسط شما پر شوند که توضیح هر کدام را در ادامه می‌دهیم.
customerId:
شناسه یکتای مشتری در سیستم شماست.
metaData:
آبجکتی حاوی اطلاعات اضافه راجع به مشتری است. ارسال این پارامتر اختیاری است.
تذکر: در صورتی که مشتری از سمت بازاریاب نباشد، دیتایی سمت سرویس ذخیره نشده و تابع callback نیز فراخوانی نمی‌شود.
ثبت فروش:
برای ثبت فروش‌های انجام شده در thank you page قطعه کد زیر را قرار دهید.
دقت داشته باشید در کد بالا متغیرهای uniqueSaleId ،saleAmount ،couponCode ،products و adTrackCustomerId باید توسط شما با مقادیر صحیح پر شود؛ که توضیح هر کدام در زیر آمده است.
uniqueSaleId:
یک شناسه یکتاست که باید در سیستم خود برای هر فروش ایجاد کنید. شما باید این متغیر را با یک تگ یا متغیر واقعی جایگزین کنید تا مقدار مربوطه را در هر فروش به صورت خودکار مقداردهی کند. شناسه یکتا میتواند هر چیزی که برای شما معنادار است باشد و باید برای هر فروش نیز منحصربفرد باشد. به طور مثال: شماره سفارش، شماره تراکنش و ... پس از ثبت فروش می‌توانید این شناسه را در پنل افیلی بخش کانورژنها مشاهده کنید. این امر باعث می‌شود که مدیریت داده‌های موجود در افیلی و سیستم شما آسانتر شود.
saleAmount:
مبلغ کل فروش یا همان مبلغ پرداختی کاربر بابت خرید است. دقت داشته باشید مبلغ مربوط به کرایه حمل و نقل و مالیات نباید لحاظ شده باشد.
couponCode:
در صورتی که مشتری هنگام خرید از کد تخفیف استفاده کرده باشد کد تخفیف مربوطه را باید وارد کنید در غیر اینصورت با مقدار null پر شود.
products:
آرایه‌ای از محصولاتی است که توسط مشتری خریداری شده، که به صورت زیر پر می‌شود.
products = [
{
"name": "محصول نمونه",
"unit_price": 12000,
"quantity": 3,
"total_price": 36000
},
{
"name": "محصول نمونه شماره دو",
"unit_price": 43000,
"quantity": 1,
"total_price": 43000
}
]
adTrackCusomerId:
شناسه یکتای مشتری در افیلی است. ارسال این پارامتر اختیاری است.
واحد پولی:
به صورت پیش‌فرض واحد پولی فروشگاه‌ها ریال است در صورتی که از واحد پولی تومان استفاده می‌کنید به پشتیبانی فروشگاه‌ها اطلاع دهید تا واحد پولی شما تغییر کند.
ثبت لید:
برای ثبت لید هنگامی که اقدام مورد نظر رخ داد، قطعه کد زیر را فراخوانی کنید.
پارامتر form_id در متا دیتا برای هر فرم باید مقدار یکتایی داشته باشد. و ارسال آن الزامی است. این مقدار میتواند از نوع عدد یا یک رشته باشد. همچنین برای فرمهای لید همانند بالا می‌توانید سایر داده‌های فرم را در متغیر متا دیتا برای ما ارسال کنید. ارسال این اطلاعات برای تطبیق و جلوگیری از تقلب ناشران الزامی است.