# توسعه‌دهندگان در این بخش روش‌های مختلف پیاده‌سازی و استفاده از سرویس‌های ارائه شده به فروشگاه‌ها، توضیح داده خواهد شد. # اسکریپت ردیابی در صورتی که تیم فنی شما امکان پیاده‌سازی سرویس‌ها را ندارد یا تمایلی به پیاده‌سازی 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دریافت لیست کانورژن‌های ثبت شده/
### ایجاد کانورژن بعد از اینکه مشتری از طریق لینک افیلیت وارد وبسایت شما شد پارامترهای **referrer** و **dl** را به مدت زمان طول دوره کوکی (مقدار پارامتر exp)، در کوکی مرورگر کاربر ذخیره می‌کنیم. بعد از تحقق کانورژن (به طور مثال انجام خرید توسط مشتری) از طریق API ایجاد کانورژن، اطلاعات مربوطه به افیلی ارسال می‌شود. در ادامه به بررسی نمونه دیتای ارسالی و دریافتی در ایجاد کانورژن‌های فروش و لید خواهیم پرداخت.

**تذکر: در صورتی که از قبل مشتری را تعریف کرده باشید و در 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** شناسه یکتای مشتری در افیلی
#### قالب پاسخ ایجاد کانورژن ```json { "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](#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** شناسه یکتای مشتری در افیلی
#### درخواست نمونه برای ایجاد کانورژن از نوع فروش ```json { "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 } ``` #### پاسخ نمونه برای ایجاد کانورژن از نوع فروش ```json { "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 } } ``` #### درخواست نمونه برای ایجاد کانورژن از نوع لید ```json { "referrer": "63abe5089bf8325c1a3a231a", "type": "lead", "meta_data": { "form_id": "register-form", "uniq_param": "09123456789", "first_name": "First Name", "last_name": "Last Name" } } ``` #### پاسخ نمونه برای ایجاد کانورژن از نوع لید ```json { "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 } } ``` ### ویرایش کانورژن می‌توانید تا قبل از پایان دوره مرجوعی و لاک شدن کانورژن، آن را ویرایش کنید. دقت داشته باشید که بعد از لاک شدن امکان اعمال تغییرات وجود نخواهد داشت. #### آدرس ارسال درخواست ```markdown POST https://core.affili.ir/services/conversions/{conversionId} ``` \*پارامتر conversionId در آدرس، شناسه کانورژن ثبت شده در افیلی است. #### قالب درخواست ویرایش کانورژن ```json { "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](#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 باشد.
### لیست کانورژن‌ها برای دریافت لیست کانورژن‌های ثبت شده از API زیر استفاده کنید. #### آدرس ارسال درخواست ```markdown GET https://core.affili.ir/services/conversions ``` #### قالب پارامترهای ارسالی برای اعمال فیلتر ```json { "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](#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** حداکثر تاریخ ایجاد کانورژن؛ این پارامتر برای فیلتر کانورژن‌هایی با مبلغ سبد خرید کمتر یا مساوی این مقدار استفاده می‌شود.
## **موجودیت‌ها** ### 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نام بازاریاب
## **ثابت‌ها** ### وضعیت کانورژن
۰در انتظار تایید توسط سیستم
۱تایید شده
۲تکراری
۳نیازمند بررسی دستی
# سرویس محصول در صورتی که بخواهید لیست محصولات شما به بازاریابان نمایش داده شود یا برای دسته‌بندی‌ها و محصولات مختلف پورسانت‌های متفاوتی را از طریق پنل کاربری اعمال کنید؛ نیاز است که محصولات فروشگاه خود را درون‌ریزی کنید. می‌توانید از طریق پیاده‌سازی وب سرویس یا از طریق ست کردن وب هوک این کار را انجام دهید. ## **وب سرویس** ### پیش‌نیازها برای استفاده، نیاز به ارسال **Bearer** توکن است. از طریق ارتباط با پشتیبانی می‌توانید توکن فروشگاه خود را دریافت کنید. ### آدرس پایه ارسال درخواست‌ها ``` https://core.affili.ir/services/products ``` ### API محصولات طبق توضیحات داده شده در جدول زیر، از API تعریف شده می‌توانید برای ایمپورت محصولات فروشگاه خود در افیلی استفاده کنید.
**نوع عملیات****نوع درخواست****توضیحات****uri**
درون‌ریزیPOSTدرون‌ریزی محصولات؛ می‌توانید حداکثر ۱۰۰۰ محصول را در هر بار فراخوانی سرویس درون‌ریزی کنید. برای بروزرسانی هم می‌توانید از همین وب سرویس استفاده کنید./import
#### درون‌ریزی محصولات ##### آدرس ارسال درخواست ``` POST https://core.affili.ir/services/products/import ``` ##### قالب درخواست درون‌ریزی ```json { "products": [ object (Product), ... ] } ``` ##### پارامترها
**نام****اجباری****توضیحات**
productsبلی[**Array of Product Object**](#bkmrk-product) لیست محصولات
## **وب هوک** کافی است API‌ای با قالب پاسخی مطابق زیر آماده کرده و در اختیار پشتیبانی قرار دهید. تا کار ست کردن وب هوک توسط پشتیبانی برای فروشگاه شما انجام شود. ```json { "data": { "products": [ object (Product), ... ] }, "meta": { "page": object (Page) } } ``` ### پارامترها
products[**Product Object**](#bkmrk-product) لیست محصولات فروشگاه
page[**Page Object**](#bkmrk-page) اطلاعات مربوط به صفحه دریافتی شامل شماره صفحه، تعداد آیتم‌ها در هر صفحه و ...
### اعمال فیلتر پیاده‌سازی بخش فیلتر نیازمند پیروی از قوانینی است که در ادامه به شرح آن‌ها خواهیم پرداخت. ۱- قابلیت اعمال فیلتر روی تمامی آیتم‌‌های آبجکت محصول و دسته‌بندی باید فعال باشد. ۲- برای اعمال فیلتر روی مقادیر **old\_price** ،**price** و **last\_update** که می‌توانند به صورت بازه‌ای از مقادیر باشند؛ از پیشوند **\_min** برای تعریف پارامتر ارسالی حداقل و از پیشوند **\_max** برای تعریف پارامتر ارسالی حداکثر استفاده می‌شود. به طور مثال برای اعمال فیلتر روی قیمت محصول در صورتی که پارامتر **min\_price** از سمت افیلی ارسال شود به معنای فیلتر محصولاتی است که قیمت آنها بزرگتر مساوی مقدار پارامتر **min\_price** باشد. برای پارامتر **max\_price** هم به طور مشابه منظور فیلتر محصولاتی است که قیمت آنها کمتر مساوی مقدار پارامتر **max\_price** باشد. ### صفحه‌بندی برای پیمایش در صفحات از پارامتر **page** برای ارسال شماره صفحه مدنظر و از پارامتر **per\_page** برای تعیین تعداد محصولات هر صفحه استفاده می‌شود. ## **موجودیت‌ها** ### product #### قالب JSON ```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**](#bkmrk-category) لیست دسته‌بندی‌های محصول
created\_at**DateTime** تاریخ ایجاد محصول
updated\_at**DateTime** تاریخ آخرین بروزرسانی محصول
### Category #### قالب JSON ```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 ```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 ``` #### قالب درخواست ایجاد مشتری ```json { "referrer": string, "mcs_id": string, "meta_data": object (MetaData) } ``` #### پارامترها
**نام****اجباری****توضیحات**
referrerبلی**String** توکن ارجاع که قبلا در مرورگر کاربر ذخیر شده.
mcs\_idبلی**String** شناسه یکتای مشتری در سیستم شما
meta\_dataخیر[**MetaData Object**](#bkmrk-publisher) آبجکت حاوی اطلاعات اضافه راجع به مشتری
#### قالب پاسخ ایجاد مشتری ```json { "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**](#bkmrk-publisher) آبجکت حاوی اطلاعات اضافه راجع به مشتری
publisher[**Publisher Object**](#bkmrk-publisher) آبجکت حاوی اطلاعات بازاریاب
created\_at**DateTime** تاریخ ایجاد
updated\_at**DateTime** تاریخ آخرین بروزرسانی
### ویرایش مشتری برای تغییر در اطلاعات مشتری می‌توانید از API زیر استفاده کنید. ```markdown POST https://core.affili.ir/services/customers/{customerId} ``` \*پارامتر customerId در آدرس، شناسه مشتری ثبت شده در افیلی است. #### قالب درخواست ویرایش مشتری ```json { "mcs_id": string, "meta_data": object (MetaData) } ``` ### لیست مشتری‌ها برای دریافت لیست مشتری‌های ثبت شده از API زیر استفاده کنید. #### آدرس ارسال درخواست ```markdown GET https://core.affili.ir/services/customers ``` #### قالب پارامترهای ارسالی برای اعمال فیلتر ```json { "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 ```json { "first_name": string, "last_name": string, "mobile": string, "email": string // Any other fields can be added as extra data. } ``` ### Publisher #### قالب JSON ```json { "id": string, "full_name": string } ``` # پیاده‌سازی برای سایت‌ساز پرتال برای پیاده‌سازی کافی است فایل payment.html را مطابق زیر تغییر دهید. ```html

@@title

لطفا از طریق فرم زیر اقدام به پرداخت سفارش کنید.
پرداخت سفارش با موفقیت انجام شده.
مشاهده جزئیات دانلود

{{step(0)}} برنامه ارسال

لطفا برنامه ارسال خود را انتخاب کنید.

{{step(1)}} مبلغ قابل پرداخت: {{model.remaining_price|number}} تومان

ثبت سفارش: {{model.created.subtract}} ، سررسید پرداخت: {{model.due_date.subtract}}

{{step(2)}} روش پرداخت

لطفا نوع پرداخت مورد نظر خود را از طریق گزینه‌های زیر انتخاب کنید.

{{step(3)}} حساب بانکی

لطفا حساب بانکی مورد نظر خود را انتخاب کنید.
حساب بانکی را انتخاب کنید.

{{step(4)}} واریز به حساب

لطفا مبلغ سفارش را به حساب با اطلاعات زیر واریز کنید:
عنوان: {{model.gateway_id.title}}
صاحب حساب: {{model.gateway_id.owner}}
شماره کارت: {{model.gateway_id.pan}}
شماره شبا: {{model.gateway_id.iban}}

{{step(5)}} سند پرداخت

اطلاعات سند پرداخت خود را از طریق فرم زیر ثبت کنید.
کد پیگیری را بنویسید.
توضیحات را کم‌تر از 4000 حرف بنویسید.

{{step(3)}} درگاه پرداخت

لطفا درگاه پرداخت مورد نظر خود را انتخاب کنید.
درگاه پرداخت را انتخاب کنید.
از آنجایی که شارژ کیف‌پول شما کم‌تر از مبلغ قابل پرداخت است؛ اگر بر روی دکمه‌ی پرداخت کلیک کنید، کل موجودی کیف‌پول شما به مقدار {{user.credit|number}} تومان از صورت‌حساب کسر خواهد شد و باقیمانده‌ی آن را می‌توانید از دیگر روش‌های موجود پرداخت کنید.
کمی صبر کنید...
کمی صبر کنید...
``` # سرویس ساب دامنه برای پیاده‌سازی سرویس ساب دامنه بعد از خرید و فعال‌سازی سرویس، می‌توانید برای ردیابی خریدهای انجام شده از اسکریپت ردیابی افیلی استفاده کنید. ### **ردیابی لینک‌ها:** قطعه کد زیر را در تگ هد همه صفحات سایت خود قرار دهید. ```html ``` ### **ثبت مشتری:** در صورتی که ارائه دهنده سرویس SaaS هستید یا مشتری در ازای پرداخت حق عضویت از خدمات شما استفاده می‌کند و می‌خواهید در طول یک مدت زمان خاص یا برای تکرار خرید به بازاریاب پورسانت پرداخت کنید. نیاز است بعد از ثبت‌نام مشتری در سیستم شما از طریق قطعه کدی که در ادامه می‌آوریم، یک مشتری ایجاد کنید. ```html ``` پس از اینکه مشتری در سرویس ثبت شد شناسه مشتری توسط تابع callback بازگردانده می‌شود. شما باید این مقدار را در دیتابیس خود ذخیره کنید. در قطعه کد بالا متغیرهای **customerId** و **metaData** باید با مقادیر صحیح توسط شما پر شوند که توضیح هر کدام را در ادامه می‌دهیم. customerId: شناسه یکتای مشتری در سیستم شماست. metaData: آبجکتی حاوی اطلاعات اضافه راجع به مشتری است. ارسال این پارامتر **اختیاری** است.

تذکر: در صورتی که مشتری از سمت بازاریاب نباشد، دیتایی سمت سرویس ذخیره نشده و تابع 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** در متا دیتا برای هر فرم باید مقدار یکتایی داشته باشد. و ارسال آن الزامی است. این مقدار می‌تواند از نوع عدد یا یک رشته باشد. همچنین برای فرمهای لید همانند بالا می‌توانید سایر داده‌های فرم را در متغیر متا دیتا برای ما ارسال کنید. ارسال این اطلاعات برای تطبیق و جلوگیری از تقلب ناشران الزامی است.