# توسعهدهندگان در این بخش روشهای مختلف پیادهسازی و استفاده از سرویسهای ارائه شده به فروشگاهها، توضیح داده خواهد شد. # اسکریپت ردیابی در صورتی که تیم فنی شما امکان پیادهسازی سرویسها را ندارد یا تمایلی به پیادهسازی API ندارید میتوانید برای ردیابی خریدهای انجام شده از اسکریپت ردیابی افیلی استفاده کنید. ### **ردیابی لینکها:** قطعه کد زیر را در تگ هد همه صفحات سایت خود قرار دهید. ```html ``` ### **ثبت مشتری:** در صورتی که ارائه دهنده سرویس SaaS هستید یا مشتری در ازای پرداخت حق عضویت از خدمات شما استفاده میکند و میخواهید در طول یک مدت زمان خاص یا برای تکرار خرید به بازاریاب پورسانت پرداخت کنید. نیاز است بعد از ثبتنام مشتری در سیستم شما از طریق قطعه کدی که در ادامه میآوریم، یک مشتری ایجاد کنید. ```html ``` پس از اینکه مشتری در افیلی تعریف ثبت شد شناسه مشتری در افیلی توسط تابع callback بازگردانده میشود. شما باید این مقدار را در دیتابیس خود ذخیره کنید. در قطعه کد بالا متغیرهای **customerId** و **metaData** باید با مقادیر صحیح توسط شما پر شوند که توضیح هر کدام را در ادامه میدهیم. customerId: شناسه یکتای مشتری در سیستم شماست. metaData: آبجکتی حاوی اطلاعات اضافه راجع به مشتری است. ارسال این پارامتر **اختیاری** است.
تذکر: در صورتی که مشتری از سمت افیلی نباشد، دیتایی سمت افیلی ذخیره نشده و تابع callback نیز فراخوانی نمیشود.
### **ثبت فروش:** برای ثبت فروشهای انجام شده در thank you page قطعه کد زیر را قرار دهید. ```html ``` دقت داشته باشید در کد بالا متغیرهای **uniqueSaleId** ،**saleAmount** ،**couponCode** ،**products** و **affiliCustomerId** باید توسط شما با مقادیر صحیح پر شود؛ که توضیح هر کدام در زیر آمده است. ##### uniqueSaleId: یک شناسه یکتاست که باید در سیستم خود برای هر فروش ایجاد کنید. شما باید این متغیر را با یک تگ یا متغیر واقعی جایگزین کنید تا مقدار مربوطه را در هر فروش به صورت خودکار مقداردهی کند. شناسه یکتا میتواند هر چیزی که برای شما معنادار است باشد و باید برای هر فروش نیز منحصربفرد باشد. به طور مثال: شماره سفارش، شماره تراکنش و ... پس از ثبت فروش میتوانید این شناسه را در پنل افیلی بخش کانورژنها مشاهده کنید. این امر باعث میشود که مدیریت دادههای موجود در افیلی و سیستم شما آسانتر شود. ##### saleAmount: مبلغ کل فروش یا همان مبلغ پرداختی کاربر بابت خرید است. دقت داشته باشید مبلغ مربوط به کرایه حمل و نقل و مالیات نباید لحاظ شده باشد. ##### couponCode: در صورتی که مشتری هنگام خرید از کد تخفیف استفاده کرده باشد کد تخفیف مربوطه را باید وارد کنید در غیر اینصورت با مقدار null پر شود. ##### products: آرایهای از محصولاتی است که توسط مشتری خریداری شده، که به صورت زیر پر میشود. ```javascript products = [ { "name": "محصول نمونه", "unit_price": 12000, "quantity": 3, "total_price": 36000 }, { "name": "محصول نمونه شماره دو", "unit_price": 43000, "quantity": 1, "total_price": 43000 } ] ``` affiliCusomerId: شناسه یکتای مشتری در افیلی است. ارسال این پارامتر اختیاری است. #### واحد پولی: به صورت پیشفرض واحد پولی فروشگاهها در افیلی ریال است در صورتی که از واحد پولی تومان استفاده میکنید به پشتیبانی فروشگاهها اطلاع دهید تا واحد پولی شما تغییر کند. ### **ثبت لید:** برای ثبت لید هنگامی که اقدام مورد نظر رخ داد، قطعه کد زیر را فراخوانی کنید. ```html ``` پارامتر **form\_id** در متا دیتا برای هر فرم باید مقدار یکتایی داشته باشد. و ارسال آن الزامی است. این مقدار میتواند از نوع عدد یا یک رشته باشد. همچنین برای فرمهای لید همانند بالا میتوانید سایر دادههای فرم را در متغیر متا دیتا برای ما ارسال کنید. ارسال این اطلاعات برای تطبیق و جلوگیری از تقلب ناشران الزامی است. # سرویس کانورژن برای ردیابی و مدیرت کانورژنها و علاوه بر پیادهسازی اسکریپت میتوانید از طریق APIهای سرویس کانورژن، اقدام به پیادهسازی سرویس همکاری در فروش نمایید. در ادامه به بررسی APIهای این سرویس و نحوه استفاده از آنها خواهیم پرداخت. ## **تعاریف** ### لینک افیلیت به لینک کوتاه شدهای که توسط بازاریاب در افیلی ساخته میشود و مشتری پس از کلیک روی آن به وبسایت شما ارجاع داده میشود لینک افیلیت میگویند. هر لینک افیلیت پس از ارجاع به وبسایت فروشگاه شامل پارامترهای زیر خواهد بود. - referrer: توکنی است که در هر بار ارجاع، به لینک ارجاع اختصاص داده میشود. این توکن مقدار یکتایی دارد و برای صحت سنجی کلیکها مورد استفاده قرار میگیرید. - exp: تعداد روزهای اعتبار کوکی در مرورگر کاربر است. - dl: این پارامتر مشخص کننده تعداد دفعات مجاز ثبت کانورژن برای بازاریاب ارجاعدهنده خواهد بود. به عبارت دیگر این مقدار به ما میگوید تا چند بار در صورت خرید مشتری به بازاریاب پورسانت تعلق خواهد گرفت. **نکته:** مقدار 1- به معنای نامحدود است. و در صورت اعمال تا زمان معتبر بودن کوکی در صورت خرید مشتری به بازاریاب پورسانت تعلق میگیرد. ### کانورژن به هر اقدامی که فروشگاه در ازای آن به بازاریاب پورسانت پرداخت میکند کانورژن میگویند. افیلی دو نوع کانورژن فروش و لید را پشتیبانی میکند. ### دوره کوکی مدت زمانی است که لینک افیلیت معتبر بوده و در صورت تحقق کانورژن در این بازه زمانی به بازاریاب پورسانت تعلق خواهد گرفت. ### دوره مرجوعی مدت زمانی است که پس از ایجاد کانورژن امکان ویرایش آن وجود دارد. پس از این مدت زمان کانورژن لاک شده و در اولین سیکل بررسی کانورژنهای لاک شده، پورسانت آن از حساب فروشگاه کسر و به بازاریاب پرداخت خواهد شد. ## **پیشنیازها** برای استفاده از سرویسهای تعریف شده، نیاز به ارسال **Bearer** توکن است. از طریق ارتباط با پشتیبانی میتوانید توکن دسترسی را دریافت کنید. ## **آدرس پایه ارسال درخواستها** ``` https://core.affili.ir/services/conversions ``` ## **API کانورژنها** طبق توضیحات داده شده در جدول زیر، از سه API تعریف شده میتوانید برای ایجاد، ویرایش و دریافت کانورژنها استفاده کنید.**نوع عملیات** | **نوع درخواست** | **توضیحات** | **uri** |
ایجاد | POST | ایجاد کانورژن جدید | / |
ویرایش | POST | ویرایش کانورژن ایجاد شده؛ conversionId شناسه کانورژن ایجاد شده در افیلی است. | /{conversionId} |
لیست | GET | دریافت لیست کانورژنهای ثبت شده | / |
**تذکر: در صورتی که از قبل مشتری را تعریف کرده باشید و در API کانورژن شناسه مشتری را ارسال کنید نیازی به ارسال referrer نیست.**
#### آدرس ارسال درخواست ``` POST https://core.affili.ir/services/conversions ``` #### قالب درخواست ایجاد کانورژن ```json { "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](#bkmrk-product-object)** لیست محصولات خریداری شده توسط مشتری؛ این پارامتر در کانورژنهایی با نوع فروش(sale) ارسال میشود. |
coupon | خیر | **String** کد تخفیف استفاده شده در خرید |
is\_first\_order | خیر | **Boolean** پارامتر مشخصکننده اولین خرید |
meta\_data | بلی | [**MetaData Object**](#bkmrk-meta-data-object) آبجکت حاوی اطلاعات لید ثبت شده؛ این پارامتر در کانورژنهایی با نوع لید(lead) ارسال میشود. |
customer\_id | خیر | **String** شناسه یکتای مشتری در افیلی |
**نام** | **توضیحات** |
id | **String** شناسه یکتای کانورژن ایجاد شده در افیلی |
publisher | **[Publisher Object](#bkmrk-publisher-object)** آبجکت مربوط به اطلاعات بازاریاب. |
status | **[Conversion Status Constant](#bkmrk-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](#bkmrk-product-object)** لیست محصولات خریداری شده توسط مشتری؛ این پارامتر تنها در صورتی که کانورژن از نوع فروش(sale)، نمایش داده میشود. |
is\_first\_order | **Boolean** پارامتر مشخصکننده اولین خرید |
meta\_data | [**MetaData Object**](#bkmrk-meta-data-object) آبجکت حاوی اطلاعات لید ایجاد شده؛ این پارامتر تنها در کانورژنهایی از نوع لید(lead) نمایش میشود. |
coupon | **String** کد تخفیف استفاده شده در خرید؛ این پارامتر تنها در صورتی که کانورژن از نوع فروش(sale)، نمایش داده میشود. |
created\_at | **DateTime** تاریخ ایجاد |
updated\_at | **DateTime** تاریخ آخرین بروزرسانی |
currency | **String** واحد پولی کانورژن ثبت شده که میتواند یکی از مقادیر IRT(تومان) یا IRR(ریال) باشد. |
customer\_id | **String** شناسه یکتای مشتری در افیلی |
**نام** | **توضیحات** |
order\_id | **String** شمارهی سفارش انجام شده؛ این پارامتر در کانورژنهایی با نوع فروش(sale) ارسال میشود. |
amount | **Double** مبلغ کل سبد خرید؛ این پارامتر در کانورژنهایی با نوع فروش(sale) ارسال میشود. |
products | **[Array of Product Object](#bkmrk-product-object)** لیست محصولات خریداری شده توسط مشتری؛ این پارامتر در کانورژنهایی با نوع فروش(sale) ارسال میشود. |
is\_first\_order | **Boolean** پارامتر مشخصکننده اولین خرید |
meta\_data | [**MetaData Object**](#bkmrk-meta-data-object) آبجکت حاوی اطلاعات لید ثبت شده؛ این پارامتر در کانورژنهایی با نوع لید(lead) ارسال میشود. |
coupon | **String** کد تخفیف استفاده شده در خرید؛ این پارامتر در کانورژنهایی با نوع فروش(sale) ارسال میشود. |
status | **[Conversion Status Constant](#bkmrk-conversion-status-constant)** وضعیت کانورژن که میتواند یکی از اعداد ۱(تایید شده)، ۲(رد شده) یا ۴(نیازمند بررسی دستی) باشد. |
recalculate | **Boolean** در صورت ویرایش پارامترهای تاثیرگذار در محاسبه پورسانت همانند مبلغ کل سبد خرید، محصولات خریداری شده و ... برای محاسبه مجدد پورسانت باید پارامتر recalculate برابر با مقدار یک یا true باشد. |
**نام** | **توضیحات** |
id | **String** شناسه یکتای کانورژن در افیلی |
status | **[Conversion Status Constant](#bkmrk-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** حداکثر تاریخ ایجاد کانورژن؛ این پارامتر برای فیلتر کانورژنهایی با مبلغ سبد خرید کمتر یا مساوی این مقدار استفاده میشود. |
name | **String** نام محصول |
unit\_price | **Double** قیمت واحد محصول در سبد خرید |
quantity | **Integer** تعداد محصول در سبد خرید |
total\_price | **Double** مجموع قیمت محصول در سبد خرید |
form\_id | **String** شناسه یکتای فرم مربوطه در وبسایت فروشگاه |
uniq\_param | **String** پارامتر یکتای لید ثبت شده که میتواند دادهای نظیر شماره موبایل، ایمیل، کد ملی یا هر مقدار یکتای دیگری در فرم باشد. |
id | شناسه یکتای بازاریاب در افیلی |
full\_name | نام بازاریاب |
۰ | در انتظار تایید توسط سیستم |
۱ | تایید شده |
۲ | تکراری |
۳ | نیازمند بررسی دستی |
**نوع عملیات** | **نوع درخواست** | **توضیحات** | **uri** |
درونریزی | POST | درونریزی محصولات؛ میتوانید حداکثر ۱۰۰۰ محصول را در هر بار فراخوانی سرویس درونریزی کنید. برای بروزرسانی هم میتوانید از همین وب سرویس استفاده کنید. | /import |
**نام** | **اجباری** | **توضیحات** |
products | بلی | [**Array of Product Object**](#bkmrk-product) لیست محصولات |
products | [**Product Object**](#bkmrk-product) لیست محصولات فروشگاه |
page | [**Page Object**](#bkmrk-page) اطلاعات مربوط به صفحه دریافتی شامل شماره صفحه، تعداد آیتمها در هر صفحه و ... |
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**](#bkmrk-category) لیست دستهبندیهای محصول |
created\_at | **DateTime** تاریخ ایجاد محصول |
updated\_at | **DateTime** تاریخ آخرین بروزرسانی محصول |
cid | **String** شناسه یکتای دستهبندی در وبسایت فروشگاه |
name | **String** نام دستهبندی |
url | **String** آدرس صفحه دستهبندی در وبسایت فروشگاه |
parent\_cid | **String** دسته والد؛ در صورتی که دستهبندی، دسته والد ندارد مقدار این پارامتر برابر با **null** میشود. |
is\_primary | **Boolean** دستهبندی شاخص؛ در صورتی که این دستهبندی، دستهبندی شاخص محصول است مقدار این پارامتر برابر با ۱ یا true و در غیر این صورت برابر با ۰ یا false میشود. |
current | **Integer** شماره صفحه فعلی |
per | **Integer** تعداد محصولات در هر صفحه، مقدار این پارامتر میتواند حداکثر ۱۰۰۰ باشد. |
last | **Integer** شماره آخرین صفحه |
total | **Integer** تعداد کل محصولات |
**نوع عملیات** | **نوع درخواست** | **توضیحات** | **uri** |
ایجاد | POST | ایجاد مشتری جدید | |
ویرایش | POST | ویرایش مشتری ایجاد شده؛ customerId شناسه مشتری ایجاد شده در افیلی است. | /{customerId} |
لیست | GET | دریافت لیست مشتریهای ثبت شده |
**نام** | **اجباری** | **توضیحات** |
referrer | بلی | **String** توکن ارجاع که قبلا در مرورگر کاربر ذخیر شده. |
mcs\_id | بلی | **String** شناسه یکتای مشتری در سیستم شما |
meta\_data | خیر | [**MetaData Object**](#bkmrk-publisher) آبجکت حاوی اطلاعات اضافه راجع به مشتری |
**نام** | **توضیحات** |
id | **String** شناسه یکتای مشتری ایجاد شده در افیلی |
mcs\_id | **String** شناسه مشتری در سیستم شما |
meta\_data | [**MetaData Object**](#bkmrk-publisher) آبجکت حاوی اطلاعات اضافه راجع به مشتری |
publisher | [**Publisher Object**](#bkmrk-publisher) آبجکت حاوی اطلاعات بازاریاب |
created\_at | **DateTime** تاریخ ایجاد |
updated\_at | **DateTime** تاریخ آخرین بروزرسانی |
تذکر: در صورتی که مشتری از سمت بازاریاب نباشد، دیتایی سمت سرویس ذخیره نشده و تابع callback نیز فراخوانی نمیشود.
### **ثبت فروش:** برای ثبت فروشهای انجام شده در thank you page قطعه کد زیر را قرار دهید. ```html ``` دقت داشته باشید در کد بالا متغیرهای **uniqueSaleId** ،**saleAmount** ،**couponCode** ،**products** و **adtrackCustomerId** باید توسط شما با مقادیر صحیح پر شود؛ که توضیح هر کدام در زیر آمده است. ##### uniqueSaleId: یک شناسه یکتاست که باید در سیستم خود برای هر فروش ایجاد کنید. شما باید این متغیر را با یک تگ یا متغیر واقعی جایگزین کنید تا مقدار مربوطه را در هر فروش به صورت خودکار مقداردهی کند. شناسه یکتا میتواند هر چیزی که برای شما معنادار است باشد و باید برای هر فروش نیز منحصربفرد باشد. به طور مثال: شماره سفارش، شماره تراکنش و ... پس از ثبت فروش میتوانید این شناسه را در پنل افیلی بخش کانورژنها مشاهده کنید. این امر باعث میشود که مدیریت دادههای موجود در افیلی و سیستم شما آسانتر شود. ##### saleAmount: مبلغ کل فروش یا همان مبلغ پرداختی کاربر بابت خرید است. دقت داشته باشید مبلغ مربوط به کرایه حمل و نقل و مالیات نباید لحاظ شده باشد. ##### couponCode: در صورتی که مشتری هنگام خرید از کد تخفیف استفاده کرده باشد کد تخفیف مربوطه را باید وارد کنید در غیر اینصورت با مقدار null پر شود. ##### products: آرایهای از محصولاتی است که توسط مشتری خریداری شده، که به صورت زیر پر میشود. ```javascript products = [ { "name": "محصول نمونه", "unit_price": 12000, "quantity": 3, "total_price": 36000 }, { "name": "محصول نمونه شماره دو", "unit_price": 43000, "quantity": 1, "total_price": 43000 } ] ``` adtrackCusomerId: شناسه یکتای مشتری در افیلی است. ارسال این پارامتر اختیاری است. #### واحد پولی: به صورت پیشفرض واحد پولی فروشگاهها ریال است در صورتی که از واحد پولی تومان استفاده میکنید به پشتیبانی فروشگاهها اطلاع دهید تا واحد پولی شما تغییر کند. ### **ثبت لید:** برای ثبت لید هنگامی که اقدام مورد نظر رخ داد، قطعه کد زیر را فراخوانی کنید. ```html ``` پارامتر **form\_id** در متا دیتا برای هر فرم باید مقدار یکتایی داشته باشد. و ارسال آن الزامی است. این مقدار میتواند از نوع عدد یا یک رشته باشد. همچنین برای فرمهای لید همانند بالا میتوانید سایر دادههای فرم را در متغیر متا دیتا برای ما ارسال کنید. ارسال این اطلاعات برای تطبیق و جلوگیری از تقلب ناشران الزامی است.