ID objek

Setiap objek API memiliki id. Simpan ID itu di sistem Anda jika Anda perlu kembali ke objek tersebut: nama dan judul dapat berubah, ID tidak pernah berubah.

Objek	`id`	Contoh
Kartu, folder	String	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Peristiwa	String dengan awalan `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Unggahan	String dengan awalan `upl_`	`"upl_8b0c…"`
Aplikasi OAuth	String dengan awalan `app_`	`"app_5f1c…"`
Koleksi, pengguna, grup, kunci API, webhook, job, dan sebagian besar lainnya	Bilangan bulat	`3`

Perlakukan ID sebagai nilai buram. Jangan mengurainya, dan jangan mengasumsikan format apa pun selain tipenya: ID string dapat berupa string apa pun, hingga panjang yang diizinkan field-nya.

Jenis objek baru yang kemungkinan besar Anda rujuk dari sistem Anda sendiri mendapat ID string dengan awalan pendek yang menyebutkan jenisnya, diikuti 32 karakter heksadesimal.

Rujukan antarobjek

Objek saling merujuk melalui ID, dalam field bernama <object>_id: collection_id, owner_id, folder_id. Untuk mendapatkan objek terkait dalam respons yang sama, pakai expand[].

Parameter path yang menerima ID dinamai dengan cara yang sama: {card_id}, {webhook_id}, {upload_id}.

Koleksi menurut ID

Koleksi memiliki id sekaligus name yang unik, seperti support. Path yang sudah ada sebelum ID diutamakan menerima nama koleksi:

GET /v1/collections/support/stats

Path yang sama juga menerima ID, ditulis sebagai id:<number>:

curl https://api.sursa.com/v1/collections/id:3/stats \
  -H "Authorization: Bearer $SURSA_API_KEY"

Utamakan bentuk id: dalam kode baru: administrator dapat mengganti nama koleksi, tetapi ID-nya tetap sama. Segmen yang hanya berisi angka, seperti /v1/collections/3, tetap berarti koleksi yang bernama 3. Nama koleksi tidak boleh berisi :, jadi kedua bentuk itu tidak pernah tertukar.

Dalam isi permintaan dan parameter kueri, collection_id tersedia di samping collection (nama) yang lebih lama. Jika Anda memberikan keduanya, collection_id yang berlaku. collection_id yang tidak ada di organisasi, atau yang tidak boleh dilihat oleh kunci, mengembalikan 404 dengan kode collections.not_found.

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "collection_id=3"

ID Anda sendiri

Kartu dapat membawa ID catatan asalnya di sistem Anda, dalam external_id: hingga 512 karakter, unik di antara kartu-kartu organisasi. Dengan ID ini Anda tidak perlu menyimpan ID Sursa sebuah kartu:

Endpoint	Fungsinya
`PUT /v1/cards-by-external-id/{external_id}`	Membuat kartu, atau mengganti kontennya jika kartu sudah ada.
`GET /v1/cards-by-external-id/{external_id}`	Membaca kartu.
`GET /v1/cards?external_id=…`	Menemukan kartu dalam daftar, bersama penyaring lain.

Lakukan URL-encode pada external_id jika nilai itu menjadi bagian dari path: crm/A-1042 menjadi crm%2FA-1042.

Dokumen sumber kustom memiliki external_id sendiri di dalam sumbernya. Keduanya tidak bertabrakan: kartu dari sumber kustom diubah dengan mengirim dokumennya lagi ke sumbernya, bukan dengan PUT /v1/cards-by-external-id/…, yang dalam kasus itu menjawab 409 dengan kode cards.managed_by_source.