نسخه فعلی سند: ۲۹ تیر ۱۴۰۴

راهنمای وب‌سرویس فیلیت‌زی

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

احراز هویت

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

Authorization: Bearer {API_KEY}

در صورت نیاز به دریافت یا تغییر API Key، با پشتیبانی سیستم تماس بگیرید.

ثبت سفارش

POST https://api.flytzi.com/v0/orders/submit/

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

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

همچنین در صورتی که شماره فاکتور در ورودی داده نشده باشد همه ردیف‌هایی که دارای یک شماره مشتر یکسان هستند به عنوان یک فاکتور در نظر گرفته می‌شوند.

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

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

داده‌های ورودی (request body)

[
  {
    "customer_code": "کد مشتری",
    "sku_code": "کد محصول",
    "invoice_code": "شماره فاکتور",
    "payment_amount": 100000,
    "sales_amount": 10
  },
  ...
]

پارامتر‌های ورودی (body parameters)

کلید	نوع داده	وضعیت	توضیح
`customer_code`	string	الزامى	کد یکتای مشتری (کد مشتری در نرم‌افزار حساب حسابداری) که در سیستم ثبت شده است.
`sku_code`	string	الزامى	کد یکتای محصول (کد محصول در نرم‌افزار حسابداری) که در سیستم ثبت شده است.
`invoice_code`	string	اختیاری	شماره فاکتور
`payment_amount`	number	اختیاری	مبلغ پرداختی (در صورت ثبت پرداخت)
`sales_amount`	number	الزامى	تعداد یا مقدار ریزترین واحد فروش

پاسخ (response)

در صورت موفقیت‌آمیز بودن درخواست، پاسخ به صورت زیر خواهد بود. که در آن orders_id شناسه سفارش ثبت شده است.

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

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

{
  "orders_id": "uuid",
  "status": "Done"
}

پارامتر‌های پاسخ (response parameters)

کلید	نوع داده	توضیح
`orders_id`	string	شناسه سفارش ثبت شده (UUID)
`status`	string	وضعیت درخواست شامل "Done" برای موفقیت و "error" برای خطا
`error`	object	در صورت بروز خطا در داده‌های ورودی، شامل کد و پیام خطا

خطاها (errors)

در صورت بروز خطای http، پاسخ به صورت زیر خواهد بود:

کد خطا	توضیحات
`400`	درخواست نامعتبر است.
`401`	کلید API معتبر نیست یا ارسال نشده است.
`500`	خطای داخلی سرور رخ داده است.

در صورتی که خطایی در داده‌های ورودی وجود داشته باشد، پاسخ با کد 200 و به صورت زیر خواهد بود:

{
  "error": {
    "code": "ERROR_CODE",
    "error_type": "error_type",
    "message": "Error message"
  },
  "status": "error"
}

لیست خطاهای ممکن:

کد عددی خطا	نوع خطا	توضیحات
10	`warehouse_not_found`	هیچ انبار ثبت شده‌ای یافت نشد.
6	`customer_code_missing`	ستون کد مشتری یافت نشد.
2	`sku_code_missing`	ستون کد محصول یافت نشد.
1	`sales_missing`	ستون مقدار فروش یافت نشد.
3	`sku_code_unregistered`	کد محصول ثبت نشده است.
7	`customer_code_unregistered`	کد مشتری ثبت نشده است.
5	`products_not_found`	یک یا چند محصول ناموجود است.
4	`sales_invalid`	مقدار فروش وارد شده نادرست است.
8	`payment_invalid`	مبلغ تسویه حساب نادرست است.
9	`file_processing_error`	خطایی در فرایند پردازش فایل رخ داده است.

دریافت وضعیت ثبت سفارش

GET https://api.flytzi.com/v0/orders/status/{orders_id}/

برای دریافت وضعیت سفارش ثبت شده، شما باید شناسه سفارش خروجی در پاسخ ثبت سفارش را در مسیر درخواست قرار دهید.

پارامترهای لینک (path parameters)

پارامتر	نوع داده	وضعیت	توضیح
`orders_id`	UUID	الزامی	شناسه سفارش دریافتی از پاسخ وب‌سرویس ثبت سفارش

پاسخ (response)

در صورت موفقیت‌آمیز بودن درخواست، پاسخ به صورت زیر خواهد بود.

{
  "message": "سفارش با موفقیت ثبت شد.",
  "status": "Done"
}

{
  "message": "در حال پردازش اطلاعات",
  "status": "In Progress"
}

پارامترهای پاسخ (response parameters)

کلید	نوع داده	توضیح
`message`	string	پیام موفقیت یا وضعیت درخواست
`status`	string	وضعیت درخواست شامل "Done" و "In Progress" است.