مستندات API فاکتور فروش کاریا حساب

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

ویدئوی معرفی وب‌سرویس فاکتور فروش کاریا حساب

Method POST

Content-Type application/json

ثبت، اصلاح و برگشت /DefinitionEndpoint/forosh

ابطال /DefinitionEndpoint/foroshebtali

API فاکتور فروش چه کاری انجام می‌دهد؟

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

فاکتور اصلی

ثبت فروش جدید با Endpoint اصلی forosh

فاکتور ابطالی

ابطال فاکتور مرجع با Endpoint اختصاصی foroshebtali

فاکتور اصلاحی

ارسال به forosh همراه با factor_sub = 2

برگشت از فروش

ارسال به forosh همراه با factor_sub = 4

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

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

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

امنیت: توکن API و اطلاعات فروش را در JavaScript مرورگر، URL یا مخزن عمومی کد قرار ندهید. درخواست‌ها را از Backend و روی HTTPS ارسال کنید و مقدار Authorization را از لاگ‌ها حذف یا ماسک نمایید.

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

Request Headers

Authorization: YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json

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

Endpointهای وب‌سرویس فروش

عملیات	Method	Endpoint	پارامتر تشخیص
ثبت فاکتور اصلی	`POST`	`https://panel.kariyahesab.com/DefinitionEndpoint/forosh`	بدون `factor_sub` در نمونه فعلی
ثبت فاکتور اصلاحی	`POST`	`https://panel.kariyahesab.com/DefinitionEndpoint/forosh`	`factor_sub = 2`
ثبت برگشت از فروش	`POST`	`https://panel.kariyahesab.com/DefinitionEndpoint/forosh`	`factor_sub = 4`
ابطال فاکتور	`POST`	`https://panel.kariyahesab.com/DefinitionEndpoint/foroshebtali`	Endpoint اختصاصی ابطال

پارامترهای فاکتور فروش

فیلد	توضیح	وضعیت	قالب یا مقادیر
`mizekar`	شناسه میزکار	الزامی	دریافتی از کاریا
`mizekaruser`	شناسه کاربر میزکار	الزامی	دریافتی از کاریا
`userid`	شناسه کاربر ثبت‌کننده	الزامی	دریافتی از کاریا
`fiscalyear`	شناسه سال مالی فعال	الزامی	دریافتی از کاریا
`factor_kind`	نوع اطلاعات خریدار	الزامی	`1` نوع اول؛ `2` مصرف‌کننده نهایی
`kindfactor`	نوع عملیات فروش در قرارداد فعلی	الزامی	مقدار ثابت `1`
`factornum`	شماره فاکتور کاریا	اختیاری	در صورت ارسال دقیقاً ۱۰ رقم؛ در غیر این صورت تولید خودکار
`factordate`	تاریخ فاکتور	الزامی	تاریخ شمسی مانند `1405/05/01`
`meli`	کد ملی یا شناسه ملی خریدار	مشروط	برای فاکتور نوع اول متناسب با شخص تعریف‌شده
`desfac`	توضیحات فاکتور	اختیاری	رشته متنی
`kalacodeX`	کد کالای ردیف X	الزامی	کالای از قبل تعریف‌شده در کاریا
`meghdarX`	تعداد یا مقدار ردیف X	الزامی	مقدار عددی
`priceX`	مبلغ واحد ردیف X	الزامی	عدد؛ واحد پول باید با تیم فنی تأیید شود
`takhfifX`	مبلغ تخفیف ردیف X	الزامی	عدد؛ در نبود تخفیف `0`
`tasvie`	نوع تسویه	الزامی	`1` نقدی، `2` نسیه، `3` ترکیبی
`naghdi`	مبلغ نقدی	مشروط	در تسویه ترکیبی همراه `nesie` ارسال شود
`nesie`	مبلغ نسیه	مشروط	در تسویه ترکیبی همراه `naghdi` ارسال شود

برای ردیف‌های فاکتور، به‌جای X شماره ردیف از ۱ تا ۱۰ قرار می‌گیرد؛ مانند kalacode1 و kalacode2. در قرارداد فعلی، هر درخواست حداکثر ۱۰ ردیف را می‌پذیرد.

قواعد شماره فاکتور و تسویه

اگر factornum ارسال شود، باید با صفر از چپ به ۱۰ رقم برسد؛ برای نمونه 23 به 0000000023 تبدیل می‌شود.
در صورت خالی بودن شماره فاکتور، سیستم طبق متن فعلی آن را تولید می‌کند.
برای tasvie = 3، جمع naghdi و nesie باید با مبلغ خالص مورد انتظار Backend برابر باشد.
تعریف «مبلغ خالص» و اینکه مالیات و عوارض در این کنترل منظور می‌شود یا خیر، باید پیش از پیاده‌سازی با تیم فنی تأیید شود.

