Sisteminizi özel kaynakla senkronize etme

Özel kaynak, yerleşik bir bağlayıcısı olmayan bir sistemi bağlar: wiki’niz, destek talebi aracınız, bir veritabanı ya da herhangi bir yerden alınmış bir dışa aktarma. Kodunuz belgeleri Sursa’ya gönderir; Sursa da onları kaynağın ayarlandığı koleksiyon ve klasörlerde kartlara dönüştürür. Bu kartlar, diğer tüm kaynaklardan gelen kartlarla aynı arama, yanıt, doğrulama ve izin özelliklerine sahiptir.

Kartları doğrudan yazmanın aksine özel kaynak, gönderdiklerinizi takip eder. Tam senkronizasyonun sonunda Sursa göndermediğiniz her belgeyi arşivler; böylece sisteminizdeki silmeler ek bir iş yapmadan Sursa’ya ulaşır.

Kaynağı kurma

Bir yönetici kaynağı Sursa’da Sources → New source → Custom source (kaynaklar → yeni kaynak → özel kaynak) bölümünde oluşturur ve şunları seçer:

• kartları için koleksiyonu ve isteğe bağlı olarak bir klasörü;
• klasör modunu: tüm kartlar seçilen klasörde ya da her belgenin path değerini yansıtan alt klasörlerde;
• izinleri: koleksiyonun izinleri ya da her belgenin onu kimlerin görebileceğini listelediği “kaynaktaki gibi” seçeneği.

Kaynak sayfası kaynağın kimliğini gösterir; örneklerde 42 kullanılır.

Anahtar seçme

Tek bir entegrasyon için, özellikle üçüncü taraf bir platformda çalışan bir entegrasyon için en güvenli seçenek kaynak anahtarıdır. import:write kapsamına sahip bir kuruluş anahtarı, birden fazla kaynağı besleyen bir hizmete uygundur.

İki anahtar da aynı şekilde gönderilir ve tüm gönderim uç noktaları /v1/push/sources/{source_id} altındadır. Anahtarı ve kaynağın durumunu GET /v1/push/sources/{source_id} ile kontrol edin:

curl https://api.sursa.com/v1/push/sources/42 \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY"

{"source_id": 42, "name": "Helpdesk articles", "documents": 1840, "open_sync": null}

Belge

Tek bir belge, content yerine bir multipart/form-data isteğinde en fazla 100 MB boyutunda bir dosya taşıyabilir: dosya file bölümünde, yukarıdaki alanlar JSON olarak document bölümünde. upload_id ve attachments için parçalar hâlinde yüklemeler, import:write kapsamına sahip bir kuruluş anahtarıyla ve import_attachment amacıyla oluşturulur; kaynak anahtarı bunları oluşturamaz.

Göndermenin iki yolu

Doğrudan güncellemeler, yardım masanızdan gelen bir webhook ya da Zapier’deki bir adım gibi her değişikliği size bildiren sistemlere uygundur. Bir belgeyi oluşturulduğunda ya da değiştiğinde gönderin, kaldırıldığında silin:

Değişiklikler yaklaşık bir dakika içinde karta dönüşür; art arda gelen birkaç değişiklik birlikte işlenir.

Senkronizasyonlar düzenli dışa aktarmalara uygundur: her şeyi ya da değişen her şeyi gönderirsiniz, Sursa da mutabakat yapar. Bu kılavuzun geri kalanı senkronizasyonları anlatır.

Tam senkronizasyon çalıştırma

Bir senkronizasyonun üç adımı vardır: açmak, göndermek, kapatmak.

1. Açın

POST /v1/push/sources/{source_id}/syncs bir senkronizasyon açar ve numarasını döndürür:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Idempotency-Key: sync-2026-10-24" \
  -H "Content-Type: application/json" \
  -d '{"type": "initial", "max_minutes": 180}'

{"sync_number": 7, "type": "initial", "status": "open", "opened_at": "2026-10-24T02:00:00Z",
 "expires_at": "2026-10-24T05:00:00Z", "pushed": 0, "removed": 0}

• type, kaynağın ilk senkronizasyonu için initial, bir senkronizasyon tamamlandıktan sonra incremental olur. Tamamlanmış bir senkronizasyondan önce açılan incremental senkronizasyon sources.push_initial_required döndürür.
• Aynı anda yalnızca bir senkronizasyon açık olabilir: ikincisi 409 sources.push_sync_open döndürür.
• Bir senkronizasyon max_minutes süresi boyunca (varsayılan olarak 60, en fazla 1.440) açık kalır. Bu sürenin sonunda süresi dolar: hiçbir şey arşivlenmez ve numarası artık kabul edilmez. Dışa aktarmanızın süresinden rahatça uzun bir süre seçin.

2. Belgeleri gönderin

Belgeleri senkronizasyon numarasıyla birlikte en fazla 500 belgelik toplu gönderimler hâlinde gönderin. Bir toplu gönderimin gövdesi en fazla 50 MiB olabilir; toplu gönderimdeki dosyalar upload_id olarak iletilir.

curl -X POST https://api.sursa.com/v1/push/sources/42/documents/batch \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Idempotency-Key: sync-7-batch-1" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_number": 7,
    "documents": [
      {"external_id": "faq-shipping", "title": "Shipping", "content_type": "markdown",
       "content": "# Shipping\n\nWe ship worldwide within 5 days.", "path": ["Support"]},
      {"external_id": "faq-refunds", "title": "Refunds", "content_type": "html",
       "content": "<p>Refunds take 14 days.</p>", "path": ["Support", "Billing"],
       "permissions": {"groups": ["Support"]}, "metadata": {"article_id": "1042"}}
    ]
  }'

