آیا امکان اتصال فروشگاه اینترنتی به کاریا حساب وجود دارد؟

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

آیا API کاریا حساب از JSON پشتیبانی میکند؟

بله، تمامی درخواستها باید با فرمت application/json ارسال شوند.

آیا استفاده از Authorization الزامی است؟

بله، تمامی درخواستهای API باید دارای هدر Authorization باشند.

مستندات API ایجاد شخص در کاریا حساب

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

Method POST

Content-Type application/json

Authentication Authorization: YOUR_API_TOKEN

Endpoint 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 ممکن است شخص تکراری بسازد.