Polling Deseni

Public API webhook desteklemez. Yeni siparişler, güncellenen teklifler, ödenen hakedişler gibi olayları sisteminize aktarmak için incremental polling kullanın.

Temel reçete

Her liste endpoint'i şu parametreleri kabul eder:

Parametre	Açıklama
`updatedAtFrom`	Bu zaman damgasından sonra güncellenen kayıtlar (ISO 8601 UTC)
`updatedAtTo`	Pencere kapatma (opsiyonel)
`orderBy=UpdatedAt&order=Asc`	Yeni güncellemeler son sayfada — cursor güvenli

Algoritma

Sisteminizde bir lastSyncedAt zaman damgası tutun (ilk başta epoch veya başlangıç tarihi)
Her N dakikada bir polling job'ı çalıştırın:
- GET /v1/orders?updatedAtFrom={lastSyncedAt}&orderBy=UpdatedAt&order=Asc&page=1&pageSize=100
X-Next-Page header'ı varken sonraki sayfaları çekin
Her kaydı işleyin (upsert vs.)
Tüm sayfa bittikten sonra: lastSyncedAt = max(updatedAt of returned records)

Neden Asc + UpdatedAt?

Asc sıralama → yeni güncellemeler her zaman son sayfada olur. Polling sırasında yeni kayıt gelse bile mevcut iterasyonu bozmaz.
UpdatedAt filtresi → kaynak tarafında index'lenmiştir, hızlıdır.

Tam çalışan örnek

Sıklık önerileri

Senaryo	Önerilen interval
Sipariş senkronizasyonu	5 dakika
Teklif/stok güncellemeleri	15 dakika
İade talepleri	15 dakika
Finans (settlement, transaction)	1 saat
Katalog (variant, kategori)	24 saat

Çok kısa interval = rate limit

1-2 dakikalık polling sıkça hız limitine takılır. Yeterli sıklık çoğu use-case için 5 dakikadır.

Edge case'ler

Saat senkronizasyonu

updatedAtFrom'a sunucu tarafının saatiyle uyumlu UTC değer gönderdiğinizden emin olun. Yerel saatiniz drift'liyse kayıt kaçırabilirsiniz. NTP kullanın.

Aynı kayıt birden fazla görüntülenebilir

Aynı saniyede birden fazla update olursa kayıt birden fazla iterasyonda gelebilir. Upsert mantığı kullanın (INSERT ... ON DUPLICATE KEY UPDATE veya merge).

İlk sync (backfill)

İlk yüklemede tüm geçmişi çekmek isterseniz updatedAtFrom'u uzak bir tarihe (örn. yıl başı) ayarlayın. Sayfa sayfa ilerleyin.

Crash/restart recovery

lastSyncedAt'ı her sayfa işlendikten sonra değil, tüm sayfa bittikten sonra kaydedin. Aksi takdirde crash sonrası kayıp olabilir. Kalıcı bir store (DB, dosya, Redis) kullanın.

At-least-once garanti

Bu desen at-least-once delivery sağlar. Idempotent işleyici yazın — aynı orderId iki kez gelse bile sonuç değişmesin.