روش پیکربندی، پیشنیازها و نکتههای ضروری در پیادهسازی رابط برنامهنویسی
روش پیکربندی
واسط برنامهنویسی حسابفا (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: شناسه یکتای درخواست
- شناسۀ یکتای درخواست یا requestUniqueId: پیوست شناسۀ یکتای درخواست از پردازش درخواستهای تکراری جلوگیری میکند. اگر این شناسه را الصاق نکنید، تکراری بودن درخواست شما بررسی نخواهد شد.
- شناسۀ یکتای درخواست فقط در متدهایی کنترل میشود که مانند متدهایSave ، Delete و Set وظیفۀ تغییر یا ذخیرهسازی اطلاعات را دارند. این شناسه در متدهایی مثل Get ، Find و List که وظیفۀ گرفتن اطلاعات را دارند، نادیده گرفته میشود
- شناسۀ یکتای درخواست به مدت 24 ساعت معتبر است و پس از این بازۀ زمانی، نادیده گرفته خواهد شد.
- این شناسه باید به فرمت GUID فرستاده شود (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) که x یک مقدار هگزادسیمال بین 0 و F است. مثال: 3adb4da2-a970-441e-96fd-9864a40d034d
- سیستم API حسابفا در هر دقیقه از هر IP حداکثر به ۲۴۰ درخواست پاسخ میدهد.
مثالی از یک درخواست در جاوا اسکریپت و 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، یک شئی یا یک آرایه از اشیاء باشد.
توجه:
ErrorCode: کد خطا
ErrorMessage: متن خطا
Result: اگر عملیات با موفقیت انجام شود، نتیجۀ برگشتی از سمت سرور در این شیئ قرار میگیرد. این پارامتر میتواند NULL، یک شئی یا یک آرایه از اشیاء باشد.
پاسخ سرور در قالب JSON تنها در زمانی فرستاده میشود که مقدار HttpResponseCode برابر با ۲۰۰ است. اگر HttpResponseCode مقداری بهجز 200 باشد، عملیات دچار خطا میشود و پاسخی از سمت سرور ارسال نخواهد شد.
پارامتر queryInfo برای اعمال فیلتر و مرتبسازی روی لیستها
در متدهایی که برای دریافت لیست اشیاء (مانند گرفتن لیست اشخاص یا کالاها) فراخوانی میشوند، میتوانید از شیئ 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’]
}
]
}