Skip to main content

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

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

تعاریف:

لینک افیلیت:

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

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

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

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

کانورژن:

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

دوره کوکی:

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

دوره مرجوعی:

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

لیست APIها:

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

پارامترهای مورد استفاده در ارسال درخواست ثبت یا ویرایش کانورژن:
نام نوع اجباری توضیحات
referrer String بلی

String

توکن ارجاع که قبلاست در کوکی مرورگر کاربر ذخیر شده.
type String بلی نوع کانورژن
order_id String بلی شماره‌ی سفارش انجام شده
amount Double بلی مبلغ کل سبد خرید
products Array خیر لیست محصولات خریداری شده توسط مشتری؛ این پارامتر در کانورژن‌هایی از نوع  فروش(sale) ارسال می‌شود.
products.* Object - آبجکت حاوی اطلاعات هر محصول
products.*.name String در صورت ارسال اطلاعات محصول، بلی نام محصول
products.*.unit_price Double در صورت ارسال اطلاعات محصول، بلی قیمت واحد محصول در سبد خرید
products.*.quantity Integer در صورت ارسال اطلاعات محصول، بلی تعداد محصول در سبد خرید
products.*.total_price Double در صورت ارسال اطلاعات محصول، بلی مجموع قیمت محصول در سبد خرید
coupon String خیر

کد تخفیف استفاده شده در خرید
meta_data Object برای کانورژن از نوع لید، بلی آبجکت حاوی اطلاعات لید ثبت شده؛ این پارامتر در کانورژن‌هایی از نوع لید(lead) ارسال می‌گردد.
meta_data.form_id String بلی شناسه یکتای فرم مربوطه در وبسایت فروشگاه
meta_data.uniq_param Any بلی پارامتر یکتای لید ثبت شده که می‌تواند داده‌ای نظیر شماره موبایل، ایمیل، کد ملی یا هر مقدار یکتای دیگری در فرم باشد.
meta_data.* Any خیر سایر اطلاعات مربوط به لید ثبت شده

پارامترهای استفاده شده در دیتای بازگشتی از سمت سرور:
نام نوع توضیحات
id
 String شناسه یکتای کانورژن ثبت شده در افیلی
publisher Object آبجکت مربوط به اطلاعات بازاریاب
publisher.id String شناسه یکتای بازاریاب در افیلی
publisher.full_name String نام بازاریاب
status Integer

وضعیت کانورژن که می‌تواند یکی از اعداد ۰(منتظر تایید توسط سیستم)، ۱(تایید شده)، ۲(رد شده)، ۳(تکراری) یا ۴(نیازمند بررسی دستی) باشد.
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|Integer شماره سفارش
products Array لیست محصولات خریداری شده توسط مشتری؛ این پارامتر تنها در صورتی که کانورژن از نوع فروش(sale) باشد، ارسال می‌شود.
products.* Object آبجکت حاوی اطلاعات هر محصول
products.*.name String نام محصول
products.*.unit_price Double قیمت واحد محصول در سبد خرید
products.*.quantity Integer تعداد محصول در سبد خرید
products.*.total_price Double مجموع قیمت محصول در سبد خرید
meta_data Object آبجکت حاوی اطلاعات لید ثبت شده
meta_data.form_id String شناسه یکتای فرم مربوطه در وبسایت فروشگاه
meta_data.uniq_param Any پارامتر یکتای لید ثبت شده که می‌تواند داده‌ای نظیر شماره موبایل، ایمیل، کد ملی یا هر مقدار یکتای دیگری در فرم باشد.
meta_data.* Any سایر اطلاعات موجود در فرم مربوطه
coupon String کد تخفیف استفاده شده در خرید
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 مربوطه می‌پردازیم.

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


Back to top