مستندات API ثبت سند حسابداری کاریا حساب | نمونه JSON

مرورگر شما از پخش ویدئو پشتیبانی نمی‌کند.

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

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

MethodPOST

Endpoint/DocEndpoint

Bodyapplication/json

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

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

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

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

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

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

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 برابر ۳ یا ۴ باشد، فیلدهای ردیف‌های بعدی نیز باید با همین الگو ارسال شوند.

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

در یک سند حسابداری معتبر، مجموع مبالغ بدهکار و بستانکار باید برابر باشد. بهتر است این کنترل در نرم‌افزار مبدأ و قبل از فراخوانی 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 یا استعلام نتیجه، ارسال مجدد خودکار توصیه نمی‌شود؛ زیرا ممکن است سند تکراری ایجاد شود.

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

چند لحظه صبر کنید...

برچسب: api