مستندات API تعریف کالا و خدمات کاریا حساب | راهنمای اتصال

Method POST

Content-Type application/json

این API چه کاری انجام می‌دهد؟

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

• ثبت خودکار کالاهای فروشگاه اینترنتی در کاریا حساب
• انتقال فهرست خدمات از CRM یا نرم‌افزار اختصاصی
• همگام‌سازی اطلاعات پایه کالا میان انبار و سیستم مالی
• کاهش ورود دستی و خطاهای ناشی از ثبت چندباره اطلاعات

محدوده این Endpoint: این وب‌سرویس برای «تعریف کالا یا خدمت» است و به‌تنهایی فاکتور فروش ایجاد نمی‌کند. برای ثبت فاکتور پس از تعریف کالا، مستندات API فاکتور فروش کاریا حساب را ببینید.

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

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

• درخواست فعال‌سازی وب‌سرویس را برای تیم پشتیبانی یا فنی کاریا ارسال کنید.
• IP ثابت یا URL سروری را که درخواست‌ها از آن ارسال می‌شوند اعلام کنید.
• توکن Authorization و شناسه‌های mizekar، mizekaruser، userid و fiscalyear را دریافت کنید.
• اتصال را ابتدا با یک کالای آزمایشی و اطلاعات غیرحساس بررسی کنید.
• پس از تأیید پاسخ و مشاهده رکورد در پنل، همگام‌سازی انبوه را فعال کنید.

آدرس وب‌سرویس و متد درخواست

Endpoint

https://panel.kariyahesab.com/DefinitionEndpoint/product HTTP Method

POST به حروف بزرگ و کوچک مسیر Endpoint توجه کنید و همان آدرس درج‌شده در مستندات را بدون تغییر استفاده کنید.

احراز هویت و Headerهای درخواست

توکن دسترسی باید در هدر Authorization ارسال شود. در الگوی فعلی مستندات کاریا، پیشوند Bearer ذکر نشده است؛ بنابراین مقدار دریافتی از تیم پشتیبانی را دقیقاً طبق نمونه زیر قرار دهید.

Request Headers

Authorization: YOUR_API_TOKEN Content-Type: application/json Accept: application/json پارامترهای سیستمی این چهار مقدار به میزکار، کاربر و سال مالی فعال مربوط‌اند و هنگام فعال‌سازی API در اختیار شما قرار می‌گیرند.

پارامترهای تعریف کالا و خدمات

چرا کدها به‌صورت String ارسال شده‌اند؟ فیلدهایی مانند kalacode و shenasekala شناسه‌اند، نه مقدار قابل محاسبه. ارسال آن‌ها به شکل رشته، از حذف صفرهای ابتدایی یا تغییر ناخواسته عدد در برخی زبان‌ها و پایگاه‌های داده جلوگیری می‌کند.

برای آشنایی عمومی با استانداردهای شماره‌گذاری و شناسایی کالاها می‌توانید به مرکز ملی شماره‌گذاری کالا و خدمات ایران مراجعه کنید. بااین‌حال، مقدار قابل قبول فیلد shenasekala را براساس اطلاعات محصول و الزامات جاری کاریا و سامانه مودیان کنترل کنید.

نمونه بدنه JSON

مقادیر زیر صرفاً نمونه آموزشی‌اند. شناسه‌های میزکار، کاربر، سال مالی، شناسه کالا و کد واحد اندازه‌گیری را با مقادیر واقعی حساب خود جایگزین کنید.

JSON Request Body

{ "mizekar": 10, "mizekaruser": 10, "userid": 88718, "fiscalyear": 5730, "name": "کالای نمونه", "kalacode": "12334566", "kalaorkhad": "1", "price": "10000", "des": "ثبت آزمایشی از طریق API", "shenasekala": "4111111111111", "measurement_units": "6214", "arzeshafzode": "10" } نمونه درخواست cURL cURL

curl --request POST --url "https://panel.kariyahesab.com/DefinitionEndpoint/product" --header "Authorization: YOUR_API_TOKEN" --header "Accept: application/json" --header "Content-Type: application/json" --data '{ "mizekar": 10, "mizekaruser": 10, "userid": 88718, "fiscalyear": 5730, "name": "کالای نمونه", "kalacode": "12334566", "kalaorkhad": "1", "price": "10000", "des": "ثبت آزمایشی از طریق API", "shenasekala": "4111111111111", "measurement_units": "6214", "arzeshafzode": "10" }' نمونه کامل درخواست HTTP Raw HTTP Request

POST /DefinitionEndpoint/product HTTP/1.1 Host: panel.kariyahesab.com Authorization: YOUR_API_TOKEN Accept: application/json Content-Type: application/json { "mizekar": 10, "mizekaruser": 10, "userid": 88718, "fiscalyear": 5730, "name": "کالای نمونه", "kalacode": "12334566", "kalaorkhad": "1", "price": "10000", "des": "ثبت آزمایشی از طریق API", "shenasekala": "4111111111111", "measurement_units": "6214", "arzeshafzode": "10" } اعتبارسنجی قبل از ارسال درخواست هدرهای Authorization و Content-Type ارسال شده باشند. هر چهار شناسه سیستمی متعلق به یک میزکار و سال مالی فعال باشند. kalaorkhad فقط یکی از مقادیر 1 یا 2 باشد. kalacode بین ۱ تا ۱۰ رقم و shenasekala دقیقاً ۱۳ رقم باشد. کد measurement_units از اطلاعات معتبر داخل کاریا دریافت شده باشد. نرخ arzeshafzode با وضعیت واقعی کالا یا خدمت تطبیق داده شود. واحد پول فیلد price پیش از اتصال عملیاتی با تیم کاریا تأیید شود. پیش از Retry، مشخص شود درخواست قبلی ثبت شده است یا خیر تا کالای تکراری ایجاد نشود. پاسخ API و مدیریت خطاها در اطلاعات فعلی، نمونه بدنه پاسخ موفق، فهرست کدهای وضعیت HTTP و ساختار خطاهای این Endpoint اعلام نشده است. بنابراین کلاینت نباید متن پاسخ یا یک کد حدسی را مبنای ثبت موفق قرار دهد. هنگام دریافت دسترسی، قرارداد پاسخ را از تیم فنی دریافت و همان را در برنامه پیاده‌سازی کنید.

• کد HTTP و بدنه پاسخ در ثبت موفق
• پاسخ توکن نامعتبر یا IP تأییدنشده
• رفتار سیستم در صورت تکراری بودن kalacode یا shenasekala
• خطای شناسه واحد اندازه‌گیری یا سال مالی نامعتبر
• محدودیت نرخ درخواست‌ها (Rate Limit)
• وجود یا نبود سازوکار Idempotency برای Retry امن

در لاگ برنامه، زمان درخواست، Endpoint، شناسه داخلی محصول و کد وضعیت را ذخیره کنید؛ اما توکن Authorization و اطلاعات حساس را در لاگ ننویسید.

ارتباط این API با سایر ابزارهای کاریا حساب

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

فعال‌سازی و تست وب‌سرویس

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