مستندات

رابط برنامه‌نویسی

حسابفا

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

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

روش پیکربندی

واسط برنامه‌نویسی حسابفا (API) یک REST API مبتنی بر پروتکل HTTP است. هر عملیات به‌صورت یک متد در سمت سرور پیاده‌سازی شده و برنامه‌نویس می‌تواند آن را مستقیماً فراخوانی کند. داده‌های ارسالی و دریافتی در قالب JSON هستند و پاسخ همۀ متدها ساختار مشخصی دارد که در ادامه توضیح داده شده است.

پیش‌نیازها

apiKey: مجوز استفاده از API حسابفا با apiKey تأیید می‌شود. apiKey برای هر کسب‌وکار یکتاست و معرف همان کسب‌وکار است.
برای دریافت این کلید، در حسابفا به بخش تنظیمات > تنظیمات مالی > API بروید.
loginToken: توکن ورود به کسب‌وکار
این توکن را می‌توانید در حسابفا، بخش تنظیمات > تنظیمات مالی > API دریافت کنید.
userId: ایمیل یا شماره موبایل صاحب کسب‌وکار که با آن وارد حسابفا می‌شوید.
password: کلمۀ عبور صاحب کسب‌وکار که با آن وارد حسابفا می‌شوید.

نکات ضروری

apiKey و loginToken به کسب‌وکار شما دسترسی کامل می‌دهند؛ آن‌ها را در کد صفحه‌های عمومی وب‌سایت قرار ندهید.
احراز هویت به دو روش انجام می‌شود:
از طریق loginToken
از طریق userId و password صاحب کسب‌وکار
اگر loginToken ارسال شود، نیازی به ارسال userId و password نیست؛ در غیر این صورت، احراز هویت با userId و password انجام می‌شود.
همۀ درخواست‌ها باید با روش POST ارسال شوند.
بدنۀ درخواست یک Object JSON مسطح است؛ یعنی apiKey، loginToken (یا userId/password) و سایر پارامترهای هر متد، همگی در یک سطح و کنار هم در همان Object اصلی قرار می‌گیرند، بدون هیچ پوششی دور آن‌ها. مثال آن را در پایین همین صفحه ببینید.
همۀ تاریخ‌ها در API حسابفا میلادی هستند. در درخواست، قالب YYYY-MM-DD HH:MM:SS (یا YYYY-MM-DDTHH:MM:SS) پذیرفته می‌شود و تاریخ‌ها در پاسخ با قالب YYYY-MM-DDTHH:MM:SS برگردانده می‌شوند.
تعداد درخواست‌ها از هر IP محدود است. حداکثر 120 درخواست در دقیقه (2 درخواست در ثانیه) را با اطمینان می‌توانید ارسال کنید؛ ارسال تعداد زیادی درخواست به‌صورت هم‌زمان یا پشت‌سرهم، با خطای 101 روبه‌رو می‌شود. اگر خطای 101 دریافت کردید، دست‌کم 10 ثانیه هیچ درخواستی ارسال نکنید؛ هر درخواست در این مدت، محدودیت را تمدید می‌کند.

توجه

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

نکات مهم

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

ارسال شناسۀ یکتای درخواست (requestUniqueId) از پردازش دوبارۀ درخواست‌های تکراری جلوگیری می‌کند. اگر این شناسه ارسال نشود، تکراری بودن درخواست بررسی نمی‌شود.
شناسۀ یکتای درخواست فقط در متدهایی بررسی می‌شود که مانند Save، Delete و Set اطلاعات را تغییر می‌دهند یا ذخیره می‌کنند. در متدهایی مانند Get، Find و List که فقط اطلاعات را دریافت می‌کنند، این شناسه نادیده گرفته می‌شود.
شناسۀ یکتای درخواست 24 ساعت معتبر است و پس از آن نادیده گرفته می‌شود.
اگر درخواستی با شناسۀ تکراری ارسال شود، دوباره پردازش نمی‌شود و خطای 120 (Duplicate request id) برمی‌گردد.
این شناسه باید در قالب GUID ارسال شود (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) که در آن x یک رقم هگزادسیمال بین 0 تا F است. مثال: 3adb4da2-a970-441e-96fd-9864a40d034d

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

    var option = {
           method: 'POST',
           url: 'https://api.hesabfa.com/v1/contact/save',
           contentType: 'application/json',
           data: JSON.stringify({
               apiKey: 'business api key',
               loginToken: 'business login token',
               yearId: 1,
               requestUniqueId: '3adb4da2-a970-441e-96fd-9864a40d034d',
               contact: {
                   name: 'نام شخص',
                   contactType: 1,
                   city: 'تهران',
                   mobile: '09121234567',
                   phone: '02188123456'
               }
           })
       }
       $.ajax(option).done(function (result) {
           if (result.Success) {
               var r = result.Result;
           }
       }).fail(function () {
       });

