کار با API

هر موجودیت، مجموعهٔ کامل اندپوینت‌های CRUD را می‌گیرد. آدرس پایه:

https://api.fikaro.ir/{slug}/v1

اندپوینت‌ها

GET     /v1/{entity}                 # list
POST    /v1/{entity}                 # create
GET     /v1/{entity}/{id}            # get
PATCH   /v1/{entity}/{id}            # update
DELETE  /v1/{entity}/{id}            # delete
GET     /v1/{entity}/{id}/{relation} # related list
POST    /v1/{entity}/{id}/{relation} # related create

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

استثنا: ساخت user از مسیر POST /v1/auth/signup انجام می‌شود، نه POST /v1/user — جزئیات در کلیدها و احراز هویت.

فیلتر

GET /v1/product?filter[status]=active
GET /v1/product?filter[price][gte]=50000

بدون عملگر، eq (برابری) فرض می‌شود. عملگرهای مجاز: eq، ne، gt، gte، lt، lte، like (جست‌وجوی متنی، بدون حساسیت به بزرگی حروف) و in (عضویت در فهرست). چند فیلتر با هم، AND می‌شوند.

مرتب‌سازی

GET /v1/product?sort=price
GET /v1/product?sort=-price

بدون علامت، صعودی است؛ با - نزولی می‌شود.

صفحه‌بندی (cursor)

فهرست‌ها صفحه‌بندی مبتنی بر cursor دارند — پایدار و سریع، حتی روی جدول‌های بزرگ:

GET /v1/order?limit=20
→ { "data": [...], "pagination": { "limit": 20, "nextCursor": "..." } }

برای صفحهٔ بعد، همان nextCursor را برگردانید:

GET /v1/order?limit=20&cursor={nextCursor}

وقتی nextCursor برابر null شد، به انتهای فهرست رسیده‌اید.

روابط (include)

GET /v1/order?include=order_item

رکوردهای مرتبط، داخل همان پاسخ برمی‌گردند — بدون درخواست دوم.

قالب خطاها

همهٔ خطاها قالب استاندارد Problem Details (RFC 7807) دارند:

{
  "type": "https://fikaro.ir/errors/total_must_be_positive",
  "title": "total_must_be_positive",
  "status": 422,
  "detail": "مبلغ سفارش باید بزرگ‌تر از صفر باشد",
  "code": "total_must_be_positive"
}

۴۰۰ — درخواست نامعتبر (JSON خراب، فیلد یا عملگر ناشناخته)
۴۰۱ — کلید یا توکن نامعتبر یا غایب
۴۰۴ — رکورد یافت نشد
۴۲۲ — رد شده توسط قانون اعتبارسنجی
۴۲۹ — عبور از سقف نرخ (مخصوصاً با کلید Playground)

در منطق برنامه همیشه به فیلد code تکیه کنید، نه متن detail — کد پایدار است، متن ممکن است بهتر شود.

دادهٔ فارسی

اعداد در بدنهٔ API همیشه لاتین‌اند؛ ارقام فارسی ورودی خودکار نرمال می‌شوند.
شماره موبایل در قالب E.164 (+98912...) ذخیره می‌شود.
تاریخ‌ها ISO 8601 و UTC هستند؛ تبدیل به تقویم شمسی سمت نمایش انجام می‌شود.