Skip to main content

پیاده‌سازی با API

برای ردیابی و مدیرت کانورژن‌ها و علاوه بر پیاده‌سازی اسکریپت می‌توانید از طریق API‌هایی که توسط افیلی ارائه شده، اقدام به پیاده‌سازی سرویس همکاری در فروش نمایید. برای این منظور می‌توانید از مستندات ارائه شده در این صفحه استفاده کنید.

تعاریف:

لینک افیلیت:

به لینک کوتاه شده‌ای که توسط بازاریاب در افیلی ساخته می‌شود و مشتری پس از کلیک روی آن به وبسایت شما ارجاع داده می‌شود لینک افیلیت می‌گویند. هر لینک افیلیت پس از ارجاع به وبسایت فروشگاه شامل پارامترهای زیر خواهد بود.

  • referrer: توکنی است که در هر بار ارجاع، به لینک ارجاع اختصاص داده می‌شود. این توکن مقدار یکتایی دارد و برای صحت سنجی کلیک‌ها مورد استفاده قرار می‌گیرید.
  • exp: تعداد روزهای اعتبار کوکی در مرورگر کاربر است.
  • dl: این پارامتر مشخص کننده تعداد دفعات مجاز ثبت کانورژن برای بازاریاب ارجاع‌دهنده خواهد بود. به عبارت دیگر این مقدار به ما می‌گوید تا چند بار در صورت خرید مشتری به بازاریاب پورسانت تعلق خواهد گرفت.

نکته: مقدار 1- به معنای نامحدود است. و در صورت اعمال تا زمان معتبر بودن کوکی در صورت خرید مشتری به بازاریاب پورسانت تعلق می‌گیرد.

کانورژن:

به هر اقدامی که فروشگاه در ازای آن به بازاریاب پورسانت پرداخت می‌کند کانورژن می‌گویند. افیلی دو نوع کانورژن فروش و لید را پشتیبانی می‌کند.

دوره کوکی:

مدت زمانی است که لینک افیلیت معتبر بوده و در صورت تحقق کانورژن در این بازه زمانی به بازاریاب پورسانت تعلق خواهد گرفت.

دوره مرجوعی:

مدت زمانی است که پس از ثبتایجاد کانورژن امکان ویرایش آن وجود دارد. پس از این مدت زمان کانورژن لاک شده و در اولین سیکل بررسی کانورژن‌های لاک شده، پورسانت آن از حساب فروشگاه کسر و به بازاریاب پرداخت خواهد شد.

لپیست APIهش‌نیازها:

تذکر: برای استفاده از سرویس‌هاین APIهاتعریف شده، نیاز به ارسال Bearer توکن است. از طریق ارتباط با پشتیبانی می‌توانید توکن دسترسی را دریافت کنید.

آدرس پایه ارسال درخواست‌های مربوط به سرویس‌ها:

https://core.affili.ir/services/{uri}

API کانورژن‌ها:

طبق توضیحات داده شده در جدول زیر، از سه API تعریف شده می‌توانید برای ایجاد، ویرایش و دریافت کانورژن‌ها استفاده کنید.

نوع عملیاتنوع درخواستتوضیحاتuri
ایجادPOSTایجاد کانورژن جدید/conversions
ویرایشPOSTویرایش کانورژن ایجاد شده؛ conversionId شناسه کانورژن ایجاد شده در افیلی است./conversions/{conversionId}
لیستGETدریافت لیست کانورژن‌های مربوط به فروشگاه شده در افیلی/conversions

 

ایجاد کانورژن:

بعد از اینکه مشتری از طریق لینک افیلیت وارد وبسایت شما شد پارامترهای referrer و dl را به مدت زمان طول دوره کوکی (مقدار پارامتر exp)، در کوکی مرورگر کاربر ذخیره می‌کنیم.

