مستندات وب‌سرویس (API) فاکتور فروش

به مستندات وب‌سرویس بخش فروش نرم‌افزار کاریا حساب خوش آمدید.

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

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

پیش‌نیاز اتصال به API

قبل از استفاده از وب‌سرویس، لازم است کاربر دسترسی رسمی API دریافت کند.

برای این منظور باید یک درخواست رسمی (نامه) به تیم پشتیبانی کاریا ارسال شود.

در این درخواست باید موارد زیر اعلام گردد:

• آدرس IP یا URL سرور (Webhook) که درخواست‌ها از آن ارسال می‌شوند
• درخواست فعال‌سازی دسترسی API

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

اطلاعاتی که توسط کاریا ارائه می‌شود:

• mizekar : شناسه میزکار
• mizekaruser : شناسه کاربر میزکار
• userid : شناسه کاربر
• fiscalyear : شناسه سال مالی فعال
• Authorization : کلید احراز هویت API

این اطلاعات برای تمامی درخواست‌های API الزامی هستند.

احراز هویت (Authentication)

تمامی درخواست‌ها باید شامل Header احراز هویت باشند.

Header

Authorization: YOUR_API_TOKEN

مقدار Authorization توسط تیم کاریا پس از تایید درخواست در اختیار شما قرار می‌گیرد.

در صورت عدم ارسال این هدر، درخواست توسط سرور رد خواهد شد.

اطلاعات پایه وب‌سرویس

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

Method

POST

Endpoint

Content-Type

application/json

ساختار بدنه درخواست (JSON)

بدنه درخواست شامل چهار بخش اصلی است.

۱. شناسه‌های سیستمی (الزامی)

این مقادیر از طرف شرکت کاریا ارائه می‌شوند.

mizekar
mizekaruser
userid
fiscalyear
factor_kind
kindfactor

توضیحات:

factor_kind

نوع فاکتور

مقادیر مجاز:

• 1 → فاکتور نوع اول (دارای اطلاعات خریدار)
• 2 → فاکتور مصرف‌کننده نهایی

kindfactor

همواره مقدار ثابت 1

۲. اطلاعات فاکتور

factornum
factordate
meli
desfac

توضیحات:

factornum

شماره فاکتور (اختیاری)

در صورت ارسال باید دقیقا 10 رقمی باشد.

مثال:

23 → 0000000023

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

factordate

تاریخ فاکتور با فرمت شمسی

1403/08/15

meli

کد ملی یا شناسه ملی خریدار

desfac

توضیحات فاکتور (اختیاری)

۳. اقلام فاکتور (کالا و خدمات)

در هر درخواست حداکثر 10 ردیف کالا قابل ارسال است.

ساختار هر ردیف:

kalacodeX
meghdarX
priceX
takhfifX

به جای X عدد ردیف قرار می‌گیرد.

مثال:

kalacode1
meghdar1
price1
takhfif1

توضیحات:

kalacodeX

کد کالا

meghdarX

تعداد یا مقدار کالا

priceX

مبلغ واحد کالا

takhfifX

مبلغ تخفیف

۴. اطلاعات تسویه

tasvie
naghdi
nesie

مقادیر مجاز:

tasvie

1 → تسویه نقدی

2 → تسویه نسیه

3 → ترکیبی (نقدی و نسیه)

اگر مقدار 3 ارسال شود باید دو فیلد زیر نیز ارسال شوند:

naghdi
nesie

جمع این دو مقدار باید برابر با مبلغ خالص فاکتور باشد.

نمونه درخواست ثبت فاکتور

{
  "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": "1403/08/15",
  "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
}

قوانین مهم در پیاده‌سازی

محدودیت تعداد کالا

در هر درخواست حداکثر 10 ردیف کالا قابل ارسال است.

در صورتی که فاکتور بیش از 10 ردیف داشته باشد باید از طریق پنل کاریا ثبت شود.

قانون شماره فاکتور

شماره فاکتور باید دقیقا 10 رقمی باشد.

در کدهای خود از تابعی مشابه PadLeft استفاده کنید.

مثال:

23 → 0000000023

ارسال به سامانه مودیان

ثبت فاکتور از طریق API تنها باعث ثبت فاکتور در نرم‌افزار کاریا می‌شود.

به دلیل حساسیت‌های قانونی:

ارسال به سامانه مودیان مالیاتی به صورت خودکار انجام نمی‌شود.

کاربر باید:

1. وارد پنل کاریا شود
2. فاکتور ثبت شده را بررسی کند
3. روی دکمه ارسال به سامانه مودیان کلیک کند

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

