اتصال به شیوه S2S API (Server) Integration
(برای توسعه دهندگانی که با زبان انگلیسی راحت تر هستند نسخه انگلسی مقاله در انتها آورده شده است)
S2S API چیست؟
رابط برنامهنویسی S2S (سمت سرور) برای ردیابی تبدیلها (Conversion Tracking) به صورت «سرور به سرور» طراحی شده است و به کوکیها یا جاوااسکریپت وابستگی ندارد. در این روش، هنگامی که بازدیدکننده از طریق لینک همکاری در فروش (Affiliate Link) وارد میشود، سرور شما یک `click_token` را از URL او دریافت و ذخیره میکند؛ سپس در زمان وقوع تبدیل، سرور شما یک درخواست POST حاوی آن توکن و جزئیات سفارش به اندپوینت (Endpoint) مربوط به S2S ارسال میکند. این راهکار برای ردیابیِ منطبق بااصول حریم خصوصی و فرآیندهای پرداخت (Checkout) در سمت سرور مناسب است.
کجا آن را تنظیم یا Configure کنیم؟
تمامی روشهای یکپارچهسازی در فرم کمپین و در زبانه «تنظیمات یکپارچهسازی» (Integration Setup) قرار دارند. از بخش مدیریت برنامه AffiliatePro استفاده کنید.
نحوه باز کردن فرم و انتخاب S2S API
۱. به پنل مدیریت اپلیکیشن AffiliatePro وارد شوید.
۲. در نوار بالایی، منوی کشویی Marketing را باز کرده و روی Campaigns کلیک کنید.
۳. در صفحه Campaigns، چهار کارت مربوط به انواع کمپین را مشاهده خواهید کرد: کمپین بنری (Banner Campaign)، کمپین متنی (Text Campaign)، کمپین لینکی (Link Campaign) و کمپین ویدیویی (Video Campaign). برای ایجاد یک کمپین جدید، روی گزینه Create New در هر یک از این کارتها کلیک کنید؛ یا برای ویرایش یک کمپین موجود، روی دکمه Edit مربوط به آن کلیک نمایید.
۴. در زبانه General Settings، نام کمپین (Campaign Name) را وارد کرده و نوع ابزار یا Tool Type را تعیین کنید (موردی که قرار است ردیابی شود؛ برای سیستم S2S مبتنی بر سفارش، گزینه Sale Integration انتخاب معمول است). سپس Target URL و سایر تنظیمات را وارد کنید.
۵. روی زبانه Integration Setup (که با آیکون دوشاخه/پلاگین مشخص شده است) کلیک کنید.
۶. در بخش Choose Your Integration Method، روی کارت S2S API (Server) کلیک کنید.
وابستگی حیاتی: ابتدا ذخیره کنید
کلید API، نشانی (URL) نقطه پایانی S2S، جدول پارامترها و نمونه دستور cURL تنها پس از یکبار ذخیره کردن کمپین نمایش داده میشوند. تا پیش از ذخیرهسازی، فرم این پیام را نشان میدهد: «ابتدا این کمپین را ذخیره کنید. کلید API و مستندات نقطه پایانی پس از ذخیرهسازی در اینجا ظاهر خواهند شد.»
روی گزینه «ذخیره» (Save) کلیک کنید — و نه «ذخیره و بستن» (Save & Close) — تا بتوانید بلافاصله کلید API و نشانی نقطه پایانیِ ظاهرشده را کپی کنید.
S2S Tracking چگونه کار میکند؟
۱. بازدیدکننده روی لینک همکاری در فروش (affiliate link) کلیک کرده و به سایت شما هدایت میشود؛ در این حین، یک `click_token` منحصربهفرد بهطور خودکار به انتهای URL اضافه میگردد.
۲. سایت شما `click_token` را از URL دریافت و ذخیره میکند (مثلاً در نشست/Session یا پایگاه داده).
۳. هنگامی که یک تبدیل (Conversion) رخ میدهد، سرور شما یک درخواست POST حاوی `click_token`، جزئیات سفارش و کلید API به اندپوینت S2S ارسال میکند.
۴. سیستم، `click_token` را با کلیک اولیه تطبیق داده و کمیسیون را بهطور خودکار ثبت میکند.
فرم Form چه چیزی را پس از ذخیره سازی نشان میدهد؟
– کلید API — آن را با استفاده از دکمه «Copy» کپی کنید. سرور شما باید این کلید را در هر درخواست POST مربوط به ثبت کانورژن (تبدیل) ارسال کند. گزینه «Regenerate API Key» را انتخاب کنید (هشدار: این کار کلید فعلی را باطل میکند؛ بنابراین باید تمام سیستمهایی که از کلید قدیمی استفاده میکنند را بهروزرسانی کنید).
– آدرس Endpoint برای S2S — دادههای کانورژن را به این آدرس ارسال کنید (با متد POST). آدرس دقیق در فرم نمایش داده شده است و از الگوی …/integration/s2sConvert پیروی میکند.
– جدول پارامترهای الزامی — api_key، click_token، order_id، order_total، order_currency.
– نمونه cURL — یک نمونه آمادهبهکار که کلید API و آدرس Endpoint اختصاصی شما در آن از پیش درج شده است.
نمونه های Response
- Success —
{"status":"success","message":"S2S conversion recorded successfully"} - Duplicate —
{"status":"duplicate","message":"Order already recorded"} - Error — e.g.
{"status":"error","message":"Invalid API key"}
دسترسی فوری از Campaigns List
در جدول کمپینها، کمپینهای S2S API در ستون «وضعیت یکپارچهسازی» (Integration Status) دارای نشان S2S API هستند. برای باز کردن پنجره تنظیمات S2S و مشاهده کلید API و اندپوینت (Endpoint) بدون نیاز به پر کردن فرم کامل، روی دکمهای کهآیکون سرور دارد و در کنار این نشان قرار گرفته است، کلیک کنید.
اگر کلید API را بازتولید کنید، تمامی پذیرندگان یا سیستمهایی که از کلید قدیمی استفاده میکنند باید فوراً بهروزرسانی شوند. به محض ذخیره کردن تنظیمات در حالی که گزینه بازتولید (regenerate) انتخاب شده باشد، کلید قدیمی نامعتبر میشود.
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||. ENGLISH. |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
What Is S2S API?
S2S API (Server) is for server-to-server conversion tracking. It does not rely on cookies or JavaScript. Your server captures a click_token from the visitor’s URL when they arrive via an affiliate link, then when a conversion happens your server sends a POST request to the S2S endpoint with that token and order details. Suitable for privacy-compliant tracking and server-side checkouts.
Where You Configure It
All integration methods are in the campaign form, under the Integration Setup tab. Use the AffiliatePro application admin.
How to Open the Form and Choose S2S API
- Log in to the AffiliatePro application admin.
- In the top bar, open the Marketing dropdown → click Campaigns.
- On the Campaigns page you will see four campaign type cards: Banner Campaign, Text Campaign, Link Campaign, Video Campaign. Click Create New on any card to create a campaign, or click the Edit button on an existing campaign to open it.
- In the General Settings tab, fill in the Campaign Name and set the Tool Type (what is tracked: Sale Integration is the typical choice for order-based S2S). Add the Target URL and other settings.
- Click the Integration Setup tab (plug icon).
- Under Choose Your Integration Method, click the S2S API (Server) card.
Critical Dependency: Save First
The API key, S2S Endpoint URL, parameter table, and example cURL are only shown after you save the campaign at least once. Until saved, the form shows: “Save this campaign first. Your API key and endpoint documentation will appear here after saving.”
Click Save (stays on the form) — not Save & Close — so you can immediately copy the API key and endpoint URL that appear.
How S2S Tracking Works
- Visitor clicks the affiliate link and is redirected to your site. A unique
click_tokenis automatically appended to the URL. - Your site captures the
click_tokenfrom the URL and stores it (e.g. in session or database). - When a conversion happens, your server sends a POST request to the S2S Endpoint with the
click_token, order details, and the API key. - The system matches the
click_tokento the original click and records the commission automatically.
What the Form Shows After Saving
- API Key — copy it with the Copy button. Your server must send it with every conversion POST. Check the Regenerate API Key checkbox (warning: invalidates the current key — update all systems using the old key).
- S2S Endpoint URL — POST conversion data here (method: POST). The exact URL is shown in the form; it follows the pattern
.../integration/s2sConvert. - Required Parameters table —
api_key,click_token,order_id,order_total,order_currency. - Example cURL — a ready-to-use example with your actual API key and endpoint pre-filled.
Response Examples
- Success —
{"status":"success","message":"S2S conversion recorded successfully"} - Duplicate —
{"status":"duplicate","message":"Order already recorded"} - Error — e.g.
{"status":"error","message":"Invalid API key"}
Quick Access from the Campaigns List
In the Campaigns table, S2S API campaigns show a S2S API badge in the Integration Status column. Click the server icon button next to the badge to open the S2S setup modal and view the API key and endpoint without entering the full form.