مستندات API ایجاد شخص در کاریا حساب | تعریف مشتری
API ایجاد شخص در کاریا حساب برای ثبت مشتری، تأمینکننده، کارمند، تنخواهدار و سایر طرفحسابها از طریق فروشگاه اینترنتی، CRM، ERP یا نرمافزار اختصاصی استفاده میشود. این مستند، Endpoint، روش احراز هویت، پارامترها، قواعد اعتبارسنجی و نمونه درخواست را توضیح میدهد.
- 6 دقیقه مطالعه
- آخرین بهروزرسانی: ۲۲ اردیبهشت ۱۴۰۵
Method POST
Content-Type application/json
Authorization: YOUR_API_TOKEN
https://panel.kariyahesab.com/DefinitionEndpoint/customer
API تعریف شخص چه کاری انجام میدهد؟
«شخص» در سیستم حسابداری میتواند مشتری، فروشنده، کارمند، تنخواهدار یا طرفحساب دیگری باشد که در عملیات فروش، دریافت و پرداخت، انبار و ثبتهای مالی استفاده میشود. این API یک شخص جدید را در میزکار و سال مالی تعیینشده ایجاد میکند تا سیستمهای دیگر مجبور به ثبت دوباره اطلاعات در پنل کاریا نباشند.
- انتقال خودکار مشتری ثبتشده در فروشگاه اینترنتی به حسابداری
- ساخت طرفحساب از اطلاعات CRM یا سامانه فروش
- تعریف تأمینکننده برای فرایندهای خرید و انبار
- ایجاد کارمند یا تنخواهدار برای عملیات مالی مرتبط
- کاهش ورود دستی و مغایرت اطلاعات هویتی میان سیستمها
محدوده Endpoint: این درخواست فقط شخص یا طرفحساب را تعریف میکند. ثبت شخص به معنی ایجاد فاکتور یا ارسال صورتحساب به سامانه مودیان نیست. برای مرحله بعد، مستندات API فاکتور فروش کاریا حساب را ببینید.
پیشنیاز فعالسازی وبسرویس
- درخواست فعالسازی API را برای تیم پشتیبانی یا فنی کاریا ارسال کنید.
- IP ثابت یا URL سروری را که درخواستها از آن ارسال میشوند اعلام کنید.
- توکن Authorization و شناسههای میزکار، کاربر و سال مالی را دریافت کنید.
- اتصال را ابتدا با اطلاعات آزمایشی و در میزکار موردنظر بررسی کنید.
- پس از مشاهده شخص ثبتشده در پنل، همگامسازی عملیاتی را فعال کنید.
حفاظت از اطلاعات: این API دادههای هویتی و تماس اشخاص را دریافت میکند. توکن، کد ملی، شناسه ملی و شماره موبایل را در JavaScript مرورگر، URL، پیام خطای عمومی یا لاگ بدون پوشش ذخیره نکنید. درخواست باید از سمت سرور و از مسیر HTTPS ارسال شود.
Endpoint، Method و Headerها
Endpoint
https://panel.kariyahesab.com/DefinitionEndpoint/customer HTTP Method
POST Request Headers
Authorization: YOUR_API_TOKEN Content-Type: application/json Accept: application/json در الگوی فعلی مستندات کاریا، پیشوند Bearer برای Authorization ذکر نشده است. توکن دریافتی را دقیقاً مطابق دستور تیم فنی در هدر قرار دهید.
پارامترهای سیستمی
پارامترهای زیر برای مشخص شدن میزکار، کاربر ثبتکننده و سال مالی استفاده میشوند و مستقل از نوع شخص، باید با مقادیر اختصاصی حساب شما ارسال شوند.
| فیلد | توضیح | وضعیت | مقدار |
|---|---|---|---|
| mizekar | شناسه میزکار فعال | الزامی | دریافتی از تیم کاریا |
| mizekaruser | شناسه کاربر میزکار دارای دسترسی API | الزامی | دریافتی از تیم کاریا |
| userid | شناسه کاربر ثبتکننده اطلاعات | الزامی | دریافتی از تیم کاریا |
| fiscalyear | شناسه سال مالی فعال | الزامی | دریافتی از تیم کاریا |
پارامترهای هویتی و تماس شخص
| فیلد | توضیح | وضعیت | قالب و محدودیت |
|---|---|---|---|
| name | نام شخص یا عنوان شرکت | الزامی | رشته متنی، حداکثر ۲۰۰ کاراکتر |
| address | نشانی شخص یا شرکت | اختیاری | رشته متنی، حداکثر ۵۰۰ کاراکتر |
| shakhskind | نوع هویتی شخص | الزامی | یکی از مقادیر ۱ تا ۵ طبق جدول نوع شخص |
| meli | کد ملی، شناسه ملی یا شماره فراگیر | مشروط | رشته عددی؛ طول براساس نوع شخص تعیین میشود |
| eghtesadi | کد اقتصادی یا مقدار هویتی متناظر | مشروط | رشته عددی؛ قواعد آن در جدول اعتبارسنجی آمده است |
| ostan | استان | در مستند فعلی مشخص نشده | رشته متنی |
| shahrestan | شهرستان | در مستند فعلی مشخص نشده | رشته متنی |
| shahr | شهر | در مستند فعلی مشخص نشده | رشته متنی |
| tel | تلفن ثابت | اختیاری | رشته عددی؛ برای حفظ صفر ابتدای پیششماره |
| mobile | شماره تلفن همراه | اختیاری | رشته عددی |
| sabtnum | شماره ثبت شرکت | اختیاری و مخصوص شخص حقوقی | رشته عددی، بین ۳ تا ۸ رقم |
| codeposti | کد پستی | الزامی؛ برای مصرفکننده نهایی نیازمند تأیید | رشته عددی دقیقاً ۱۰ رقمی |
| kindofwork | نقش طرفحساب | الزامی | یکی از مقادیر ۱ تا ۴ طبق جدول نقش |
مقادیر مجاز نوع شخص و نقش طرفحساب
| فیلد | مقدار | معنی |
|---|---|---|
| shakhskind | 1 | شخص حقوقی |
| shakhskind | 2 | شخص حقیقی انفرادی |
| shakhskind | 3 | شخص حقیقی ـ مشارکت مدنی |
| shakhskind | 4 | اتباع غیرایرانی |
| shakhskind | 5 | مصرفکننده نهایی |
| kindofwork | 1 | تأمینکننده |
| kindofwork | 2 | مشتری |
| kindofwork | 3 | کارمند |
| kindofwork | 4 | تنخواهدار |
قواعد کد ملی، شناسه ملی و کد اقتصادی
| نوع شخص | فیلد meli | فیلد eghtesadi | قاعده اعلامشده |
|---|---|---|---|
| حقوقی | شناسه ملی | شناسه ملی | متن قبلی API طول ۱۰ یا ۱۱ رقم را برای meli اعلام کرده است؛ پذیرش ۱۰ رقم باید توسط تیم فنی تأیید شود. |
| حقیقی انفرادی | کد ملی ۱۰ رقمی | کد اقتصادی ۱۴ رقمی | نام، کد ملی و کد اقتصادی الزامی اعلام شدهاند. |
| مشارکت مدنی | مقدار هویتی معتبر | کد اقتصادی ۱۲ رقمی | قالب دقیق meli برای این حالت باید با تیم فنی کنترل شود. |
| اتباع غیرایرانی | شماره فراگیر ۱۲ رقمی | شماره فراگیر | نام و اطلاعات هویتی الزامی اعلام شدهاند. |
| مصرفکننده نهایی | اختیاری | اختیاری | در متن قبلی فقط name الزامی اعلام شده است؛ استثنای کد پستی باید تأیید شود. |
دو ابهام لازم برای تأیید تیم فنی: آیا شناسه ملی ۱۰ رقمی برای شخص حقوقی واقعاً توسط Backend پذیرفته میشود؟ و آیا مصرفکننده نهایی از الزام codeposti مستثناست؟ تا زمان تأیید، این دو حالت را در تست اتصال جداگانه بررسی کنید.
برای بررسی اطلاعات ثبتی اشخاص حقوقی از خدمات رسمی سازمان ثبت اسناد و املاک کشور استفاده کنید و اطلاعات هویتی را از منابع غیررسمی دریافت نکنید.
الزامات خاص کارمند و تنخواهدار
- برای نقش کارمند (kindofwork = 3)، کد ملی در متن فعلی الزامی اعلام شده است.
- برای تنخواهدار (kindofwork = 4)، اختیاری بودن فیلدها مربوط به اطلاعات هویتی تکمیلی است؛ پارامترهای سیستمی و فیلدهای لازم برای تشخیص شخص همچنان باید ارسال شوند.
- مقدار shakhskind نوع هویتی و مقدار kindofwork نقش حسابداری شخص را تعیین میکند؛ این دو فیلد جایگزین یکدیگر نیستند.
نمونه JSON ثبت شخص حقوقی
مقادیر زیر صرفاً آموزشی هستند. شناسههای سیستمی، اطلاعات هویتی، شماره تماس و کد پستی را با داده معتبر محیط خود جایگزین کنید.
JSON Request Body
{ "mizekar": 10, "mizekaruser": 10, "userid": 88718, "fiscalyear": 5730, "name": "شرکت نمونه حسابداری", "address": "تهران، خیابان نمونه، پلاک ۱۲۳", "shakhskind": "1", "meli": "14001234567", "eghtesadi": "14001234567", "ostan": "تهران", "shahrestan": "تهران", "kindofwork": "2", "sabtnum": "45879", "shahr": "تهران", "codeposti": "1234567890", "tel": "02188776655", "mobile": "09121234567" } نمونه درخواست cURL cURL
curl --request POST --url "https://panel.kariyahesab.com/DefinitionEndpoint/customer" --header "Authorization: YOUR_API_TOKEN" --header "Accept: application/json" --header "Content-Type: application/json" --data '{ "mizekar": 10, "mizekaruser": 10, "userid": 88718, "fiscalyear": 5730, "name": "شرکت نمونه حسابداری", "address": "تهران، خیابان نمونه، پلاک ۱۲۳", "shakhskind": "1", "meli": "14001234567", "eghtesadi": "14001234567", "ostan": "تهران", "shahrestan": "تهران", "kindofwork": "2", "sabtnum": "45879", "shahr": "تهران", "codeposti": "1234567890", "tel": "02188776655", "mobile": "09121234567" }' نمونه درخواست HTTP Raw HTTP Request
POST /DefinitionEndpoint/customer 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": "شرکت نمونه حسابداری", "address": "تهران، خیابان نمونه، پلاک ۱۲۳", "shakhskind": "1", "meli": "14001234567", "eghtesadi": "14001234567", "ostan": "تهران", "shahrestan": "تهران", "kindofwork": "2", "sabtnum": "45879", "shahr": "تهران", "codeposti": "1234567890", "tel": "02188776655", "mobile": "09121234567" } پاسخ موفق و مدیریت خطاها در نسخه قبلی محتوا، پاسخ زیر بهعنوان نمونه ثبت موفق درج شده بود:
Illustrative Success Response
{ "success": true, "message": "شخص با موفقیت ثبت شد" } نیازمند تأیید: کد HTTP پاسخ موفق، فیلد شناسه شخص ایجادشده و قرارداد دقیق پاسخ خطا در اطلاعات فعلی مشخص نشدهاند. تا قبل از تأیید تیم فنی، ساختار بالا را قطعی فرض نکنید و صرفاً متن پیام را مبنای موفقیت تراکنش قرار ندهید.
خطاهای قابل پیشبینی
- نبودن یا نامعتبر بودن هدر Authorization
- IP تأییدنشده یا شناسههای سیستمی نامعتبر
- طول یا قالب اشتباه کد ملی، شناسه ملی، کد اقتصادی یا کد پستی
- مقدار خارج از محدوده برای shakhskind یا kindofwork
- ثبت دوباره شخصی که قبلاً با همان شناسه هویتی ایجاد شده است
رفتار ثبت تکراری، Rate Limit و پشتیبانی از Idempotency در متن فعلی اعلام نشده است. پیش از Retry خودکار، ابتدا نتیجه درخواست قبلی را بررسی کنید تا طرفحساب تکراری ساخته نشود.
ارتباط API شخص با سایر خدمات کاریا
- طرفحساب ایجادشده میتواند در عملیات نرمافزار حسابداری ابری کاریا حساب استفاده شود.
- اطلاعات صحیح مشتری برای صدور صورتحساب در نرمافزار سامانه مودیان کاریا حساب اهمیت دارد.
- اگر کسبوکار شما علاوه بر اتصال فنی به اجرای امور مالی نیاز دارد، صفحه خدمات شرکت حسابداری کاریا حساب را ببینید.
فعالسازی و تست API ایجاد شخص
پس از دریافت توکن و شناسههای اختصاصی، ابتدا یک شخص آزمایشی ثبت و نتیجه را داخل پنل کاریا کنترل کنید.
سؤالات متداول
آیا میتوان مشتری فروشگاه اینترنتی را خودکار در کاریا ثبت کرد؟
بله. Backend فروشگاه میتواند پس از ثبت یا تأیید مشتری، اطلاعات او را با درخواست POST به Endpoint تعریف شخص ارسال کند.
تفاوت shakhskind و kindofwork چیست؟
shakhskind نوع هویتی مانند حقیقی، حقوقی یا مصرفکننده نهایی را مشخص میکند؛ kindofwork نقش حسابداری مانند مشتری، تأمینکننده، کارمند یا تنخواهدار را تعیین میکند.
آیا Authorization باید با Bearer ارسال شود؟
در نمونه فعلی کاریا، هدر به شکل Authorization: YOUR_API_TOKEN معرفی شده و پیشوند Bearer ذکر نشده است. مقدار را مطابق اطلاعات دریافتی از تیم فنی ارسال کنید.
برای مصرفکننده نهایی چه اطلاعاتی لازم است؟
متن قبلی فقط نام را الزامی اعلام کرده است؛ اما همان متن کد پستی را نیز برای ثبت اشخاص الزامی میداند. استثنای مصرفکننده نهایی باید در تست API یا توسط تیم فنی تأیید شود.
آیا API فاکتور، مشتری را نیز خودکار ایجاد میکند؟
چنین رفتاری در مستندات فعلی اعلام نشده است. برای جریان قابلکنترل، ابتدا شخص را ایجاد و سپس شناسه یا اطلاعات تأییدشده او را در فرایند فاکتور استفاده کنید.
آیا میتوان درخواست ناموفق را خودکار تکرار کرد؟
فقط پس از مشخص شدن رفتار ثبت تکراری و Idempotency. در غیر این صورت Retry ممکن است شخص تکراری بسازد.
آیا امکان اتصال فروشگاه اینترنتی به کاریا حساب وجود دارد؟
بله، با استفاده از API تعریف شخص و سایر وب سرویسهای کاریا حساب میتوان فروشگاه اینترنتی را به سیستم حسابداری متصل کرد.
آیا API کاریا حساب از JSON پشتیبانی میکند؟
بله، تمامی درخواستها باید با فرمت application/json ارسال شوند.
آیا استفاده از Authorization الزامی است؟
بله، تمامی درخواستهای API باید دارای هدر Authorization باشند.
نظرات
هنوز نظری ثبت نشده است. اولین نفر باشید.
اظهارنامه و سامانه مودیان را به دفتری بسپارید که خودش مرتب میماند.
کاریا حساب صورتحساب را از دل همان سندی میسازد که ثبت کردهاید و خودش میفرستد. راهاندازی صفر تا صد رایگان است.