مثال استفاده API حسابداری
در مقاله قبل در مورد معرفی وب سرویس حسابداری صحبت کردیم در این مقاله قصد داریم در مورد مثال وب سرویس حسابداری توضیح دهیم.
مثالی از یک درخواست در جاوااسکریپت و 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”]
}
در این مقاله در مورد مثال وب سرویس حسابداری صحبت کردیم در مقاله بعد در مورد کدهای وب سرویس حسابداری توضیح خواهیم داد