Menyinkronkan sistem Anda dengan sumber kustom

Sumber kustom menghubungkan sistem yang tidak memiliki konektor bawaan: wiki Anda, alat tiket Anda, basis data, ekspor dari mana pun. Kode Anda mengirim dokumen ke Sursa, dan Sursa mengubahnya menjadi kartu di koleksi dan folder yang diatur untuk sumber itu, dengan pencarian, jawaban, verifikasi, dan izin yang sama seperti kartu dari sumber lain mana pun.

Berbeda dengan menulis kartu secara langsung, sumber kustom mencatat apa yang sudah Anda kirim. Di akhir sinkronisasi penuh, Sursa mengarsipkan setiap dokumen yang tidak Anda kirim, jadi penghapusan di sistem Anda sampai ke Sursa tanpa kerja tambahan.

Menyiapkan sumber

Administrator membuat sumber di Sursa melalui Sources → New source → Custom source (Sumber → Sumber baru → Sumber kustom), lalu memilih:

• koleksi dan, jika perlu, folder untuk kartu-kartunya;
• mode folder: semua kartu di folder yang dipilih, atau subfolder yang mencerminkan path setiap dokumen;
• izin: izin koleksi, atau “seperti di sumber”, saat setiap dokumen mencantumkan siapa yang boleh melihatnya.

Halaman sumber menampilkan ID-nya; contoh-contoh memakai 42.

Memilih kunci

Kunci sumber adalah pilihan paling aman untuk satu integrasi, terutama integrasi yang berjalan di platform pihak ketiga. Kunci organisasi dengan import:write cocok untuk layanan yang mengisi beberapa sumber.

Kedua kunci dikirim dengan cara yang sama, dan setiap endpoint push berada di bawah /v1/push/sources/{source_id}. Periksa kunci dan keadaan sumber dengan GET /v1/push/sources/{source_id}:

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}

Dokumen

Alih-alih content, satu dokumen dapat membawa file hingga 100 MB dalam permintaan multipart/form-data: file di bagian file, field di atas sebagai JSON di bagian document. Unggahan per bagian untuk upload_id dan attachments dibuat dengan kunci organisasi yang memiliki cakupan import:write dan tujuan import_attachment; kunci sumber tidak dapat membuatnya.

Dua cara mengirim

Pembaruan langsung cocok untuk sistem yang memberi tahu Anda tentang setiap perubahan, seperti webhook dari helpdesk Anda atau langkah di Zapier. Kirim dokumen saat dokumen dibuat atau diubah, dan hapus saat dokumen dihilangkan:

Perubahan menjadi kartu dalam waktu sekitar satu menit; beberapa perubahan berturut-turut diproses bersama.

Sinkronisasi cocok untuk ekspor rutin: Anda mengirim semuanya, atau semua yang berubah, dan Sursa melakukan rekonsiliasi. Bagian selanjutnya dari panduan ini membahas sinkronisasi.

Menjalankan sinkronisasi penuh

Sinkronisasi memiliki tiga langkah: buka, kirim, tutup.

1. Buka

POST /v1/push/sources/{source_id}/syncs membuka sinkronisasi dan mengembalikan nomornya:

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 bernilai initial untuk sinkronisasi pertama sumber, dan incremental setelah ada sinkronisasi yang selesai. Sinkronisasi incremental sebelum ada yang selesai mengembalikan sources.push_initial_required.
• Hanya satu sinkronisasi yang dapat terbuka pada satu waktu: sinkronisasi kedua mengembalikan 409 sources.push_sync_open.
• Sinkronisasi tetap terbuka selama max_minutes (secara default 60, hingga 1.440). Setelah itu sinkronisasi kedaluwarsa: tidak ada yang diarsipkan dan nomornya tidak lagi diterima. Pilih waktu yang cukup lebih lama daripada durasi ekspor Anda.

2. Kirim dokumen

Kirim dokumen dalam batch berisi hingga 500, dengan nomor sinkronisasi. Isi batch hingga 50 MiB; file di dalam batch diberikan sebagai upload_id.

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"}}
    ]
  }'

Respons berisi hasil untuk setiap dokumen, dalam urutan Anda mengirimnya:

{
  "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…"}
  ]
}

Secara default, setiap dokumen dalam batch diterapkan secara tersendiri: satu dokumen yang buruk tidak menghentikan yang lain.

