مستندات API ثبت سند حسابداری کاریا حساب

وب‌سرویس ثبت سند حسابداری کاریا حساب به توسعه‌دهندگان اجازه می‌دهد رویدادهای مالی نرم‌افزار اختصاصی، فروشگاه اینترنتی، CRM یا سیستم عملیاتی خود را به شکل سند حسابداری در کاریا حساب ثبت کنند. در این راهنما Endpoint، روش احراز هویت، فیلدهای سربرگ و ردیف‌های سند، نمونه JSON و کنترل‌های ضروری پیش از ارسال درخواست توضیح داده شده است.

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

MethodPOST

Endpoint/DocEndpoint

Bodyapplication/json

پیش از پیاده‌سازی: این صفحه بر اساس قرارداد فعلی ارائه‌شده برای کاریا حساب تنظیم شده است. ساختار پاسخ موفق، کدهای خطا، واحد پول، محدودیت تعداد درخواست و سازوکار جلوگیری از ثبت تکراری در متن اولیه مشخص نشده‌اند؛ این موارد را پیش از اتصال محیط عملیاتی از تیم فنی دریافت کنید.

پیش‌نیاز دریافت دسترسی API

دسترسی این وب‌سرویس به‌صورت عمومی فعال نیست. برای شروع، درخواست فعال‌سازی API را برای پشتیبانی کاریا حساب ارسال کرده و IP یا URL ثابت سروری را که درخواست‌ها از آن ارسال می‌شوند اعلام کنید. پس از تأیید، تیم فنی دسترسی لازم را ایجاد و شناسه‌های موردنیاز را در اختیار شما قرار می‌دهد.

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

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

Endpoint ثبت سند حسابداری

بخش	مقدار	توضیح
Method	`POST`	ایجاد سند حسابداری
URL	`https://panel.kariyahesab.com/DocEndpoint`	آدرس کامل Endpoint
Authorization	`Authorization: YOUR_API_TOKEN`	توکن ارائه‌شده توسط کاریا؛ در مستند فعلی پیشوند Bearer ذکر نشده است.
Content-Type	`application/json`	بدنه درخواست باید JSON معتبر باشد.

Authorization: YOUR_API_TOKEN
Content-Type: application/json

پارامترهای سربرگ سند

پارامتر	وضعیت	مقدار یا قالب	توضیح
`mizekar`	الزامی	شناسه ارائه‌شده	شناسه میزکار فعال
`mizekaruser`	الزامی	شناسه ارائه‌شده	شناسه کاربر میزکار
`fiscalyear`	الزامی	شناسه سال مالی	باید با سال مالی فعال و تاریخ سند سازگار باشد.
`enteshar`	الزامی	`0`	طبق قرارداد فعلی، برای ثبت اولیه مقدار صفر ارسال می‌شود.
`userid`	الزامی	شناسه کاربر	کاربری که سند به نام او ثبت می‌شود.
`doc_num`	مشروط	شماره سند یا رشته خالی	اگر شماره‌گذاری خودکار است، مقدار خالی ارسال شود. پیش از تعیین دستی شماره، قانون یکتایی آن را از پشتیبانی بپرسید.
`doc_date`	الزامی	`1405/05/01`	تاریخ شمسی با قالب عددی سال/ماه/روز
`farei`	اختیاری	شماره فرعی یا رشته خالی	در نبود مقدار، خالی ارسال شود.
`atf`	اختیاری	شماره عطف یا رشته خالی	در نبود مقدار، خالی ارسال شود.
`project`	اختیاری	کد پروژه معتبر یا رشته خالی	فقط زمانی مقداردهی شود که پروژه قبلاً در سیستم تعریف شده باشد.
`branch`	اختیاری	کد شعبه معتبر یا رشته خالی	فقط زمانی مقداردهی شود که شعبه معتبر انتخاب شده باشد.
`name`	الزامی	۱۰ تا ۲۵۰ کاراکتر	شرح عمومی و روشن درباره ماهیت سند
`rownumber`	الزامی	`2`، `3` یا `4`	تعداد ردیف‌های سند طبق قرارداد فعلی این Endpoint

ناسازگاری متن اولیه: در توضیحات، بعضی شناسه‌ها «عددی» معرفی شده‌اند اما در نمونه قبلی به‌شکل رشته ارسال شده بودند. نوع داده را دقیقاً مطابق قرارداد اعلامی تیم فنی پیاده‌سازی کنید و به تبدیل خودکار عدد و رشته توسط سرور متکی نباشید.

پارامترهای هر ردیف سند

برای هر ردیف، شماره ردیف به انتهای نام پارامتر اضافه می‌شود؛ برای مثال moein1 مربوط به ردیف اول و moein2 مربوط به ردیف دوم است. اگر rownumber برابر ۳ یا ۴ باشد، فیلدهای ردیف‌های بعدی نیز باید با همین الگو ارسال شوند.

