خام API

توجه

از آنجایی که API شمعدونی یک API چند مرحله ای است و هم در فرانت اند و هم در بک اند فروشگاه شما نیاز هست که پیاده سازی بشه لطفا تا حد ممکن از از پلاگین های ما استفاده کنید. در صورتی که سیستم شما در میان پلاگین های ما موجود نبود میتوانید به support@shamdooni.org ایمیل بزنید تا تیم فنی ما شما را راهنمایی کنند.

مقدمه

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

  1. iframe شمعدونی
  2. RESTish API شمعدونی
  3. نشان اعتماد شمعدونی
قسمت اول و دوم به طور تنگاتنگ با هم در ارتباطند و قسمت سوم که ساده ترین قسمت پیاده سازی میباشد ارتباط تنگانگی با دو قسمت دیگر ندارد. در ادامه به توضیح هر بخش میپردازیم.

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

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

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