# سرویس کانورژن برای ردیابی و مدیرت کانورژن‌ها و علاوه بر پیاده‌سازی اسکریپت می‌توانید از طریق 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نام بازاریاب
## **ثابت‌ها** ### وضعیت کانورژن
۰در انتظار تایید توسط سیستم
۱تایید شده
۲تکراری
۳نیازمند بررسی دستی