کار با 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 هستند؛ تبدیل به تقویم شمسی سمت نمایش انجام میشود.
بیشتر بخوانید
- اتصال فرانتاند به API — لایهی ارتباط را با fetch خام بنویسیم، axios یا کلاینت اختصاصی؟