Sayfalama

Tüm liste (Query) endpoint'leri zorunlu sayfalama ile çalışır. Default değer yoktur — eksik veya geçersiz parametre 400 Bad Request döner.

Query parametreleri

Parametre	Tip	Sınır
`page`	int	`>= 1`
`pageSize`	int	`10` – `100`
`orderBy`	string	Endpoint başına farklı whitelist
`order`	enum	`Asc` veya `Desc`

Pagination metadata

Yanıtın header'larında taşınır, body yalnızca List<T> döner:

Header	Açıklama
`X-Total-Count`	Tüm sayfalardaki toplam kayıt
`X-Page`	Mevcut sayfa numarası
`X-Page-Size`	Sayfa büyüklüğü
`X-Next-Page`	Sonraki sayfa numarası (varsa)
`X-Prev-Page`	Önceki sayfa numarası (varsa)

Örnek istek/yanıt

İstek

GET /v1/orders?page=1&pageSize=20&orderBy=CreatedAt&order=Desc

200 OK · Response headers

X-Total-Count: 142
X-Page: 1
X-Page-Size: 20
X-Next-Page: 2
Content-Type: application/json

200 OK · Body

[
  { "id": "01H8M...", "orderNumber": "EP-2026-00142", ... },
  { "id": "01H8L...", "orderNumber": "EP-2026-00141", ... }
]

OrderBy whitelist'i

Performans için orderBy her endpoint için sınırlı bir alan kümesini kabul eder (indexli kolonlar). Endpoint sayfasına gidip izinli alanları kontrol edin.

Endpoint	İzinli orderBy
`/v1/orders`	`CreatedAt`
`/v1/offers`	`CreatedAt`, `UpdatedAt`, `Price`, `Quantity`
`/v1/offers/{id}/digital-items`	`CreatedAt`, `ExpiresAt`, `Status`, `ValueType`
`/v1/claims`	`CreatedAt`, `UpdatedAt`
`/v1/product-questions`	`CreatedAt`, `Id`
`/v1/order-invoices`	`CreatedAt`, `UploadedAt`, `InvoiceDate`, `InvoiceNumber`, `Status`
`/v1/settlements`	`CreatedAt`, `PeriodStart`, `PeriodEnd`, `NetAmount`
`/v1/settlements/{id}/items`	`CreatedAt`, `Type`, `GrossAmount`, `CommissionAmount`, `NetAmount`
`/v1/finance-transactions`	`CreatedAt`, `Amount`
`/v1/catalog-categories`	`CreatedAt`, `Id`
`/v1/catalog-variants`	`CreatedAt`, `Sku`, `VariantName`, `IsActive`

Whitelist dışı değer:

400 Bad Request

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "orderBy": ["OrderBy must be one of: CreatedAt."]
  }
}

errors altındaki mesaj o uç noktanın kabul ettiği alanları saydığı için, listeyi ezberlemek yerine hatayı okumak yeterlidir.

Sayfa dolaşma örneği

Polling için sıralama

İncremental sync (yeni kayıtları periyodik olarak çekmek) için orderBy=UpdatedAt&order=Asc kullanın ve updatedAtFrom filtresiyle birleştirin. Detay için Polling Deseni sayfasına bakın.

HEAD endpoint'i (sayım)

Bazı endpoint'ler HEAD metoduyla sadece toplam sayıyı döndürür:

İstek

HEAD /v1/order-invoices?status=Pending

200 OK · Yanıt

X-Total-Count: 7
(Content-Length: 0)

Bu, "bekleyen fatura sayısı" gibi sayaç bilgisi için body indirimsiz hızlı bir yoldur.