الگوی پارامتر	وضعیت	توضیح
`moein{n}`	الزامی	کد حساب معین معتبر برای ردیف
`tafsil{n}`	مشروط	اگر حساب معین تفصیل‌پذیر است، کد تفصیل معتبر؛ در غیر این صورت خالی
`sectafsil{n}`	اختیاری/مشروط	کد سطح دوم تفصیل در صورت نیاز
`thridtafsil{n}`	اختیاری/مشروط	کد سطح سوم تفصیل؛ املای `thrid` مطابق نام فعلی فیلد API حفظ شود.
`fourthtafsil{n}`	اختیاری/مشروط	کد سطح چهارم تفصیل در صورت نیاز
`des{n}`	الزامی	شرح ردیف، بین ۱۰ تا ۲۵۰ کاراکتر
`bedehkar{n}`	الزامی	مبلغ بدهکار به‌صورت عدد صحیح نامنفی؛ در صورت نبود مبلغ، صفر
`bestankar{n}`	الزامی	مبلغ بستانکار به‌صورت عدد صحیح نامنفی؛ در صورت نبود مبلغ، صفر
`codehesab{n}`	اختیاری	اطلاعات تکمیلی حساب؛ در صورت نبود مقدار، خالی

کنترل تراز سند پیش از ارسال

در یک سند حسابداری معتبر، مجموع مبالغ بدهکار و بستانکار باید برابر باشد. بهتر است این کنترل در نرم‌افزار مبدأ و قبل از فراخوانی API انجام شود؛ حتی اگر سرور نیز سند نامتوازن را رد کند.

کنترل پیشنهادی در کلاینت:

مجموع bedehkar1 تا آخرین ردیف با مجموع bestankar1 تا آخرین ردیف برابر باشد.
برای هر ردیف، معمولاً فقط یکی از مبالغ بدهکار یا بستانکار بزرگ‌تر از صفر باشد.
تعداد مجموعه‌فیلدهای ارسال‌شده با مقدار rownumber تطابق داشته باشد.
کدهای معین، تفصیل، پروژه و شعبه پیش از ارسال در همان میزکار و سال مالی معتبر باشند.

نمونه JSON برای ثبت سند دو ردیفی

در نمونه زیر، مبلغ ۳٬۵۰۰٬۰۰۰ واحد پولی در حساب هزینه بدهکار و همان مبلغ در حساب بانک بستانکار شده است. شناسه‌ها صرفاً نمونه‌اند و باید با مقادیر واقعی محیط شما جایگزین شوند.

{
  "mizekar": 1020,
  "mizekaruser": 5011,
  "fiscalyear": 1405,
  "enteshar": 0,
  "userid": 220,
  "doc_num": "",
  "doc_date": "1405/05/01",
  "farei": "",
  "atf": "",
  "project": "",
  "branch": "",
  "name": "ثبت هزینه خرید لوازم مصرفی و پرداخت از حساب بانک",
  "rownumber": 2,
  "moein1": "5101",
  "tafsil1": "24001",
  "sectafsil1": "",
  "thridtafsil1": "",
  "fourthtafsil1": "",
  "des1": "هزینه خرید لوازم مصرفی بخش اداری",
  "bedehkar1": 3500000,
  "bestankar1": 0,
  "codehesab1": "",
  "moein2": "1102",
  "tafsil2": "10015",
  "sectafsil2": "",
  "thridtafsil2": "",
  "fourthtafsil2": "",
  "des2": "پرداخت وجه از حساب بانک ملت",
  "bedehkar2": 0,
  "bestankar2": 3500000,
  "codehesab2": ""
}

فیلد ok که در نمونه قبلی دیده می‌شد از نسخه جدید حذف شد، زیرا در توضیحات پارامترها تعریف نشده بود. اگر Backend واقعاً به این فیلد نیاز دارد، تیم فنی باید نام، نوع و مقادیر مجاز آن را به قرارداد رسمی API اضافه کند.

نمونه درخواست cURL

curl --request POST 
  --url 'https://panel.kariyahesab.com/DocEndpoint' 
  --header 'Authorization: YOUR_API_TOKEN' 
  --header 'Content-Type: application/json' 
  --data '{
    "mizekar": 1020,
    "mizekaruser": 5011,
    "fiscalyear": 1405,
    "enteshar": 0,
    "userid": 220,
    "doc_num": "",
    "doc_date": "1405/05/01",
    "farei": "",
    "atf": "",
    "project": "",
    "branch": "",
    "name": "ثبت هزینه خرید لوازم مصرفی و پرداخت از حساب بانک",
    "rownumber": 2,
    "moein1": "5101",
    "tafsil1": "24001",
    "sectafsil1": "",
    "thridtafsil1": "",
    "fourthtafsil1": "",
    "des1": "هزینه خرید لوازم مصرفی بخش اداری",
    "bedehkar1": 3500000,
    "bestankar1": 0,
    "codehesab1": "",
    "moein2": "1102",
    "tafsil2": "10015",
    "sectafsil2": "",
    "thridtafsil2": "",
    "fourthtafsil2": "",
    "des2": "پرداخت وجه از حساب بانک ملت",
    "bedehkar2": 0,
    "bestankar2": 3500000,
    "codehesab2": ""
  }'

