آموزش اتصال به ناپ کامرس | راهنمای جامع API، وب‌هوک و یکپارچه‌سازی

روش‌های اصلی اتصال به ناپ کامرس

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

۱. استفاده از افزونه‌های API رسمی

ناپ کامرس یک افزونه RESTful Web API رسمی ارائه می‌دهد که در مارکت‌پلیس آن قابل تهیه است [citation:15]. این افزونه با استفاده از سرویس‌های بومی ناپ کامرس، امنیت و کارایی بالایی را فراهم می‌کند و بیش از ۲۰۰ متد API برای پوشش تمام جنبه‌های فرانت‌اند فروشگاه در اختیار توسعه‌دهندگان قرار می‌دهد [citation:11].

۲. توسعه افزونه اتصال سفارشی

برای نیازهای خاص، می‌توانید یک افزونه اتصال سفارشی توسعه دهید. این روش انعطاف‌پذیری کامل را فراهم می‌کند و امکان پیاده‌سازی منطق دلخواه را به شما می‌دهد [citation:7].

۳. استفاده از وب‌هوک (Webhook)

وب‌هوک‌ها امکان دریافت رویدادهای لحظه‌ای از سرویس‌های خارجی را فراهم می‌کنند. برای مثال، درگاه‌های پرداخت مانند PayPal یا Crypto.com از وب‌هوک برای ارسال وضعیت پرداخت استفاده می‌کنند [citation:2][citation:12].

نصب و راه‌اندازی افزونه API در ناپ کامرس

در این بخش از آموزش اتصال به ناپ کامرس، مراحل نصب و راه‌اندازی یک افزونه API را بررسی می‌کنیم.

مرحله ۱: تهیه افزونه API

افزونه API را از مارکت‌پلیس ناپ کامرس تهیه کنید. این افزونه به صورت پولی ارائه می‌شود و شامل مستندات کامل Swagger است [citation:11].

مرحله ۲: نصب افزونه

برای نصب افزونه، مراحل زیر را دنبال کنید:

• به پنل مدیریت ناپ کامرس بروید.
• از مسیر Configuration → Local Plugins وارد شوید.
• افزونه API را در لیست پیدا کنید و روی Install کلیک کنید.

مرحله ۳: ایجاد اپلیکیشن و دریافت API Key

پس از نصب، به صفحه Applications بروید و یک اپلیکیشن جدید ایجاد کنید. با این کار، یک Application API Key منحصربه‌فرد تولید می‌شود که باید در تمام درخواست‌های API در هدر X-API-KEY ارسال شود [citation:3].

مرحله ۴: دریافت توکن JWT

برای اکثر متدهای API، به یک توکن JWT نیاز دارید. برای دریافت توکن مهمان (Guest Token)، درخواستی به آدرس /api/PublicCustomer/GetGuestToken با هدر X-API-KEY ارسال کنید [citation:3]:

    var client = new RestClient("https://yourstore.com/api/PublicCustomer/GetGuestToken");
    var request = new RestRequest(Method.GET);
    request.AddHeader("X-API-KEY", "YOUR_API_KEY");
    IRestResponse response = client.Execute(request);
    

پاسخ شامل AccessToken خواهد بود که باید در هدر Authorization تمام درخواست‌های بعدی ارسال شود [citation:3].

مرحله ۵: احراز هویت کاربر

برای ورود کاربران ثبت‌نام شده، از آدرس /api/PublicCustomer/Login با بدنه شامل UsernameOrEmail و Password استفاده کنید [citation:3].

مدیریت وب‌هوک (Webhook) در ناپ کامرس

وب‌هوک‌ها یکی از مهم‌ترین ابزارها در آموزش اتصال به ناپ کامرس هستند که امکان دریافت داده‌های لحظه‌ای از سرویس‌های خارجی را فراهم می‌کنند.

وب‌هوک چیست و چرا به آن نیاز داریم؟

وب‌هوک مکانیزمی است که به سرویس‌های خارجی اجازه می‌دهد رویدادهای مهم را به صورت لحظه‌ای به فروشگاه شما ارسال کنند. برای مثال، درگاه پرداخت پس از تأیید یا رد تراکنش، یک درخواست HTTP به آدرس وب‌هوک شما ارسال می‌کند [citation:2].

پیاده‌سازی یک وب‌هوک ساده

برای ایجاد یک وب‌هوک در ناپ کامرس، مراحل زیر را دنبال کنید:

مرحله ۱: ایجاد کنترلر و اکشن

یک کنترلر جدید با یک اکشن برای دریافت درخواست وب‌هوک ایجاد کنید [citation:10]:

    [IgnoreAntiforgeryToken]
    public virtual async Task WebhookHandler(int? orderId)
    {
        // دریافت داده‌های ارسال شده
        var requestBody = await new StreamReader(Request.Body).ReadToEndAsync();
        
        // پردازش داده‌ها
        // ...
        
        return Ok();
    }
    

مرحله ۲: ثبت مسیر (Route)

برای ثبت مسیر وب‌هوک، از کد زیر در RouteProvider استفاده کنید [citation:10]:

    endpointRouteBuilder.MapControllerRoute(
        name: "Plugin.Webhook",
        pattern: "Plugins/Webhook/{orderId:regex(\\d*)}",
        defaults: new { controller = "Webhook", action = "WebhookHandler" }
    );
    

مرحله ۳: تست وب‌هوک

