در حال بارگذاری ...
وبسرویس تعریف کالا و خدمات کاریا حساب به توسعهدهندگان اجازه میدهد اطلاعات پایه محصول یا خدمت را با یک درخواست POST و بدنه JSON از فروشگاه اینترنتی، CRM، نرمافزار انبار یا سامانه سازمانی به نرمافزار کاریا حساب منتقل کنند.
Method
POST
Content-Type
application/json
Authentication Header
Authorization: YOUR_API_TOKEN
Endpoint
https://panel.kariyahesab.com/DefinitionEndpoint/product
این API چه کاری انجام میدهد؟
این Endpoint برای ایجاد یک رکورد کالا یا خدمت در کاریا حساب استفاده میشود. در هر درخواست، شناسههای میزکار و سال مالی همراه با مشخصات آیتم—از جمله کد، نام، شناسه کالا یا خدمت، واحد اندازهگیری، نرخ ارزش افزوده، قیمت و توضیحات—ارسال میشوند. نتیجه مطلوب این است که تعریف اولیه کالا بدون ورود دوباره اطلاعات در پنل انجام شود.
- ثبت خودکار کالاهای فروشگاه اینترنتی در کاریا حساب
- انتقال فهرست خدمات از CRM یا نرمافزار اختصاصی
- همگامسازی اطلاعات پایه کالا میان انبار و سیستم مالی
- کاهش ورود دستی و خطاهای ناشی از ثبت چندباره اطلاعات
محدوده این Endpoint: این وبسرویس برای «تعریف کالا یا خدمت» است و بهتنهایی فاکتور فروش ایجاد نمیکند. برای ثبت فاکتور پس از تعریف کالا، مستندات API فاکتور فروش کاریا حساب را ببینید.
پیشنیاز دریافت دسترسی API
پیش از ارسال درخواست، دسترسی API باید توسط تیم کاریا فعال شود. در روال فعلی فعالسازی، اطلاعات سرور درخواستکننده بررسی و مقادیر اختصاصی حساب در اختیار توسعهدهنده قرار میگیرد.
- درخواست فعالسازی وبسرویس را برای تیم پشتیبانی یا فنی کاریا ارسال کنید.
- IP ثابت یا URL سروری را که درخواستها از آن ارسال میشوند اعلام کنید.
- توکن
Authorizationو شناسههایmizekar،mizekaruser،useridوfiscalyearرا دریافت کنید. - اتصال را ابتدا با یک کالای آزمایشی و اطلاعات غیرحساس بررسی کنید.
- پس از تأیید پاسخ و مشاهده رکورد در پنل، همگامسازی انبوه را فعال کنید.
هشدار امنیتی: توکن API را در JavaScript مرورگر، کد قالب سایت، اپلیکیشن عمومی یا مخزن کد قرار ندهید. درخواست باید از سمت سرور ارسال شود و توکن در متغیر محیطی یا مخزن امن اسرار نگهداری شود.
آدرس وبسرویس و متد درخواست
Endpoint
https://panel.kariyahesab.com/DefinitionEndpoint/productHTTP Method
POSTبه حروف بزرگ و کوچک مسیر Endpoint توجه کنید و همان آدرس درجشده در مستندات را بدون تغییر استفاده کنید.
احراز هویت و Headerهای درخواست
توکن دسترسی باید در هدر Authorization ارسال شود. در الگوی فعلی مستندات کاریا، پیشوند Bearer ذکر نشده است؛ بنابراین مقدار دریافتی از تیم پشتیبانی را دقیقاً طبق نمونه زیر قرار دهید.
Request Headers
Authorization: YOUR_API_TOKEN
Content-Type: application/json
Accept: application/jsonپارامترهای سیستمی
این چهار مقدار به میزکار، کاربر و سال مالی فعال مربوطاند و هنگام فعالسازی API در اختیار شما قرار میگیرند.
| فیلد | توضیح | وضعیت | مقدار |
|---|---|---|---|
mizekar |
شناسه میزکار فعال | الزامی | مقدار اختصاصی دریافتی از کاریا |
mizekaruser |
شناسه کاربر میزکار | الزامی | مقدار اختصاصی دریافتی از کاریا |
userid |
شناسه کاربر ثبتکننده اطلاعات | الزامی | مقدار اختصاصی دریافتی از کاریا |
fiscalyear |
شناسه سال مالی فعال | الزامی | مقدار اختصاصی دریافتی از کاریا |
پارامترهای تعریف کالا و خدمات
| فیلد | توضیح | وضعیت | قالب و محدودیت |
|---|---|---|---|
kalaorkhad |
نوع رکورد | الزامی | 1 برای کالا و 2 برای خدمت |
kalacode |
کد داخلی کالا یا خدمت | الزامی | رشته عددی، حداقل ۱ و حداکثر ۱۰ رقم |
name |
نام کالا یا خدمت | الزامی | رشته متنی، حداکثر ۲۵۰ کاراکتر |
shenasekala |
شناسه کالا یا خدمت | الزامی | رشته عددی دقیقاً ۱۳ رقمی |
arzeshafzode |
نرخ مالیات و عوارض ارزش افزوده | الزامی | عدد بین ۰ تا ۹۹؛ نرخ متناسب با کالا یا خدمت ارسال شود |
price |
قیمت کالا یا خدمت | اختیاری | مقدار عددی؛ واحد پول باید پیش از پیادهسازی با تیم فنی تأیید شود |
des |
توضیحات تکمیلی | اختیاری | رشته متنی |
measurement_units |
کد واحد اندازهگیری | الزامی | کد معتبر دریافتشده از ابزار واحد اندازهگیری در کاریا |
چرا کدها بهصورت 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 با سایر ابزارهای کاریا حساب
- کالا و خدمات تعریفشده میتوانند در فرایندهای نرمافزار حسابداری ابری کاریا حساب استفاده شوند.
- برای ثبت و مدیریت صورتحسابهای الکترونیکی، امکانات نرمافزار سامانه مودیان کاریا حساب را بررسی کنید.
- اگر مجموعه شما علاوه بر اتصال نرمافزاری به اجرای امور مالی و مالیاتی نیاز دارد، صفحه خدمات شرکت حسابداری کاریا حساب مسیر مرتبط است.
سؤالات متداول API تعریف کالا و خدمات
آیا میتوان API را مستقیماً از مرورگر فراخوانی کرد؟
بهتر است خیر. قرار دادن توکن در کد سمت کاربر آن را در معرض مشاهده قرار میدهد. درخواست را از Backend، سرور فروشگاه یا سرویس واسط امن ارسال کنید.
مقدار Authorization باید با Bearer ارسال شود؟
در الگوی فعلی مستندات کاریا، هدر به شکل Authorization: YOUR_API_TOKEN معرفی شده و پیشوند Bearer ذکر نشده است. مقدار را دقیقاً مطابق دستور تیم فنی ارسال کنید.
برای تعریف خدمت، چه مقداری ارسال میشود؟
در فیلد kalaorkhad مقدار 2 برای خدمت و مقدار 1 برای کالا در نظر گرفته شده است.
کد واحد اندازهگیری را از کجا دریافت کنیم؟
کد معتبر باید از ابزار یا فهرست واحدهای اندازهگیری در سیستم کاریا دریافت شود. از کد نمونه مستندات بدون بررسی در محیط واقعی استفاده نکنید.
آیا این API کالا را به سامانه مودیان ارسال میکند؟
این Endpoint برای تعریف کالا یا خدمت در کاریا حساب است. تعریف کالا با ثبت یا ارسال صورتحساب الکترونیکی یک عملیات جداگانه محسوب میشود.
چرا نمونه HTTP قبلی خطا میداد؟
مسیر درخواست باید با Endpoint اصلی یکسان باشد. مسیر صحیح این مستند /DefinitionEndpoint/product است و نباید با /ProductEndpoint جایگزین شود.
فعالسازی و تست وبسرویس
پس از دریافت توکن و شناسههای اختصاصی از تیم کاریا، اتصال را با یک رکورد آزمایشی بررسی و نتیجه را در پنل کنترل کنید.
ورود به پنل کاریا حساب
نظر شما برای ما مهم است