پاسخ API و مدیریت خطا

در محتوای فعلی، نمونه پاسخ موفق، پاسخ خطا و کدهای HTTP این Endpoint ارائه نشده است. برای جلوگیری از برداشت اشتباه، پاسخ ساختگی در این راهنما قرار داده نشده و لازم است موارد زیر از تیم فنی دریافت و مستند شوند:

کد HTTP و ساختار JSON پاسخ موفق
شناسه یا شماره سند ایجادشده در پاسخ
خطاهای احراز هویت، IP غیرمجاز و سال مالی نامعتبر
خطاهای کد معین یا تفصیل نامعتبر، شرح کوتاه و سند نامتوازن
رفتار سرور هنگام Timeout و ارسال مجدد درخواست
محدودیت نرخ درخواست‌ها و حداکثر حجم Body

جلوگیری از ثبت سند تکراری

تا زمانی که وجود کلید Idempotency یا شناسه مرجع خارجی در قرارداد API تأیید نشده، درخواست Timeoutشده را بدون بررسی نتیجه قبلی دوباره ارسال نکنید. در غیر این صورت ممکن است یک رویداد مالی دو بار ثبت شود. برای هر رویداد در سیستم مبدأ یک شناسه یکتا، Hash درخواست و وضعیت پردازش نگهداری کنید و روش استعلام نتیجه را از تیم فنی بپرسید.

تفاوت سند حسابداری، فاکتور فروش و صورتحساب الکترونیکی

ثبت سند در DocEndpoint به معنی ثبت فاکتور فروش یا ارسال صورتحساب الکترونیکی به سازمان امور مالیاتی نیست. برای صدور فاکتور باید از وب‌سرویس مربوط به فروش استفاده شود و برای مدیریت فرآیندهای مالیاتی می‌توانید امکانات نرم‌افزار واسط سامانه مودیان کاریا حساب را بررسی کنید. اطلاعیه‌ها و مقررات مالیاتی نیز باید از منابع رسمی مانند رسانه مالیاتی ایران پیگیری شوند.

چک‌لیست استقرار در محیط عملیاتی

فعال‌سازی دسترسی و ثبت IP یا URL ثابت سرور
نگهداری توکن در Secret Manager یا متغیر امن سمت سرور
تطبیق شناسه سال مالی و تاریخ سند
اعتبارسنجی کدهای معین، تفصیل، پروژه و شعبه
کنترل تعداد ردیف، طول شرح‌ها و تراز بدهکار و بستانکار
ثبت امن درخواست و پاسخ بدون ذخیره‌سازی توکن در Log
آزمایش ابتدا با داده کنترل‌شده و تأیید نتیجه در پنل
تعریف فرآیند امن برای Timeout، Retry و جلوگیری از سند تکراری

پرسش‌های متداول API سند حسابداری

وب‌سرویس ثبت سند حسابداری چه کاری انجام می‌دهد؟

این وب‌سرویس اطلاعات سربرگ و ردیف‌های یک سند حسابداری را از سیستم مبدأ دریافت و در کاریا حساب ثبت می‌کند.

حداقل و حداکثر تعداد ردیف سند چقدر است؟

طبق قرارداد فعلی ارائه‌شده، مقدار rownumber می‌تواند ۲، ۳ یا ۴ باشد. برای تعداد بیشتر باید امکان آن از تیم فنی استعلام شود.

اگر شماره سند را ندانیم چه مقداری ارسال کنیم؟

در صورت استفاده از شماره‌گذاری خودکار، doc_num را به‌صورت رشته خالی ارسال کنید. نحوه بازگرداندن شماره ایجادشده باید در ساختار پاسخ API مشخص شود.

آیا سند باید تراز باشد؟

بله؛ مجموع بدهکار و بستانکار را پیش از ارسال برابر کنید. نمونه این صفحه نیز یک سند دو ردیفی تراز است.

آیا این API فاکتور را به سامانه مودیان ارسال می‌کند؟

خیر؛ این Endpoint برای ثبت سند حسابداری است. ثبت فاکتور فروش و ارسال صورتحساب الکترونیکی، فرآیندها و سرویس‌های جداگانه‌ای هستند.

در صورت قطع ارتباط، درخواست را دوباره ارسال کنیم؟

تا پیش از مشخص شدن سازوکار Idempotency یا استعلام نتیجه، ارسال مجدد خودکار توصیه نمی‌شود؛ زیرا ممکن است سند تکراری ایجاد شود.

برای اتصال مطمئن سیستم مالی به کاریا حساب

اگر برای انتخاب کدینگ، کنترل اسناد، پیاده‌سازی فرآیند مالی یا رسیدگی به مغایرت‌ها به همراهی تخصصی نیاز دارید، خدمات شرکت حسابداری کاریا حساب را ببینید. پس از دریافت دسترسی فنی نیز می‌توانید از پنل کاریا حساب نتیجه ثبت آزمایشی را کنترل کنید.