updated_since ile artımlı senkronizasyon

Sursa verilerinin bir kopyasını kendi sisteminizde tutmak için her seferinde her şeyi okumanız gerekmez. updated_at alanı olan nesnelerin listeleri updated_since parametresini kabul eder ve yalnızca o anda ya da o andan sonra değişen nesneleri döndürür.

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "updated_since=2026-10-23T00:00:00Z" \
  --data-urlencode "limit=200"

updated_since ile liste önce artan updated_at değerine, sonra id değerine göre sıralanır ve imleç bu sırayla devam eder. Böylece değişiklikleri gerçekleştikleri sırayla okursunuz ve bir sayfa sınırı onları hiçbir zaman birinin kaybolacağı şekilde bölmez.

updated_since parametresini şu listeler kabul eder:

Koleksiyonların, kullanıcıların ve duyuruların updated_at alanı yoktur; bu yüzden listeleri bu parametreyle filtrelenmez: bu listeler kısadır, onları her çalıştırmada bütün olarak okuyun. Zaman, Z ya da +02:00 gibi bir saat dilimi farkı içermelidir; GET /v1/cards listesinde olduğu gibi başka her değer reddedilir.

updated_since ile klasör ağacı artık bir ağaç değildir: her koleksiyonun folders alanı değişen klasörleri boş children ile düz bir liste olarak içerir; her klasörün nerede durduğunu parent_id gösterir. Bu durumda GET /v1/folders, değişen klasörü olmayan koleksiyonları yanıta almaz.

Bir senkronizasyon döngüsü

1. İlk çalıştırmada listenin tamamını updated_since olmadan okuyun ve çalıştırmanın başladığı anı kaydedin.
2. Sonraki her çalıştırmada kaydettiğiniz anı, bir dakika gibi küçük bir pay düşülerek updated_since olarak gönderin ve yeni başlangıç zamanını kaydedin.
3. Her nesneyi id değerine göre deponuza yazın ve önceki kopyanın yerine koyun. Pay nedeniyle iki kez görünen nesneler yalnızca yeniden yazılır.
4. Sonraki her sayfayı imleçle ve aynı updated_since değeriyle isteyin. İmleç yalnızca ilk sayfanın filtreleriyle çalışır: filtreler olmadan istek api.cursor_invalid koduyla 400 döndürür.

Çalıştırmanın bittiği zamanı değil başladığı zamanı kullanmak, çalıştırma sürerken yapılan bir değişikliğin bir sonraki çalıştırmada yakalanmasını sağlar.

GET /v1/cards bir JSON dizisi döndürür, bu yüzden sonraki sayfası X-Next-Cursor başlığında gelir (Dizi döndüren listeler bölümüne bakın):

const BASE = "https://api.sursa.com";
const headers = { Authorization: `Bearer ${process.env.SURSA_API_KEY}` };

async function syncCards(since, saveCard) {
  const startedAt = new Date();
  const params = new URLSearchParams({ limit: "200" });
  if (since) params.set("updated_since", new Date(since.getTime() - 60_000).toISOString());
  let query = params.toString();
  while (query) {
    const response = await fetch(`${BASE}/v1/cards?${query}`, { headers });
    if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    for (const card of await response.json()) await saveCard(card); // write into your store by card.id
    const cursor = response.headers.get("X-Next-Cursor");
    if (cursor) params.set("cursor", cursor); // keep updated_since: the cursor needs the same filters
    query = cursor ? params.toString() : "";
  }
  return startedAt; // pass it as `since` next time
}

Silinenler

Bir liste yalnızca var olan nesneleri döndürür, bu yüzden bir şeyin silindiğini size söyleyemez. Silinenleri olay beslemesinden alın:

curl -G https://api.sursa.com/v1/webhook-events \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "type=card.deleted" \
  --data-urlencode "created_since=2026-10-23T00:00:00Z"

Beslemeyi okumak için admin rolüne ve webhooks:manage kapsamına sahip bir anahtar gerekir. Olaylar 30 gün saklanır. Senkronizasyonunuz bundan daha uzun süre çalışmadıysa listenin tamamını yeniden okuyun ve artık listede olmayan her nesneyi deponuzdan kaldırın.

Veri ambarına aktarma kılavuzu listeleri, updated_since parametresini ve olay beslemesini tek bir işte bir araya getirir.