Ідентифікатори об’єктів

Кожен об’єкт 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

Колекції мають і 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 не існує в організації або ключу не дозволено бачити цю колекцію, API повертає 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.