برای ابطال فاکتور ثبت شده از این Endpoint استفاده می‌شود.

Endpoint

POST

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

پارامترهای بدنه

mizekar
mizekaruser
userid
fiscalyear
factor_marja
factornum
factordate

توضیحات

factor_marja

شماره فاکتور مرجع که باید 10 رقمی باشد.

factornum

شماره فاکتور ابطالی (اختیاری)

در صورت خالی بودن، سیستم به صورت خودکار تولید می‌کند.

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

{
  "mizekar": "YOUR_MIZEKAR_ID",
  "mizekaruser": "YOUR_MIZEKAR_USER_ID",
  "userid": "YOUR_USER_ID",
  "fiscalyear": "YOUR_FISCAL_YEAR_ID",
  "factor_marja": "0000000001",
  "factornum": "",
  "factordate": "1403/08/16"
}

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

فاکتور اصلاحی برای زمانی است که بخواهید اقلام فاکتور را اصلاح کنید.

Endpoint

پارامترهای مخصوص فاکتور اصلاحی

factor_sub = 2

پارامترهای الزامی

۱. شناسه‌های سیستمی

mizekar
mizekaruser
userid
fiscalyear
factor_kind = 1
kindfactor = 1
factor_sub = 2

۲. اطلاعات پایه و ارجاع

factor_marja   شماره فاکتور اصلی (10 رقمی) — الزامی
factornum      اختیاری (10 رقمی)
factordate     تاریخ شمسی
meli           همان کدملی فاکتور مرجع (غیر قابل تغییر)
desfac         توضیحات

۳. اقلام کالا (اصلاح‌شده)

تمام کالاهای جدید یا اصلاح‌شده باید ارسال شوند.

حداکثر 10 ردیف.

kalacodeX
meghdarX
priceX
takhfifX

۴. اطلاعات تسویه

tasvie
naghdi
nesie

نمونه 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": "1403/08/18",

  "meli": "0123456789",
  "desfac": "اصلاح تعداد اقلام",

  "kalacode1": "1001",
  "meghdar1": 5,
  "price1": 150000,
  "takhfif1": 0,

  "tasvie": 1,
  "naghdi": 750000,
  "nesie": 0
}

محدودیت‌ها

• اطلاعات مشتری قابل تغییر نیست
• فقط کالا، تعداد و مبلغ قابل اصلاح است
• حداکثر 10 ردیف کالا

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

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

Endpoint

پارامترهای مخصوص فاکتور برگشتی

factor_sub = 4

پارامترهای الزامی

۱. شناسه‌های سیستمی

mizekar
mizekaruser
userid
fiscalyear
factor_kind = 1
kindfactor = 1
factor_sub = 4

۲. اطلاعات ارجاع

factor_marja   شماره فاکتور اصلی (10 رقمی) — الزامی
factornum      اختیاری
factordate     تاریخ شمسی
meli           باید مطابق مشتری فاکتور اصلی باشد
desfac         توضیحات

۳. اقلام کالا (بر اساس قوانین سامانه مودیان)

قانون بسیار مهم:

**تعداد برگشتی نباید ارسال شود!

بلکه تعداد باقی‌مانده نزد مشتری باید ارسال شود.**

مثال:

فروش اولیه: 8 عدد

مرجوعی: 3 عدد

مقدار ارسالی:

meghdar = 5

اگر کالایی اصلا مرجوع نشده باشد باید عینا تکرار شود.

قیمت (priceX) نباید تغییر کند.

۴. تسویه

tasvie
naghdi
nesie

نمونه 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": "1403/08/18",

  "meli": "0123456789",
  "desfac": "برگشت 3 عدد از کالای اول",

  "kalacode1": "1001",
  "meghdar1": 5,
  "price1": 150000,
  "takhfif1": 0,

  "kalacode2": "1002",
  "meghdar2": 2,
  "price2": 85000,
  "takhfif2": 0,

  "tasvie": 1,
  "naghdi": 920000,
  "nesie": 0
}

پیام لازم پس از ثبت موفق برگشتی

پس از ثبت فاکتور برگشتی در API، باید پیام زیر به کاربر نمایش داده شود:

فاکتور برگشت از فروش با موفقیت در نرم‌افزار کاریا ثبت شد.

برای ارسال به سامانه مودیان مالیاتی لازم است وارد پنل کاریا شوید و از لیست فاکتورها گزینه ارسال را انتخاب نمایید.

ارسال خودکار به دلیل محدودیت‌های قانونی امکان‌پذیر نیست.