وب سرویس

نسخه شماره ۱

https://api.hesabit.com/v1/



معرفی

API حسابیت وب سرویسی مبتنی بر REST و OAuth 2.0 است که به توسعه دهندگان اجازه میدهد برنامه خود را به حسابیت متصل کنند .

از طریق این وب سرویس شما به تمامی بخش های مختلف حسابیت دسترسی دارید و می توانید اطلاعات را اضافه کنید ، بخوانید ، ویرایش کنید و حذف نمائید .

تعداد درخواست (Request) برای هر شناسه ۲۰,۰۰۰ بار در روز خواهد بود ، اگر بیش از این نیاز دارید حتما از طریق تیکت اطلاع دهید .


HTTP Methods

وب سرویس حسابیت ۴ متد HTTP را پشتیبانی می کند :

  • POST :

    از این مدل درخواست فقط برای ایجاد دیتای جدید استفاده می شود .

    مانند ایجاد فاکتور جدید

  • GET :

    این نوع درخواست فقط برای خواندن دیتای موجود اسفاده می شود .

    مانند خواندن لیست مشتریان

  • PUT :

    از این نوع درخواست فقط برای ویرایش دیتای موجود استفاده می شود .

    مانند ویرایش مشخصات یک محصول

  • DELETE :

    این نوع درخواست برای حذف دیتای موجود استفاده می شود .

    مانند حذف یک فاکتور


SSL

وب سرویس حسابیت فقط بروی HTTPS در دسترس است .

https://api.hesabit.com/v1/


JSON

وب سرویس حسابیت از json پشتیبانی میکند و درخواست ها و پاسخ ها به صورت json مبادله خواهد شد .

در Header در خواست ها باید مقدار Content-Type: application/json; وجود داشته باشد .


متغیر های آدرس

برخی مقادیر مانند شناسه ها (ID) در داخل آدرس قرار می گیرند (Path parameters) مانند زمانی که می خواهیم درخواست ویرایش محصول را ارسال کنیم شناسه محصول (Item ID) در آدرس قرار میگیرد : /items/{item_id}


پارامترهای درخواست

برخی مقادیر مانند تعداد رکورد ها (limit) به صورت کوئری در انتهای آدرس قرار می گیرند (Query parameters) مانند زمانی که می خواهیم فقط تعداد ۵ فاکتور (limit=5) پرداخت شده (status=paid) را بگیریم : /invoices?limit=5&status=paid


راهنمای سریع OAuth 2.0

اگر به دنبال جزئیات تنظیمات OAuth هستنید این صفحه را مطالعه کنید .


۱- Client

از طریق پنل کاربری یک client جدید ایجاد کنید .


۲- Authorization

درخواست دسترسی به اطلاعات کاربر باید از طریق آدرس زیر انجام شود . ( شما میتوانید این آدرس را در مروگر خود باز کنید )

        
https://www.hesabit.com/oauth2/authorize?client_id={client_id}&response_type=code&scope=write&access_type=offline&redirect_uri={redirect_uri}

دقت کنید که به جای {client_id} و {redirect_uri} مقادیر مربوط به Client که در مرحله قبل ساخته اید را قرار دهید .


۳- Access Token

پس از تائید مرحله قبل مقدار code به آدرسی redirect_uri شما ارسال می شود و در این مرحله باید یک درخواست از نوع POST به آدرس زیر ارسال کنید و در جواب access_token را دریافت کنید .

        
https://api.hesabit.com/oauth2/token
محتوی درخواست POST : 
        
{
    "code":"{مقدار کد دریافت شده در این مرحله}",
    "grant_type":"authorization_code",
    "client_id":"{شناسه دریافت شده در پنل کاربری}",
    "client_secret":"{مقدار دریافت شده در پنل کاربری}",
    "redirect_uri":"{آدرس بازگشت}"
}

در پارسخ به این درخواست Access Token و Refresh Token مانند نمونه زیر برای شما ارسال می شود .

نمونه پاسخ به درخواست قبل : 
        
{
    "access_token": "06fea353-98cc-4aac-9acf-3eb82e65ec48",
    "token_type": "Bearer",
    "expires_in": 36000,
    "refresh_token": "12fea35c-98cc-4aac-a1cb-2eb82e61ec11",
    "scope": "write"
}

۴- اتصال به وب سرویس

برای کار با وبسرویس کافی است مقدار access_token که در مرحله قبل دریافت کردید در نشانی درخواست ها قرار دهید . (همه درخواست ها به API باید همراه با aceess_token باشد)

        
https://api.hesabit.com/v1/invoices/?access_token=06fea353-98cc-4aac-9acf-3eb82e65ec48

۵- Resfresh Token

هر access_token فقط برای ۱۰ ساعت معتبر است و پس از آن منقضی خواهد شد و برای دریافت access_token جدید باید از طریق refresh_token یک access_token جدید بگیرید . برای اینکار یک درخواست از نوع POST به صورت زیر ارسال کنید .

        
https://api.hesabit.com/oauth2/token
محتوی درخواست POST : 
        
{
    "client_id":"{شناسه دریافت شده در پنل کاربری}",
    "grant_type":"refresh_token",
    "client_secret":"{مقدار دریافت شده در پنل کاربری}",
    "refresh_token":"{توکن دریافت شده در مرحله قبل}"
}
نمونه پاسخ به درخواست قبل : 
        
{
    "access_token": "36fea351-18cc-4aac-9acf-1eb82e65ec33",
    "token_type": "Bearer",
    "expires_in": 36000,
    "scope": "write"
}