نحوه پیکربندی

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

پیش نیاز ها

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

نکات ضروری

احراز هویت به دو روش انجام می شود:
از طریق loginToken
از طریق userId و password صاحب کسب و کار
در صورتی که در پارامترها مقدار loginToken ذکر شده باشد نیازی به userId و password نیست، اما اگر پارامتر loginToken وجود نداشته باشد احراز هویت از طریق userId و password انجام می گیرد.
کلیه درخواست های ارسالی به سرور باید به روش POST باشند.
در بدنه کلیه درخواست ها باید یک آبجکت JSON به نام data وجود داشته باشد که مقادیر ارسالی به عنوان پارامتر در آن ذخیره شده باشند.
کلیه تاریخ ها در سیستم API حسابفا به صورت میلادی تعریف شده اند. قالب تاریخ به شکل YYYY-MM-DD HH:MM:SS است.

نکته مهم

سیستم API حسابفا در هر دقیقه از هر IP حداکثر به 50 درخواست پاسخ خواهد داد.

مثالی از یک درخواست در جاوااسکریپت و JQuery

method	تعیین متد از نوع POST
url	آدرس API
apiKey	apikey پارامتر ضروری
loginToken	loginToken پارامتر ضروری
userId	userId پارامتر ضروری
password	password پارامتر ضروری
if (result.Success)	اگر این شرط برقرار باشد، درخواست موفقیت آمیز بوده است.
var r = result.Result	نتیجه درخواست در فیلد r ذخیره شده است.
fail(function() { })	اگر نتیجه درخواست، کدی غیر از 200 باشد درخواست موفقیت آمیز نبوده است و ارتباط با سرور برقرار نشده است.

    var option = {
           method: 'POST',
           url: 'https://api.hesabfa.com/v1/contact/save',
           data: {
               apiKey: 'business api key',    
               loginToken: 'business login token',   
               userId: 'business owner user id',     
               password: 'business owner password',  
               contact: {
                   Code: '0',
                   Name: 'نام شخص',
                   City: 'تهران',
                   Mobile: '09121234567',
                   Phone: '02188123456'
               }
           }
       }
       $.ajax(option).done(function(result) {
           if (result.Success)
           var r = result.Result;  
       .fail(function() {
       });

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

همانطور که اشاره شد مقادیر بازگشتی از سرور با فراخوانی متد های 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 رکورد در نظر گرفته می شود.
Skip	تعداد رکوردی که از ابتدای لیست صرف نظر می شود.
Search	عبارت جستجو
SearchFields	آرایه ای از فیلدهایی که جستجو در آن انجام می گیرد.
Filters	آرایه ای از اشیا برای اعمال فیلتر بر روی لیست. شامل ساختار زیر:

Property	نام فیلد مورد نظر برای اعمال فیلتر. نکته: فیلد هایی که در بخش خروجی سرویس API دریافت شده اند در این بخش قابل انتخاب هستند.
Operator	نوع عملگر، شامل موارد زیر: = > => < =< =! (نامساوی) * (شامل شود) ?* (خاتمه یابد) *? (شروع شود) in (در بین مقادیر یک آرایه)
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"]
}

نکته

در صورت انتخاب in به عنوان اپراتور value باید به صورت آرایه ارسال گردد.

مثال:

 {
     Take: 10,
     Skip: 0,
     Filters:[
                {
                    Property: 'Code',
                    Operator: 'in',
                    Value: [‘000001’, ‘000002’, ‘000003’]
                }
             ]
}

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

مثالی از یک درخواست در جاوااسکریپت و JQuery

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

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