بعد از تحقق کانورژن (به طور مثال انجام خرید توسط مشتری) از طریق API ایجاد کانورژن، اطلاعات مربوطه به افیلی ارسال می‌شود. در ادامه به بررسی نمونه دیتای ارسالی و دریافتی در ایجاد کانورژن‌های فروش و لید خواهیم پرداخت.

آدرس ارسال درخواست:
POST https://core.affili.ir/services/conversions
قالب ایجاد کانورژن:
{
  "referrer": string,
  "order_id": string,
  "amount": double,
  "type": string,
  "products": [
    object [Product](https://affili.ir),
    ...
  ],
  "coupon": string
}
[Product](https://affili.ir)

 

 

نام اجباری توضیحات
referrer بلی

String

توکن ارجاع که قبلا در مرورگر کاربر ذخیر شده.

type بلی

String

نوع کانورژن که می‌تواند یکی از مقادیر sale یا lead باشد

order_id بلی

String

شماره‌ی سفارش انجام شده

amount بلی

Double

مبلغ کل سبد خرید

products خیر

Array of Product

لیست محصولات خریداری شده توسط مشتری؛ این پارامتر در کانورژن‌هایی از نوع  فروش(sale) ارسال می‌شود.

coupon خیر

String

کد تخفیف استفاده شده در خرید

meta_data بلی

MetaData Object

آبجکت حاوی اطلاعات لید ثبت شده؛ این پارامتر در کانورژن‌هایی از نوع لید(lead) ارسال می‌شود.

پارامترهای استفاده شده در دیتای بازگشتی از سمت سرور:
نام توضیحات
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

لیست محصولات خریداری شده توسط مشتری؛ این پارامتر تنها در صورتی که کانورژن از نوع فروش(sale)، نمایش داده می‌شود.

meta_data

MetaData Object

آبجکت حاوی اطلاعات لید ثبتایجاد شده؛ این پارامتر تنها در کانورژن‌هایی از نوع لید(lead) نمایش می‌شود.

coupon

String

کد تخفیف استفاده شده در خرید؛ این پارامتر تنها در صورتی که کانورژن از نوع فروش(sale)، نمایش داده می‌شود.

created_at

DateTime

تاریخ ایجاد

updated_at

DateTime

تاریخ آخرین بروزرسانی

currency

String

واحد پولی کانورژن ثبت شده که می‌تواند یکی از مقادیر IRT(تومان) یا IRR(ریال) باشد.

ثبت کانورژن:

POST https://core.affili.ir/services/conversions

بعد از اینکه مشتری از طریق لینک افیلیت وارد وبسایت شما شد پارامترهای referrer و dl را به مدت زمان طول دوره کوکی (مقدار پارامتر exp)، در کوکی مرورگر کاربر ذخیره می‌کنیم.

بعد از تحقق کانورژن (به طور مثال انجام خرید توسط مشتری) از طریق API ثبتایجاد کانورژن، اطلاعات مربوطه به افیلی ارسال می‌شود. در ادامه به بررسی نمونه دیتای ارسالی و دریافتی در ثبتایجاد کانورژن‌های فروش و لید خواهیم پرداخت.

نمونه دیتای ارسالی برای ایجادر ثبت کانورژن از نوع فروش:
{
  "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"
    }
  ],
  "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": null,
    "checked_out": null,
    "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"
      }
    ],
    "created_at": "2022-12-31 19:27:32",
    "updated_at": "2022-12-31 19:27:32",
    "currency": "IRT"
  }
}

نمونه دیتای ارسالی در ثبت کانورژن از نوع لید:

{
  "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": null,
    "checked_out": null,
    "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"
    }
  }
}

ویرایش کانورژن:

POST https://core.affili.ir/services/conversions/{conversionId}

می‌توانید تا قبل از پایان دوره مرجوعی و لاک شدن کانورژن، آن را ویرایش کنید. دقت داشته باشید که بعد از لاک شدن امکان اعمال تغییرات وجود نخواهد داشت. در ادامه به بررسی API مربوطه می‌پردازیم.

پارامترهای قابل ویرایش: