مستندات وب‌سرویس (API) ثبت سند حسابداری

به مستندات وب‌سرویس بخش سند حسابداری نرم‌افزار کاریا حساب خوش آمدید.

با استفاده از این API، توسعه‌دهندگان می‌توانند نرم‌افزارهای اختصاصی، فروشگاه‌های اینترنتی یا سیستم‌های CRM خود را به سامانه کاریا متصل کرده و فاکتورهای فروش را به صورت خودکار و لحظه‌ای در سیستم ثبت نمایند.

این مستندات شامل تمامی اطلاعات لازم برای اتصال، احراز هویت و ارسال فاکتور به سیستم کاریا می‌باشد.

پیش‌نیاز اتصال به API

قبل از استفاده از وب‌سرویس، لازم است کاربر دسترسی رسمی API دریافت کند.

برای این منظور باید یک درخواست رسمی (نامه) به تیم پشتیبانی کاریا ارسال شود.

در این درخواست باید موارد زیر اعلام گردد:

• آدرس IP یا URL سرور (Webhook) که درخواست‌ها از آن ارسال می‌شوند
• درخواست فعال‌سازی دسترسی API

پس از بررسی، تیم فنی کاریا دسترسی لازم را در فایروال سیستم ایجاد کرده و اطلاعات زیر را در اختیار شما قرار می‌دهد:

اطلاعاتی که توسط کاریا ارائه می‌شود:

• mizekar : شناسه میزکار
• mizekaruser : شناسه کاربر میزکار
• userid : شناسه کاربر
• fiscalyear : شناسه سال مالی فعال
• Authorization : کلید احراز هویت API

این اطلاعات برای تمامی درخواست‌های API الزامی هستند.

وب‌سرویس ثبت سند حسابداری (DocEndpoint)

Method

POST

URL

https://panel.kariyahesab.com/DocEndpoint

Authentication

ارسال هدر Authorization الزامی است.

Headers

Authorization: {API_TOKEN}

Body Content Type

JSON

ساختار استاندارد بدنه درخواست (Body)

در این بخش تمام فیلدهای قابل ارسال در بدنه درخواست همراه با توضیحات رسمی آن‌ها آورده شده‌اند.

تمامی مقادیر باید به‌صورت JSON معتبر ارسال شوند.

۱. فیلدهای پایه سیستم

mizekar

شناسه میزکار فعال.

این مقدار باید به صورت عددی مطابق اطلاعات سیستم ارسال شود.

mizekaruser

شناسه کاربر میزکار.

این مقدار باید دقیقاً مطابق شناسه کاربر فعال ارسال شود.

fiscalyear

شناسه سال مالی فعال.

این مقدار معمولاً توسط کلاینت از بخش Login یا تنظیمات اولیه دریافت می‌شود.

enteshar

وضعیت انتشار سند.

در حالت ثبت اولیه باید مقدار 0 ارسال شود.

userid

شناسه کاربر ثبت‌کننده سند.

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

۲. اطلاعات مربوط به شماره سند

doc_num

شماره سند حسابداری.

اگر مقدار مشخصی برای این فیلد تعیین شده باشد باید همان مقدار ارسال شود.

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

doc_date

تاریخ سند حسابداری.

• ارسال این فیلد الزامی است.
• فرمت مجاز تاریخ فقط به‌صورت عددی و مطابق الگو:

  1404/01/01

• ارسال هر نوع فرمت دیگر نامعتبر است.
• سند بدون تاریخ پذیرفته نمی‌شود.

farei

شماره فرعی سند.

• اگر شماره فرعی مشخص شده باشد باید ارسال شود.
• در صورت عدم وجود شماره فرعی، این فیلد باید خالی بماند تا سیستم مقدار مناسب تولید کند.

atf

شماره عطف سند.

• در صورت وجود شماره عطف، مقدار آن باید ارسال شود.
• در غیر این صورت این فیلد خالی ارسال شود.

۳. اطلاعات مربوط به پروژه و شعبه

project

کد پروژه سند حسابداری.

• فقط در صورتی باید مقدار داشته باشد که یک پروژه معتبر در سیستم انتخاب شده باشد.
• در حالت پیش‌فرض این فیلد باید خالی باشد.

branch

کد شعبه سند.

• فقط در صورتی مقداردهی می‌شود که یک شعبه معتبر انتخاب شده باشد.
• در حالت عادی باید خالی ارسال شود.

۴. شرح کلی سند

name

شرح عمومی سند حسابداری.

