به محتوای اصلی

کار با 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?search=کتابهای اشپزی

search روی فیلدهایی کار می‌کند که در مدل داده «قابل جست‌وجو» علامت خورده‌اند — تیکی روی خود فیلد، در صفحهٔ مدل داده. چند فیلد با هم OR می‌شوند.

برخلاف filter[field][like] که تطابق دقیق زیررشته است، search متن را پیش از مقایسه نرمال می‌کند: ی و ک عربی، ة و ۀ، همزهٔ الف، نیم‌فاصله و کاراکترهای نامرئی، اِعراب، و ارقام فارسی و عربی همه به یک شکل استاندارد می‌روند. یعنی «كتابها»، «کتاب‌ها» و «کتابها» یک نتیجه می‌دهند. تطابق نیم‌کلمه هم کار می‌کند: ?search=محصو رکوردهای «محصول» را برمی‌گرداند.

  • اگر روی موجودیت هیچ فیلد قابل جست‌وجویی که شما اجازهٔ خواندنش را داشته باشید نباشد، پاسخ 400 با کد no_searchable_fields است.
  • تا وقتی ایندکس یک فیلد تازه‌علامت‌خورده ساخته می‌شود، همان نتایج برمی‌گردند ولی کندتر؛ پاسخ در این حالت هدر X-Search-Degraded: true دارد.

جزئیات اینکه دقیقاً چه چیزهایی یکی می‌شوند و چرا این کار باید متقارن انجام شود، در جست‌وجوی فارسی در دیتابیس آمده است.

مرتب‌سازی

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 هستند؛ تبدیل به تقویم شمسی سمت نمایش انجام می‌شود.

بیشتر بخوانید