Nesne kimlikleri

API’deki her nesnenin bir id alanı vardır. Nesneye daha sonra yeniden ulaşmanız gerekiyorsa bu değeri kendi sisteminizde saklayın: adlar ve başlıklar değişebilir, kimlikler hiçbir zaman değişmez.

Nesne	`id`	Örnek
Kart, klasör	Dize	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Olay	`evt_` önekli dize	`"evt_0123456789abcdef0123456789abcdef"`
Yükleme	`upl_` önekli dize	`"upl_8b0c…"`
OAuth uygulaması	`app_` önekli dize	`"app_5f1c…"`
Koleksiyon, kullanıcı, grup, API anahtarı, webhook, iş ve diğerlerinin çoğu	Tam sayı	`3`

Kimlikleri opak kabul edin. Onları ayrıştırmayın ve türün ötesinde bir biçim varsaymayın: dize türündeki bir kimlik, alanının izin verdiği uzunluğa kadar herhangi bir dize olabilir.

Kendi sistemlerinizden büyük olasılıkla başvuracağınız yeni nesne türleri, türü adlandıran kısa bir önek ve ardından 32 onaltılık karakterden oluşan dize kimlikler alır.

Nesneler arasındaki başvurular

Nesneler birbirine <object>_id biçiminde adlandırılmış alanlarda kimlikle başvurur: collection_id, owner_id, folder_id. İlgili nesneyi aynı yanıtta almak için expand[] parametresini kullanın.

Kimlik alan yol parametreleri de aynı şekilde adlandırılır: {card_id}, {webhook_id}, {upload_id}.

Kimlikle koleksiyonlar

Koleksiyonların hem bir id değeri hem de support gibi benzersiz bir name değeri vardır. Kimliklerin tercih edilmeye başlanmasından önce var olan yollar koleksiyonun adını alır:

GET /v1/collections/support/stats

Aynı yollar, id:<number> biçiminde yazılan kimliği de kabul eder:

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

Yeni kodda id: biçimini tercih edin: bir yönetici koleksiyonu yeniden adlandırabilir, ancak kimliği aynı kalır. /v1/collections/3 gibi yalnızca rakamlardan oluşan bir yol bölümü hâlâ adı 3 olan koleksiyonu ifade eder. Koleksiyon adı : içeremez, bu yüzden iki biçim hiçbir zaman karışmaz.

İstek gövdelerinde ve sorgu parametrelerinde collection_id, eski collection (ad) parametresinin yanında yer alır. İkisini birlikte gönderirseniz collection_id geçerli olur. Kuruluşta bulunmayan ya da anahtarın erişemediği bir collection_id değeri, collections.not_found koduyla 404 döndürür.

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

Kendi kimlikleriniz

Kartlar, sisteminizde geldikleri kaydın kimliğini external_id alanında taşıyabilir: en fazla 512 karakter, kuruluşun kartları arasında benzersiz. Bu alan sayesinde bir kartın Sursa kimliğini saklamanız hiçbir zaman gerekmez:

Uç nokta	Ne yapar
`PUT /v1/cards-by-external-id/{external_id}`	Kartı oluşturur ya da kart varsa içeriğini değiştirir.
`GET /v1/cards-by-external-id/{external_id}`	Kartı okur.
`GET /v1/cards?external_id=…`	Kartı başka filtrelerle birlikte bir listede bulur.

external_id yolun bir parçası olduğunda değerini URL kodlamasıyla yazın: crm/A-1042, crm%2FA-1042 olur.

Özel kaynak belgelerinin, kendi kaynakları içinde ayrı external_id değerleri vardır. İkisi çakışmaz: özel kaynağa ait bir kart, belgeyi kaynağına yeniden göndererek değiştirilir, PUT /v1/cards-by-external-id/… ile değil; bu durumda o uç nokta cards.managed_by_source koduyla 409 yanıtı verir.