پلاگین شمعدونی |‌ API خام

مقدمه

شمعدونی از ۳ قسمت کلی تشکیل شده است:

iframe شمعدونی
RESTish API شمعدونی
نشان اعتماد شمعدونی

قسمت اول و دوم به طور تنگاتنگ با هم در ارتباطند و قسمت سوم که ساده ترین قسمت پیاده سازی میباشد ارتباط تنگانگی با دو قسمت دیگر ندارد. در ادامه به توضیح هر بخش میپردازیم.

RESTful یا RESTish؟

استاندار REST یک استاندارد ساخت HTTP API برای اشتراک گذاری منابع است. RESTful API به API ای گفته میشود که تا جای ممکن از استاندارد REST پیروی کند. حال API شمعدونی در مورد اشتراک گذاری منابع نیست و یک API عملگرا میباشد، اما ما تلاش کردیم تا حد ممکن از استاندارد REST پیروی کنیم به خاطر همین به آن RESTish API میگوییم.

کلیات کارکرد

در هنگامی که در فروشگاه کاربر به صفحه checkout میرسد یک درخواست به API شمعدونی فرستاده میشود تا یک تراکنش ساخته شود. در این درخواست یک شناسه تراکنش ساخته میشود. در این صفحه در آخر فاکتور iframe شمعدونی قرار گرفته میشود که کاربر در صورت تیک زدن در iframe یک درخواست دیگر به API شمعدونی میفرستد و مبلغ رند شده در پاسخ دریافت میشود. در همین هنگام یک event برای صفحه checkout فرستاده میشود تا فاکتور را از طریق AJAX بروزرسانی کند. در مرحله بعد، بعد از پرداخت موفقیت آمیز یک درخواست دیگر به API شمعدونی زده میشود و تراکنش را تایید میکند.
نشان اعتماد شمعدونی هم به سادگی قابل اضافه شدن میباشد و شما میتوانید در فوتر یا ساید بار فروشگاه خودتان قرار دهید.

پیاده سازی

مرحله اول

حال باید iframe شمعدونی را در زیر فاکتور خود قرار دهید

<iframe src="https://www.shamdooni.org/iframe/?apilink=YOUR_API_LINK&session_key=SESSION_KEY&checked=TRUE_OR_FALSE" width="400px" height="200px"></iframe>

داده های YOUR_API_LINK ، SESSION_KEY و TRUE_OR_FALSE داده هایی هستند که شما باید پر کنید و در مراحل بعد توضیح داده میشود.

مرحله دوم

در این مرحله باید شما یک table (در صورتی که از دیتابیس های رابطه ای استفاده میکنید) درست کنید
ستون های پیشنهادی ما برای این جدول عبارتند از:

توضیحات	نام فیلد
معمولا در سیستم های فروشگاهی همچین فیلدی برای پیدا کردن سبد موجود است.	session_key
شناسه سفارش که معمولا بعد از پرداخت به دست می آید.	order_id
رند شده یا نه	rounded
قیمت نهایی فاکتور	final_amount
مقدار رند شده	round_amount
مبلغ پرداختی قبل از رند شدن	amount
شناسه تراکنش شمعدونی	shamdooni_transaction_id
تمام شدگی تراکنش	ended

<iframe src="https://www.shamdooni.org/iframe/?apilink=YOUR_API_LINK&session_key=SESSION_KEY&checked=TRUE_OR_FALSE" width="400px" height="200px"></iframe>

داده های YOUR_API_LINK ، SESSION_KEY و TRUE_OR_FALSE داده هایی هستند که شما باید پر کنید و در مراحل بعد توضیح داده میشود.

مرحله سوم

در هنگامی که صفحه checkout لود میشود یک درخواست http با متد POST به آدرس زیر باید فرستاده شود.

https://www.shamdooni.org/api/rounder/v1

داده های درخواست:

توضیحات	نام فیلد
API Key دریافتی شما از شمعدونی.	apikey
مبلغ فاکتور کاربر	amount
شماره فاکتور (اختیاری)	factorId

داده های دریافتی:

در صورتی که اطلاعات ارسالی صحیح باشد:

{
            status: 201,
            message: "تراکنش جدید با موفقیت ساخته شد.",
            transId: شناسه تراکنش,
            amount: مبلغ تراکنش
        }

در صورت بروز خطا:

{
            status: 400,
            message: "پارامتر های داده شده اشتباه است."
        }

حال باید داده های مناسب را در جدول خود در دیتابیس بریزید.

مرحله چهارم

هنگامی که کاربر بر روی تیک iframe کلیک میکند iframe یک درخواست پست به آدرسی که در پارامتر api_link به آن داده شده میفرستد و در آن session_key را به عنوان پارامتر url بعد از apikey و مقدار چک را به صورت body درخواست پس میدهد.

در این مرحله کافیست تا شما یک end point درست کنید و آدرس آن را در پارامتر های iframe وارد کنید تا بتواند پاسخ هارا دریافت کند و در دیتابیس اضافه کند. در این end point شما باید به آدرس زیر با متد PUT در خواست http بزنید تا بتوانید اطلاعات مرتبط با رند شدن را پیدا کنید و در دیتابیس ذخیره کنید. تنها پارامتر مورد نیاز در این درخواست transId میباشد.

https://www.shamdooni.org/api/rounder/v1/:transId

مرحله پنجم

هنگامی که کاربر روی دکمه رند کردن کلیک میکند iframe پس از گرفتن پاسخ از سرور شما یک event به صفحه ای که iframe در آن قرار گرفته شده میفرستد که برای آگاهی از این رویداد باید کد زیر در صفحه checkout اجرا شود.

window.addEventListener("message", function(event) {
    YOUR_AJAX_UPDATE_ORDER_FUNCTION();
});

تابع YOUR_AJAX_UPDATE_ORDER_FUNCTION باید در فاکتور فروشگاه مقدار رند شده را اضافه کند.

مرحله ششم

در مرحله آخر پس از پرداخت موفق میبایست API تایید تراکنش فراخوانده شود. این API دارای متد PUT میباشد و تنها پارامتر مورد نیاز آن transId میباشد.

https://www.shamdooni.org/api/rounder/v1/verify/:transId

نشان اعتماد شمعدونی

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

مستندات شمعدونی

خام API

توجه