Api

صفحه‌بندی و فیلترها#

هر نقطه پایانی فهرست با قالب استاندارد صفحه‌بندی Laravel صفحه‌بندی می‌شود. نقاط پایانی جزئیات صفحه‌بندی نمی‌شوند؛ یک شیء منفرد data برمی‌گردانند.

چون مجموعه‌ها می‌توانند بزرگ باشند، یکپارچه‌سازی‌ها باید با تأمل صفحه‌بندی کنند و یک کلید خارجی باثبات ذخیره نمایند به‌جای وابستگی به موقعیت رشته.

پارامترها#

پارامتر	نوع	پیش‌فرض	حداکثر	اعمال می‌شود بر
`page`	integer	1	—	همه فهرست‌ها
`per_page`	integer	25	100	همه فهرست‌ها

مقدارهای بیرون از محدوده پذیرفته‌شده یک پاسخ تأیید 422 تولید می‌کنند. مقدارهای کسری یا غیرعددی به‌جای گِرد شدن، رد می‌شوند.

قالب پاسخ#

json

{
  "data": [],
  "links": {
    "first": "https://app.example.com/api/v2/sales?page=1",
    "last": "https://app.example.com/api/v2/sales?page=4",
    "prev": null,
    "next": "https://app.example.com/api/v2/sales?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 4,
    "per_page": 25,
    "path": "https://app.example.com/api/v2/sales",
    "to": 25,
    "total": 87
  }
}

فیلد meta	معنا
`current_page`	صفحه‌ای که در این پاسخ برگردانده شده
`last_page`	بالاترین صفحه موجود برای همان فیلترها
`per_page`	اندازه صفحه اعمال‌شده
`from`, `to`	محدوده رشته‌ها در این صفحه؛ `null` وقتی صفحه خالی است
`total`	مجموع رشته‌های مطابق با فیلترها
`path`	URL پایه، بدون پارامترهای کوئری

links.prev و links.next در مرزها null هستند. تا null نشدن next را دنبال کنید؛ شماره صفحه را کورکورانه افزایش ندهید، چون مجموعه فیلترها ممکن است زیر پای شما تغییر کند.

پیوندهای صفحه‌بندی فیلترهای شما را نگه می‌دارند. یک درخواست با from=2026-10-01&status=pending پیوندهایی تولید می‌کند که هنوز همان پارامترها را دربر دارند، که یک حلقه «دنبال‌کردن پیوند بعدی» را امن می‌سازد.

ترتیب#

منبع	ترتیب
Products	`id` صعودی
Stock	`id` موجودی صعودی
Purchases	جدیدترین اول
Sales	جدیدترین اول
Orders	`created_at` نزولی

ترتیب برای یک مجموعه داده ثابت باثبات است. اگر رکوردها در حال صفحه‌بندی شما درج شوند، برای همگام‌سازی تدریجی به‌جای شماره صفحه از یک فیلتر تاریخ یا واترمارک «created after» استفاده کنید.

الگوی همگام‌سازی تدریجی#

صفحه اول را با from تنظیم‌شده بر آخرین واترمارک موفق خود بخوانید.
رشته‌ها را پردازش کنید و id منبع و created_at را ذخیره نمایید.
واترمارک را به تازه‌ترین created_at که پردازش کردید منتقل کنید.
پس از صفحه اول متوقف شوید اگر تازه‌ترین رشته از قبل شناخته شده است.

این کار از تکرارها جلوگیری می‌کند و تعداد درخواست‌ها را پایین نگه می‌دارد.

خلاصه فیلترها#

نقطه پایانی	فیلترهای موجود
`/api/v2/products`	`search`، `language_code`
`/api/v2/stock`	`language_code` (شعبه از طریق هدر)
`/api/v2/purchases`	`from`، `to`، `language_code`، `id`
`/api/v2/orders`	`from`، `to`، `status`
`/api/v2/sales`	`from`، `to`، `language_code`، `id`

فیلترهای تاریخ#

قالب: YYYY-MM-DD.
هر دو مرز شامل هستند.
to باید برابر یا بعد از from باشد.
حذف هر دو مرز کل تاریخچه را با ترتیب جدیدترین اول برمی‌گرداند.
تاریخ‌ها در منطقه زمانی برنامه تفسیر می‌شوند؛ زمان‌برچسب‌ها در پاسخ‌ها مقدارهای ذخیره‌شده‌اند، بنابراین آن‌ها را همسان مقایسه کنید.

انتخاب اندازه صفحه#

هدف	`per_page` پیشنهادی
جستجوی تعاملی	10–25
همگام‌سازی شبانه	100
اکسپورت مغایرت‌گیری	100 با پنجره‌های تاریخی

صفحه‌های بزرگ‌تر سهمیه کمتری به ازای هر رکورد مصرف می‌کنند، چون سهمیه به ازای درخواست شمرده می‌شود نه به ازای رشته.