در این مثال، بدنۀ درخواست با contentType: 'application/json' و JSON.stringify به‌صورت JSON ارسال می‌شود. اگر data را بدون این دو بفرستید، jQuery آن را به‌صورت فرم ارسال می‌کند و API با خطای HTTP 415 پاسخ می‌دهد.

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

همان‌طور که گفته شد، پاسخ متدهای API در قالب JSON است و همۀ آن‌ها ساختار زیر را دارند:

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

Success: وضعیت کلی پاسخ؛ اگر عملیات موفق باشد true و در غیر این صورت false است.
ErrorCode: کد خطا (جدول کدهای خطا)
ErrorMessage: متن خطا
Result: اگر عملیات موفق باشد، نتیجه در این فیلد قرار می‌گیرد. مقدار آن می‌تواند null، یک Object یا آرایه‌ای از Objectها باشد.

توجه:

پاسخ با ساختار بالا فقط وقتی برگردانده می‌شود که کد وضعیت HTTP برابر 200 باشد؛ خطاهای منطقی (مانند پیدا نشدن یک Object) هم با کد 200 و Success برابر false برمی‌گردند. اگر کد وضعیت HTTP عددی جز 200 باشد (مثلاً 404 برای آدرس اشتباه، 405 برای روشی جز POST، یا 400 و 415 برای بدنۀ نادرست)، درخواست به متد نرسیده و پاسخ ساختار بالا را ندارد.

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

در متدهایی که فهرستی را برمی‌گردانند (مانند فهرست اشخاص یا کالاها)، می‌توانید با queryInfo نتایج را فیلتر یا مرتب کنید.

queryInfo یک Object با ساختار زیر است:

sortBy	نام فیلدی که مرتب‌سازی بر اساس آن انجام می‌شود
sortDesc	false = مرتب‌سازی صعودی true = مرتب‌سازی نزولی
take	حداکثر تعداد رکوردهای بازگشتی؛ اگر ارسال نشود، 10 در نظر گرفته می‌شود.
skip	تعداد رکوردهایی که از ابتدای فهرست نادیده گرفته می‌شوند.
search	عبارت جستجو؛ فقط همراه با searchFields اعمال می‌شود.
searchFields	آرایه‌ای از فیلدهایی که جستجو در آن‌ها انجام می‌شود. نام فیلدها باید دقیقاً مانند خروجی همان متد باشد (مثلاً Name، نه name).
filters	آرایه‌ای از Objectهای فیلتر. هر Object ساختار زیر را دارد:

property	نام فیلدی که فیلتر روی آن اعمال می‌شود. نکته: فقط فیلدهایی که در خروجی همان متد وجود دارند، قابل انتخاب‌اند و نام فیلد باید دقیقاً مانند خروجی باشد.
operator	نوع عملگر؛ یکی از موارد زیر: = (مساوی) != (نامساوی) > (بزرگ‌تر) >= (بزرگ‌تر یا مساوی) < (کوچک‌تر) * (شامل شود) ?* (شروع شود) *? (خاتمه یابد) in (در بین مقادیر یک آرایه)
value	مقداری که با فیلد مقایسه می‌شود

مثال:

{
     sortBy: 'Name',
     sortDesc: false,
     take: 10,
     skip: 0,
     filters:[
                {
                    property: 'Name',
                    operator: '*',
                    value: 'شرکت'
                },
                {
                    property: 'ContactCredit',
                    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']
                }
             ]
}