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

واسط برنامه نویسی حسابفا (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 است.

نکات ضروری

مقدارyearId (سال مالی) برای اولین سال مالی: 1، سال مالی بعد: 2 و به همین ترتیب ادامه می یابد.
در صورتی که yearId ارسال نشود، به صورت اتوماتیک آخرین سال مالی در نظر گرفته میشود. در غیر اینصورت اطلاعات در مورد سال مالی yearId ارسال می شود.

نکات ضروری

requestUniqueId: شناسه یکتای درخواست

الصاق این شناسه به درخواست از پردازش درخواست های تکراری جلوگیری می کند. در صورتی که الصاق نشود، تکراری بودن درخواست چک نمی شود.
این شناسه فقط در متدهایی کنترل می شود که وظیفه تغییر یا ذخیره سازی اطلاعات را دارند مانند متدهای Save و Delete و Set.
در متدهایی که وظیفه گرفتن اطلاعات را دارند مانند متدهای Get و Find و List این شناسه نادیده گرفته می شود.
شناسه یکتای درخواست به مدت ۲۴ ساعت معتبر خواهد بود و پس از آن نادیده گرفته خواهد شد.
این شناسه باید به فرمت GUID ارسال شود.
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
که x مقداری هگزادسیمال بین 0 تا F است.
مثال: 3adb4da2-a970-441e-96fd-9864a40d034d

نکته مهم

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

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

    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',
               yearId:'fiscal yearId',
               requestUniqueId:'request unique id'
               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’]
                }
             ]
}

نحوه پیکربندی، پیش نیاز ها، نکات ضروری در پیاده سازی رابط برنامه نویسی

requestUniqueId: شناسه یکتای درخواست

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

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

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