Yanıt, gönderdiğiniz sırayla her belge için bir sonuç içerir:

{
  "results": [
    {"external_id": "faq-shipping", "result": "unchanged", "status": "indexed", "card_id": "8c1d…", "version": "5e0f…"},
    {"external_id": "faq-refunds", "result": "updated", "status": "pending", "card_id": "3f2c…", "version": "a91b…"}
  ]
}

Varsayılan olarak bir toplu gönderimdeki her belge ayrı ayrı uygulanır: hatalı bir belge diğerlerini durdurmaz.

Son senkronizasyondan bu yana değişmeyen belgelerin yeniden gönderilmesi gerekmez. Tam mutabakatın onları koruması için bu belgeleri kimlikleriyle, istek başına en fazla 1.000 kimlik olmak üzere POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch ile yeniden göndermeden onaylayın:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs/7/touch \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ids": ["faq-contact", "faq-hours"]}'

3. Kapatın

POST /v1/push/sources/{source_id}/syncs/{sync_number}/close senkronizasyonu sona erdirir:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs/7/close \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "complete"}'

Dışa aktarmanız yarıda kaldığında senkronizasyonu her zaman failed ile kapatın: yarım kalan bir dışa aktarmadan sonra gönderilen complete, sırası gelmemiş her belgeyi arşivler. Aynı kapatma isteğini tekrarlamak aynı sonucu döndürür.

Kapatmadan sonra Sursa belgeleri yaklaşık bir dakika içinde kartlara dönüştürür. Kaynak sayfası her senkronizasyonu gönderilen ve arşivlenen belge sayılarıyla birlikte gösterir; GET /v1/push/sources/{source_id}/syncs/{sync_number} de aynı sayaçları döndürür.

Artımlı senkronizasyonlar

Tam senkronizasyonlar arasında yalnızca değişenleri gönderin:

1. "type": "incremental" ile açın.
2. Değişen belgeleri gönderin ve kaldırılan belgelerin kimliklerini deletes alanına yazın (aşağıya bakın).
3. complete_incremental ile kapatın.

Artımlı çalıştırmaların kaçırdığı her şeyi yakalamak için ara sıra, örneğin haftada bir, tam senkronizasyon çalıştırın.

Toplu gönderimde belge silme

Bir toplu gönderim, yazdığı belgelerle birlikte belge de kaldırabilir. Kaldırılacak belgelerin kimliklerini deletes alanında listeleyin:

{
  "sync_number": 8,
  "documents": [{"external_id": "faq-shipping", "title": "Shipping", "content": "…"}],
  "deletes": ["faq-old-returns", "faq-fax"]
}

Silinen her kimlik results içinde kendi girdisini alır: result değeri deleted ya da kaynakta böyle bir belge yoksa not_found olur. Aynı kimliği yeniden silmek zararsızdır.

Atomik toplu gönderimler

Bazı değişiklikler yalnızca birlikte anlamlıdır; örneğin bir belge ve onun yerini alan belge. "atomic": true gönderin; toplu gönderim ya tamamen uygulanır ya da hiç uygulanmaz: herhangi bir belge denetimlerden geçemezse toplu gönderimden hiçbir şey uygulanmaz ve yanıt, sources.push_batch_rejected koduyla 422 olur; her belgenin sonucu error.details.results içinde gelir: başarısız olan belgelerde error, diğerlerinde skipped bulunur.

{"sync_number": 8, "atomic": true, "documents": […], "deletes": ["faq-old-returns"]}

atomic olmadan bir toplu gönderim belge belge uygulanır. Atomik toplu gönderimleri ilişkili değişiklikler için, normal toplu gönderimleri ise hatalı bir belgenin geri kalanını engellememesi gereken toplu yüklemeler için kullanın.

Her belgenin sonucunu kontrol etme

Toplu gönderim yanıtı her belgenin nasıl yazıldığını söyler. Karta dönüştürme sonradan gerçekleşir, bu yüzden status hâlâ pending olabilir. Bir senkronizasyonun karta dönüşmeyen belgelerini bulmak için:

curl "https://api.sursa.com/v1/push/sources/42/syncs/7/documents?status=failed" \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY"

Her girdide external_id, title, status, card_id, version ve reason bulunur; liste cursor ile sayfalanır. status ayrıca pending, processing, indexed ve removed değerlerini de alır.

Sormak yerine size bildirilmesini de sağlayabilirsiniz: import.sync_completed (bir senkronizasyon kapatıldı ve toplamlarıyla birlikte işlendi) ve import.document_failed (bir belge karta dönüşmedi, reason değeriyle birlikte) olayları webhook ile ve olay beslemesinde gelir.

Yeniden denemeler

• Her POST isteğiyle bir Idempotency-Key gönderin. Aynı anahtarla tekrarlanan bir toplu gönderim ilk sonucu döndürür.
• Anahtar olmasa bile aynı external_id değerine sahip bir belge hiçbir zaman ikinci bir kart olmaz: unchanged ya da updated olur.
• Süreç bir senkronizasyonun ortasında durursa eskisinin süresi dolduktan sonra yeni bir senkronizasyon açın ya da numarası hâlâ elinizdeyse eskisini failed ile kapatın ve senkronizasyonu yeniden çalıştırın.

Sınırlar

Kaynağın belge sınırını aşan bir belge, toplu gönderimde limit_reached nedeniyle başarısız olur; tek belgelik bir istek ise sources.push_too_many_documents koduyla 409 döndürür. Hız sınırları diğer tüm isteklerde olduğu gibi uygulanır; Hız sınırları ve kotalar sayfasına bakın.

Sık karşılaşılan hatalar