• این مقدار باید بین 10 تا 250 کاراکتر باشد.
• شرح باید به‌صورت متنی و مرتبط با ماهیت سند ثبت گردد.

۵. تعداد ردیف‌های سند

rownumber

تعداد ردیف‌های سند حسابداری.

مقدار معتبر:

2
3
4

در صورت ارسال مقدار خارج از بازه فوق، عملیات ثبت سند نامعتبر خواهد بود.

۶. فیلدهای ردیف اول سند

moein1

کد حساب معین ردیف اول.

ارسال مقدار معتبر برای این فیلد الزامی است.

tafsil1

کد تفصیل ردیف اول.

اگر حساب معین این ردیف تفصیل‌پذیر باشد باید مقدار معتبر ارسال شود.

اگر حساب معین تفصیل‌ناپذیر باشد این فیلد باید خالی باشد.

sectafsil1, thridtafsil1, fourthtafsil1

در صورت عدم نیاز به تفصیل‌های چندمرحله‌ای، این فیلدها باید خالی ارسال شوند.

des1

شرح ردیف اول سند.

• باید بین 10 تا 250 کاراکتر باشد.
• شرح نباید خالی ارسال شود.

bedehkar1

مبلغ بدهکار ردیف اول.

• مقدار باید فقط عدد صحیح باشد.
• عدد منفی، اعشار، متن یا علامت مجاز نیست.
• در صورت نبود مبلغ، مقدار 0 ارسال شود.

bestankar1

مبلغ بستانکار ردیف اول.

قواعد مشابه بدهکار: فقط عدد یا صفر.

codehesab1

توضیحات تکمیلی مربوط به حساب. ارسال مقدار ضروری نیست.

۷. فیلدهای ردیف دوم سند

moein2

کد حساب معین ردیف دوم.

ارسال مقدار معتبر اجباری است.

tafsil2

کد تفصیل ردیف دوم.

بسته به تفصیل‌پذیر بودن حساب معین تعیین می‌شود.

sectafsil2, thridtafsil2, fourthtafsil2

در صورت عدم نیاز، این مقادیر خالی ارسال می‌شوند.

des2

شرح ردیف دوم.

• نباید خالی باشد.
• بین 10 تا 250 کاراکتر.

bedehkar2 / bestankar2

فقط عدد صحیح یا صفر.

بدون اعشار، بدون منفی، بدون متن.

codehesab2

اختیاری.

۸. فیلدهای ردیف سوم (در صورتی که rownumber ≥ 3 باشد)

moein3

کد معین ردیف سوم (الزامی در صورت وجود این ردیف).

tafsil3

تفصیل ردیف سوم در صورت تفصیل‌پذیر بودن حساب.

des3

شرح ردیف سوم

حداقل 10 و حداکثر 250 کاراکتر.

bedehkar3 / bestankar3

فقط عدد صحیح یا صفر.

codehesab3

اختیاری.

۹. فیلدهای ردیف چهارم (در صورتی که rownumber = 4 باشد)

moein4

کد حساب معین ردیف چهارم.

tafsil4

کد تفصیل ردیف چهارم.

sectafsil4, thridtafsil4, fourthtafsil4

در صورت نیاز ارسال شود، در غیر این صورت خالی.

des4

شرح ردیف چهارم (۱۰ تا ۲۵۰ کاراکتر).

bedehkar4 / bestankar4

فقط عدد صحیح یا صفر.

codehesab4

اختیاری.

نمونه JSON Body

{
  "ok": 1,
  "mizekar": "1020",
  "mizekaruser": "5011",
  "fiscalyear": "1404",
  "enteshar": 0,
  "userid": "220",

  "doc_num": "",
  "doc_date": "1404/02/15",
  "farei": "",
  "atf": "",
  "project": "",
  "branch": "",
  "name": "ثبت هزینه خرید لوازم مصرفی و پرداخت از حساب بانک",

  "rownumber": 3,

  "moein1": "5101",
  "tafsil1": "24001",
  "des1": "هزینه خرید لوازم مصرفی بخش اداری",
  "bedehkar1": 3500000,
  "bestankar1": 0,

  "moein2": "1102",
  "tafsil2": "10015",
  "des2": "پرداخت وجه از حساب بانک ملت",
  "bedehkar2": 0,
  "bestankar2": 3500000,

  "moein3": "8101",
  "tafsil3": "",
  "des3": "تسویه طرف حساب مرتبط با هزینه ثبت شده",
  "bedehkar3": 0,
  "bestankar3": 0,

  "moein4": "",
  "tafsil4": "",
  "des4": "",
  "bedehkar4": 0,
  "bestankar4": 0
}