Идентификатори објеката

Сваки објекат API интерфејса има id. Сачувајте га у свом систему када треба да се вратите објекту: имена и наслови могу да се промене, идентификатори никада.

Објекат	`id`	Пример
Картица, фолдер	Стринг	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Догађај	Стринг са префиксом `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Отпремање	Стринг са префиксом `upl_`	`"upl_8b0c…"`
OAuth апликација	Стринг са префиксом `app_`	`"app_5f1c…"`
Колекција, корисник, група, API кључ, вебхук, посао и већина осталих	Цео број	`3`

Идентификаторе третирајте као непрозирне. Не рашчлањујте их и не претпостављајте никакав формат осим типа: стринг идентификатор може бити било који стринг, до дужине коју његово поље дозвољава.

Нове врсте објеката на које ћете вероватно упућивати из својих система добијају стринг идентификаторе са кратким префиксом који означава врсту, након којег следе 32 хексадецимална знака.

Везе између објеката

Објекти упућују један на други преко идентификатора, у пољима са именом <object>_id: collection_id, owner_id, folder_id. Да бисте повезани објекат добили у истом одговору, користите expand[].

Параметри путање који примају идентификатор именују се на исти начин: {card_id}, {webhook_id}, {upload_id}.

Колекције по идентификатору

Колекције имају и id и јединствено име name, на пример support. Путање које су постојале пре него што је предност дата идентификаторима примају име колекције:

GET /v1/collections/support/stats

Исте путање примају и идентификатор, записан као id:<number>:

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

У новом коду користите облик id:: администратор може да преименује колекцију, али њен идентификатор остаје исти. Сегмент који чине само цифре, на пример /v1/collections/3, и даље означава колекцију чије је име 3. Име колекције не може да садржи :, па се та два облика никада не мешају.

У телима захтева и параметрима упита collection_id стоји поред ранијег collection (име). Ако проследите оба, предност има collection_id. collection_id који не постоји у организацији или који кључ нема право да види враћа 404 са кодом collections.not_found.

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

Сопствени идентификатори

Картице могу да носе идентификатор записа из вашег система из ког потичу, у пољу external_id: до 512 знакова, јединствен међу картицама организације. Уз њега никада не морате да чувате идентификатор картице у платформи Sursa:

Операција	Шта ради
`PUT /v1/cards-by-external-id/{external_id}`	Креира картицу или замењује њен садржај ако већ постоји.
`GET /v1/cards-by-external-id/{external_id}`	Чита картицу.
`GET /v1/cards?external_id=…`	Проналази картицу у листи, уз друге филтере.

Кодирајте external_id за URL када је део путање: crm/A-1042 постаје crm%2FA-1042.

Документи сопственог извора имају свој external_id унутар свог извора. Та два се не сукобљавају: картица сопственог извора мења се поновним слањем документа њеном извору, а не помоћу PUT /v1/cards-by-external-id/…, који у том случају одговара са 409 и кодом cards.managed_by_source.