مرکز واسط برنامه نویسی

پیکربندی واسط API


نحوه پیکربندی
واسط برنامه نویسی حساب فا (API) با استفاده از تکنولوژی Web Api2 پیاده سازی شده است و انتقال اطلاعات بر اساس پروتکل HTTP می باشد. این سرویس عملیات ها را در قالب متد هایی ارائه می دهد که سمت سرور پیاده سازی شده اند و برنامه نویس می تواند این متد ها را به صورت مستقیم فراخوانی کند. مقادیر ارسالی و دریافتی بر اساس JSON بوده و کلیه متد ها، مقادیر ارسالی را بر اساس ساختار مشخصی از شی های JSON که در ادامه تشریح خواهد شد به کلاینت انتقال می دهند.

پیش نیاز ها
apiKey: مجوز استفاده از سرویس API حساب فا از طریق apiKey تایید می شود که این apiKey به ازاء هر کسب و کار یکتا بوده و معرف آن کسب و کار می باشد. برای به دست آوردن apiKey می توانید در پنل کاربری کسب و کار مورد نظر از منوی تنظیمات > واسط برنامه نویسی به apiKey دسترسی پیدا کنید.
userId: نام کاربری صاحب کسب و کار که در حساب فا به منظور ورود به سیستم استفاده می شود.
password: کلمه عبور صاحب کسب و کار که در حساب فا به منظور ورود به سیستم استفاده می شود.


نکات ضروری
  1. کلیه درخواست های ارسالی به سرور باید به روش POST باشند.
  2. در بدنه کلیه درخواست ها باید یک آبجکت JSON به نام data وجود داشته باشد که مقادیر ارسالی به عنوان پارامتر در آن ذخیره شده باشند.
  3. سه پارامتر apiKey,userId,password باید به همراه کلیه درخواست ها به سرور ارسال شوند. یعنی به عنوان فیلدهای اطلاعاتی شی data ذکر شده در بند 2 قرار داشته باشند.
  4. کلیه تاریخ ها در سیستم API حسابفا به صورت میلادی تعریف شده اند. قالب تاریخ به شکل YYYY-MM-DD HH:MM:SS است.
نکته مهم
  • سیستم API حسابفا در هر دقیقه از هر IP حداکثر به 50 درخواست پاسخ خواهد داد.

مثالی از یک درخواست در جاوااسکریپت و JQuery
            var option = {
                method: 'POST',  ------> POST تعیین متد از نوع
                url: 'https://api.hesabfa.com/v1/contact/save',  ------> API آدرس 
                data: {
                    apiKey: 'business api key',      ------> apikey پارامتر ضروری 
                    userId: 'business owner user id',      ------> userId پارامتر ضروری 
                    password: 'business owner password',   ------> password پارامتر ضروری 
                    contact: {
                        Code: '0',
                        Name: 'نام شخص',
                        City: 'تهران',
                        Mobile: '09121234567',
                        Phone: '02188123456'
                    }
                }
            }
            $.ajax(option).done(function(result) {
                if (result.Success)
                     اگر این شرط برقرار باشد، درخواست موفقیت آمیز بوده است     
                var r = result.Result;    ------> نتیجه درخواست در این فیلد ذخیره شده است
            })
            .fail(function() {
                 اگر نتیجه درخواست، کدی غیر از 200 باشد درخواست موفقیت آمیز نبوده است و ارتباط با سرور برقرار نشده است
            });
    

مقادیر بازگشتی:

همانطور که اشاره شد مقادیر بازگشتی از سرور با فراخوانی متد های API، در قالب JSON می باشد.

قالب JSON پاسخ داده شده از تمامی متد ها دارای ساختار زیر می باشد:

{
     Success:bool,
     ErrorCode:int,
     ErrorMessage:text,
     Result:object,
}

Success: نشان دهنده وضعیت کلی پاسخ. چنانچه عملیات مربوطه موفقیت آمیز باشد مقدار این پارامتر true و چنانچه با خطا مواجه شده باشد false می شود.
ErrorCode: کد خطا
ErrorMessage: متن خطا
Result:در صورتی که عملیات با موفقیت انجام شده باشد، نتیجه برگشتی از سمت سرور در این شی قرار می گیرد. این پارامتر می تواند NULL، یا یک شی یا یک آرایه از اشیا باشد.

توجه کنید که پاسخ سرور در قالب JSON فقط در زمانی که مقدار HttpResponseCode برابر 200 باشد ارسال می گردد. چنانچه HttpResponseCode مقداری غیر از 200 باشد، عملیات با خطا مواجه شده و پاسخی از سمت سرور ارسال نخواهد شد.


پارامتر queryInfo برای اعمال فیلتر و مرتب سازی بر روی لیست ها:

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

این شی دارای ساختار زیر می باشد:

SortBy نام فیلد مورد نظر برای مرتب سازی
SortDesc false = مرتب سازی صعودی
true = مرتب سازی نزولی.
Take حداکثر تعداد رکورد بازگشتی، در صورت تعیین نشدن حداکثر تعداد 10 رکورد در نظر گرفته می شود.
حداکثر تعداد رکورد بازگشتی 50 رکورد است.
Skip تعداد رکوردی که از ابتدای لیست صرف نظر می شود.
Search عبارت جستجو.
SearchFields آرایه ای از فیلدهایی که جستجو در آن انجام می گیرد.
Filters آرایه ای از اشیا برای اعمال فیلتر بر روی لیست. شامل ساختار زیر:
Property نام فیلد مورد نظر برای اعمال فیلتر.
نکته: فیلد هایی که در بخش خروجی سرویس API دریافت شده اند در این بخش قابل انتخاب هستند.
Operator نوع عملگر، شامل موارد زیر:
=    >    =>    <    =<    =! (نامساوی)    * (شامل شود)    ?* (خاتمه یابد)    *? (شروع شود)
Value مقدار مورد نظر
مثال:
{
     SortBy: 'Name',
     SortDesc: false,
     Take: 10,
     Skip: 0,
     Filters:[
                {
                    Property: 'Name',
                    Operator: '*',
                    Value: 'شرکت'
                },
                {
                    Property: 'Liability',
                    Operator: '>',
                    Value: '100000'
                }
             ]
}
مثال:
{
     SortBy: 'Name',
     SortDesc: false,
     Take: 10,
     Skip: 0,
     Search: "محمد",
     SearchFields: ["Name", "FirstName", "LastName"]
}