برای تست، می‌توانید از ابزارهایی مانند Postman استفاده کنید یا به آدرس زیر مراجعه کنید [citation:10]:

yourwebsite.com/Plugins/Webhook/1

مثال عملی: تنظیم وب‌هوک درگاه پرداخت

درگاه‌های پرداخت مانند PayPal و Crypto.com از وب‌هوک برای ارسال وضعیت پرداخت استفاده می‌کنند [citation:2][citation:12]. برای تنظیم وب‌هوک در این درگاه‌ها، باید آدرسی مانند https://yourdomain.com/Plugins/PaymentGateway/Webhook را در پنل درگاه ثبت کنید [citation:4].

یکپارچه‌سازی با سرویس‌های خارجی

یکی از کاربردهای اصلی آموزش اتصال به ناپ کامرس، یکپارچه‌سازی با سرویس‌های خارجی مانند گوگل آنالیتیکس، سیستم‌های ERP و درگاه‌های پرداخت است [citation:7].

ساختار یک افزونه یکپارچه‌سازی

هر افزونه یکپارچه‌سازی معمولاً شامل اجزای زیر است [citation:7]:

• Plugin.cs: شامل اطلاعات متادیتا و منطق نصب و حذف.
• Services: حاوی منطق کسب‌وکار و فراخوانی APIهای خارجی.
• Controllers: برای نمایش تنظیمات یا دریافت وب‌هوک.
• Views: برای رابط کاربری تنظیمات (اختیاری).

مثال: ارسال رویداد به گوگل آنالیتیکس

برای ارسال رویداد خرید به گوگل آنالیتیکس نسخه ۴ (GA4)، یک سرویس با کد زیر ایجاد کنید [citation:7]:

    public class GoogleAnalyticsService
    {
        private readonly HttpClient _httpClient;
        private readonly string _measurementId = "G-XXXXXXX";
        private readonly string _apiSecret = "your_api_secret";

        public GoogleAnalyticsService(HttpClient httpClient)
        {
            _httpClient = httpClient;
        }

        public async Task SendPurchaseEventAsync(string clientId, decimal value)
        {
            var url = $"https://www.google-analytics.com/mp/collect?measurement_id={_measurementId}&api_secret={_apiSecret}";
            var body = new
            {
                client_id = clientId,
                events = new[]
                {
                    new
                    {
                        name = "purchase",
                        params_ = new { value = value }
                    }
                }
            };
            
            var json = JsonSerializer.Serialize(body);
            var response = await _httpClient.PostAsync(url, new StringContent(json, Encoding.UTF8, "application/json"));
            response.EnsureSuccessStatusCode();
        }
    }
    

امنیت در اتصال به ناپ کامرس

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

استفاده از HTTPS

همیشه از گواهی SSL برای تمام درخواست‌های API و وب‌هوک استفاده کنید [citation:4]. این کار از حملات Man-in-the-Middle جلوگیری می‌کند.

احراز هویت دو لایه

افزونه‌های API معتبر معمولاً از احراز هویت دو لایه استفاده می‌کنند [citation:3][citation:11]:

• لایه اول: توکن JWT که بر اساس Secret Key تولید می‌شود و برای احراز هویت کاربران استفاده می‌شود.
• لایه دوم: Application API Key که در هدر X-API-KEY ارسال می‌شود و دسترسی به API را برای اپلیکیشن‌های خاص فراهم می‌کند.

مدیریت توکن‌ها

برای مدیریت توکن‌های JWT و Refresh Token، از مکانیزم‌های زیر استفاده کنید [citation:11]:

• توکن‌ها را به صورت امن در سمت کلاینت ذخیره کنید.
• برای تمدید توکن‌ها از Refresh Token استفاده کنید.
• توکن‌های منقضی شده را به صورت دوره‌ای پاک‌سازی کنید.

بهترین شیوه‌های توسعه API در ناپ کامرس

• استفاده از صفحه‌بندی: برای داده‌های حجیم، از پارامترهای pageNumber و pageSize استفاده کنید تا از بار اضافی جلوگیری شود [citation:9].
• اعتبارسنجی داده‌ها: از Data Annotations یا Fluent Validation برای اعتبارسنجی ورودی‌ها استفاده کنید [citation:9].
• مدیریت خطا: از کدهای وضعیت HTTP مناسب و لاگ‌گیری با ابزارهایی مانند Serilog استفاده کنید [citation:9].
• مستندسازی: از Swagger برای مستندسازی خودکار API استفاده کنید [citation:11].
• استفاده از کش: برای پاسخ‌های API که به ندرت تغییر می‌کنند، از کش استفاده کنید [citation:11].

نتیجه‌گیری

آموزش اتصال به ناپ کامرس نشان می‌دهد که این پلتفرم با ارائه افزونه‌های API قدرتمند، پشتیبانی از وب‌هوک و معماری انعطاف‌پذیر، بستری ایده‌آل برای یکپارچه‌سازی با سیستم‌های خارجی فراهم می‌کند. با استفاده از روش‌های معرفی شده در این مقاله، می‌توانید فروشگاه خود را به ابزارهای تحلیل، بازاریابی، پرداخت و مدیریت متصل کنید و تجربه بهتری برای مشتریان خود ایجاد نمایید.

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

توجه: این مقاله بر اساس مستندات رسمی ناپ کامرس و تجربه توسعه‌دهندگان حرفه‌ای تهیه شده است. برای آخرین تغییرات، همواره به مستندات رسمی و مارکت‌پلیس ناپ کامرس مراجعه کنید.