نمونه JSON ثبت فاکتور اصلی

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

Create Sales Invoice — JSON

{
  "mizekar": "YOUR_MIZEKAR_ID",
  "mizekaruser": "YOUR_MIZEKAR_USER_ID",
  "userid": "YOUR_USER_ID",
  "fiscalyear": "YOUR_FISCAL_YEAR_ID",
  "factor_kind": 1,
  "kindfactor": 1,
  "factornum": "0000000337",
  "factordate": "1405/05/01",
  "meli": "0123456789",
  "desfac": "ثبت از طریق وب‌سرویس فروشگاه",
  "kalacode1": "1001",
  "meghdar1": 2,
  "price1": 150000,
  "takhfif1": 0,
  "kalacode2": "1005",
  "meghdar2": 1,
  "price2": 300000,
  "takhfif2": 10000,
  "tasvie": 1,
  "naghdi": 590000,
  "nesie": 0
}

نمونه درخواست cURL

cURL

curl --request POST 
  --url "https://panel.kariyahesab.com/DefinitionEndpoint/forosh" 
  --header "Authorization: YOUR_API_TOKEN" 
  --header "Accept: application/json" 
  --header "Content-Type: application/json" 
  --data '{
    "mizekar": "YOUR_MIZEKAR_ID",
    "mizekaruser": "YOUR_MIZEKAR_USER_ID",
    "userid": "YOUR_USER_ID",
    "fiscalyear": "YOUR_FISCAL_YEAR_ID",
    "factor_kind": 1,
    "kindfactor": 1,
    "factornum": "0000000337",
    "factordate": "1405/05/01",
    "meli": "0123456789",
    "desfac": "ثبت از طریق وب‌سرویس فروشگاه",
    "kalacode1": "1001",
    "meghdar1": 2,
    "price1": 150000,
    "takhfif1": 0,
    "kalacode2": "1005",
    "meghdar2": 1,
    "price2": 300000,
    "takhfif2": 10000,
    "tasvie": 1,
    "naghdi": 590000,
    "nesie": 0
  }'

ثبت فاکتور ابطالی

برای ابطال فاکتور ثبت‌شده از Endpoint اختصاصی زیر استفاده می‌شود:

Cancellation Endpoint

POST https://panel.kariyahesab.com/DefinitionEndpoint/foroshebtali

تفاوت شماره‌ها: در متن فعلی، factor_marja شماره ۱۰ رقمی فاکتور مرجع در کاریا معرفی شده است. آن را بدون تأیید تیم فنی با شماره منحصر‌به‌فرد مالیاتی صورتحساب در سامانه مودیان جایگزین نکنید.

Cancel Sales Invoice — JSON

{
  "mizekar": "YOUR_MIZEKAR_ID",
  "mizekaruser": "YOUR_MIZEKAR_USER_ID",
  "userid": "YOUR_USER_ID",
  "fiscalyear": "YOUR_FISCAL_YEAR_ID",
  "factor_marja": "0000000001",
  "factornum": "",
  "factordate": "1405/05/02"
}

factornum فاکتور ابطالی اختیاری است و طبق مستند فعلی در صورت خالی بودن توسط سیستم تولید می‌شود.

ثبت فاکتور اصلاحی

فاکتور اصلاحی به Endpoint اصلی فروش ارسال می‌شود و مقدار factor_sub آن باید 2 باشد.

factor_marja شماره ۱۰ رقمی فاکتور اصلی است.
meli باید با خریدار فاکتور مرجع یکسان باشد.
طبق قرارداد فعلی، اطلاعات مشتری قابل تغییر نیست.
تمام اقلامی که باید در نسخه اصلاح‌شده باقی بمانند ارسال شوند، نه فقط ردیفی که تغییر کرده است.
حداکثر ۱۰ ردیف کالا یا خدمت قابل ارسال است.

Corrective Sales Invoice — JSON

{
  "mizekar": "YOUR_MIZEKAR_ID",
  "mizekaruser": "YOUR_MIZEKAR_USER_ID",
  "userid": "YOUR_USER_ID",
  "fiscalyear": "YOUR_FISCAL_YEAR_ID",
  "factor_kind": 1,
  "kindfactor": 1,
  "factor_sub": 2,
  "factor_marja": "0000000015",
  "factornum": "",
  "factordate": "1405/05/03",
  "meli": "0123456789",
  "desfac": "اصلاح تعداد اقلام",
  "kalacode1": "1001",
  "meghdar1": 5,
  "price1": 150000,
  "takhfif1": 0,
  "tasvie": 1,
  "naghdi": 750000,
  "nesie": 0
}