Dokumen yang tidak berubah sejak sinkronisasi terakhir tidak perlu dikirim lagi. Konfirmasikan dokumen itu menurut ID dengan POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, hingga 1.000 ID per permintaan, agar rekonsiliasi penuh mempertahankannya:

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. Tutup

POST /v1/push/sources/{source_id}/syncs/{sync_number}/close mengakhiri sinkronisasi:

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"}'

Tutup dengan failed setiap kali ekspor Anda berhenti di tengah jalan: complete setelah ekspor yang tidak lengkap akan mengarsipkan setiap dokumen yang belum sempat Anda kirim. Mengulang penutupan yang sama mengembalikan hasil yang sama.

Setelah ditutup, Sursa mengubah dokumen menjadi kartu dalam waktu sekitar satu menit. Halaman sumber menampilkan setiap sinkronisasi beserta jumlah dokumen yang dikirim dan diarsipkan, dan GET /v1/push/sources/{source_id}/syncs/{sync_number} mengembalikan penghitung yang sama.

Sinkronisasi inkremental

Di antara sinkronisasi penuh, kirim hanya yang berubah:

1. Buka dengan "type": "incremental".
2. Kirim dokumen yang berubah, dan masukkan ID dokumen yang dihapus ke deletes (lihat di bawah).
3. Tutup dengan complete_incremental.

Jalankan sinkronisasi penuh dari waktu ke waktu, misalnya setiap minggu, untuk menangkap apa pun yang terlewat oleh eksekusi inkremental.

Menghapus dokumen dalam batch

Batch dapat menghapus dokumen bersamaan dengan dokumen yang ditulisnya. Cantumkan ID-nya di deletes:

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

Setiap ID yang dihapus mendapat entrinya sendiri di results, dengan result bernilai deleted, atau not_found jika sumber tidak memiliki dokumen seperti itu. Menghapus ID yang sama lagi tidak berbahaya.

Batch atomik

Beberapa perubahan hanya masuk akal jika dilakukan bersama, misalnya sebuah dokumen dan dokumen yang menggantikannya. Kirim "atomic": true, dan batch diterapkan sepenuhnya atau tidak sama sekali: jika ada dokumen yang gagal dalam pemeriksaannya, tidak ada bagian batch yang diterapkan, dan responsnya 422 dengan kode sources.push_batch_rejected serta hasil setiap dokumen di error.details.results: dokumen yang gagal memiliki error, yang lain skipped.

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

Tanpa atomic, batch diterapkan dokumen demi dokumen. Pakai batch atomik untuk perubahan yang saling terkait, dan batch biasa untuk muatan massal, ketika satu dokumen yang buruk tidak boleh menahan sisanya.

Memeriksa hasil setiap dokumen

Respons batch memberi tahu Anda bagaimana setiap dokumen ditulis. Pengubahannya menjadi kartu terjadi sesudahnya, jadi status masih dapat bernilai pending. Untuk menemukan dokumen sebuah sinkronisasi yang tidak menjadi kartu:

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

Setiap entri memiliki external_id, title, status, card_id, version, dan reason, dan daftar ini dipaginasi dengan cursor. status juga menerima pending, processing, indexed, dan removed.

Anda juga dapat diberi tahu alih-alih bertanya: peristiwa import.sync_completed (sinkronisasi ditutup dan diproses, beserta totalnya) dan import.document_failed (dokumen tidak menjadi kartu, beserta reason-nya) datang melalui webhook dan di umpan peristiwa.

Percobaan ulang

• Kirim Idempotency-Key bersama setiap POST. Batch yang diulang dengan kunci yang sama mengembalikan hasil pertama.
• Bahkan tanpa kunci itu, dokumen dengan external_id yang sama tidak pernah menjadi kartu kedua: dokumen itu bernilai unchanged atau updated.
• Jika proses berhenti di tengah sinkronisasi, buka sinkronisasi baru setelah yang lama kedaluwarsa, atau tutup yang lama dengan failed jika Anda masih memiliki nomornya, lalu jalankan sinkronisasi lagi.

Batas

Dokumen di atas batas dokumen sumber gagal dengan alasan limit_reached dalam batch; permintaan satu dokumen menjawab 409 dengan kode sources.push_too_many_documents. Batas laju berlaku seperti untuk permintaan lainnya; lihat Batas laju dan kuota.

Error yang umum