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

کار با 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/order?filter[createdAt]=2026-10-10
GET /v1/order?filter[createdAt][gte]=2026-10-01
GET /v1/booking?filter[date][lt]=2026-10-10T14:30:00Z
  • createdAt و updatedAt هر رکورد قابل فیلترند، با عملگرهای eq، ne، gt، gte، lt و lte. مقدارشان باید تاریخ باشد؛ وگرنه پاسخ 400 با کد invalid_filter_value است.
  • روی فیلدهای تاریخ، وقتی مقدار فیلتر شکل تاریخ دارد، مقایسه مقایسهٔ تاریخ است، نه متن: یک لحظه با هر منطقهٔ زمانی که نوشته شود (Z یا +03:30) همان نتیجه را می‌دهد. تاریخ یا ساعتی که منطقهٔ زمانی ندارد به وقت تهران خوانده می‌شود. (در آدرس، + را %2B بنویسید؛ وگرنه فاصله خوانده می‌شود.)
  • تاریخ تنها (مثل 2026-10-10) با eq یعنی کل آن روز به وقت تهران، از ساعت ۰۰:۰۰ تا پیش از ۰۰:۰۰ روز بعد — نه فقط لحظهٔ نیمه‌شب. با ne یعنی همه‌چیز بیرون از آن روز.
  • ne ردیف‌هایی را که در آن فیلد متن خالی یا تاریخ نامعتبر ذخیره کرده‌اند نگه می‌دارد. بقیهٔ عملگرها چنین ردیفی را برنمی‌گردانند. ردیفی که آن فیلد را اصلاً ندارد، با هیچ عملگری، از جمله ne، برنمی‌گردد.

تغییر رفتار — مهر ۱۴۰۵. پیش از این، فیلتر روی فیلدهای تاریخ مقایسهٔ متنی بود. حالا مقایسهٔ تاریخ است و تاریخ تنها با eq کل روز را می‌گیرد. اگر فیلتر تاریخی را با تاریخ تنها نوشته‌اید (مثلاً filter[date]=2026-10-10 یا filter[date][lte]=2026-10-10)، ممکن است نتیجه‌اش با قبل فرق کند؛ یک بار دوباره امتحانش کنید.

جست‌وجو

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 خراب، فیلد یا عملگر ناشناخته)
  • ۴۰۱ — کلید یا توکن نامعتبر یا غایب
  • ۴۰۴ — رکورد یافت نشد
  • ۴۲۲ — رد شده توسط قانون اعتبارسنجی
  • ۴۲۹ — عبور از سقف نرخ پلن پروژه

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

دادهٔ فارسی

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

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