ثبت فاکتور برگشت از فروش

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

قاعده اختصاصی قرارداد فعلی: در نمونه کاریا، برای ردیف مرجوع‌شده «تعداد باقی‌مانده نزد مشتری» ارسال می‌شود، نه تعداد مرجوعی. برای مثال اگر فروش اولیه ۸ و مرجوعی ۳ باشد، مقدار ارسالی 5 است. ردیف‌های مرجوع‌نشده نیز عیناً تکرار می‌شوند و قیمت تغییر نمی‌کند. این رفتار را پیش از استفاده عملیاتی با تیم فنی و یک تست کنترل‌شده تأیید کنید.

Sales Return — JSON

{
  "mizekar": "YOUR_MIZEKAR_ID",
  "mizekaruser": "YOUR_MIZEKAR_USER_ID",
  "userid": "YOUR_USER_ID",
  "fiscalyear": "YOUR_FISCAL_YEAR_ID",
  "factor_kind": 1,
  "kindfactor": 1,
  "factor_sub": 4,
  "factor_marja": "0000000012",
  "factornum": "",
  "factordate": "1405/05/04",
  "meli": "0123456789",
  "desfac": "برگشت ۳ عدد از کالای اول",
  "kalacode1": "1001",
  "meghdar1": 5,
  "price1": 150000,
  "takhfif1": 0,
  "kalacode2": "1002",
  "meghdar2": 2,
  "price2": 85000,
  "takhfif2": 0,
  "tasvie": 1,
  "naghdi": 920000,
  "nesie": 0
}

ثبت در کاریا و ارسال به سامانه مودیان

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

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

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

پاسخ API، خطاها و ثبت تکراری

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

موارد ضروری برای تکمیل مستند فنی:

کد HTTP و بدنه پاسخ ثبت موفق برای هر چهار عملیات
شناسه یا شماره فاکتور ایجادشده در پاسخ
خطای توکن، IP، مشتری، کالا، سال مالی و مبلغ تسویه نامعتبر
رفتار درخواست تکراری با یک factornum
Rate Limit، Timeout پیشنهادی و سیاست Retry
وجود یا نبود Idempotency Key
واحد پول priceX، takhfifX، naghdi و nesie

در زمان Timeout، قبل از تکرار درخواست، وجود فاکتور با همان شماره را بررسی کنید. Retry بدون کنترل می‌تواند فاکتور تکراری بسازد.

چک‌لیست پیش از اتصال عملیاتی

توکن و IP محیط Production فعال و از محیط آزمایش جدا شده باشد.
کد مشتری و همه کدهای کالا در میزکار مقصد وجود داشته باشند.
واحد پول مبالغ با تیم فنی تأیید شده باشد.
تاریخ شمسی و شماره ۱۰ رقمی فاکتور درست تولید شوند.
مجموع تسویه با مبلغ مورد انتظار Backend برابر باشد.
سناریوهای اصلاح، ابطال و برگشت جداگانه تست شده باشند.
پاسخ و خطا در سیستم مبدا ثبت شود، بدون ذخیره توکن و اطلاعات حساس در لاگ.
کاربر بداند ثبت در کاریا با ارسال نهایی به سامانه مودیان یک مرحله نیست.

ارتباط API فروش با خدمات کاریا حساب

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

سؤالات متداول API فاکتور فروش

آیا این API فاکتور را مستقیم به سامانه مودیان ارسال می‌کند؟

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

حداکثر چند ردیف کالا قابل ارسال است؟

طبق قرارداد فعلی هر درخواست حداکثر ۱۰ ردیف با الگوی kalacode1 تا kalacode10 می‌پذیرد.

شماره فاکتور چند رقم است؟

در صورت ارسال باید دقیقاً ۱۰ رقم باشد. برای شماره‌های کوتاه‌تر باید از سمت چپ صفر اضافه شود؛ در صورت خالی بودن، سیستم طبق مستند فعلی شماره تولید می‌کند.

تفاوت factor_kind و factor_sub چیست؟

factor_kind نوع صورتحساب از نظر اطلاعات خریدار را مشخص می‌کند؛ factor_sub عملیات ارجاعی را تعیین می‌کند که در این مستند مقدار ۲ برای اصلاح و ۴ برای برگشت از فروش است.

برای اصلاح فاکتور فقط ردیف تغییرکرده را بفرستیم؟

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

در برگشت از فروش، تعداد مرجوعی ارسال می‌شود؟

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