Идентификаторы объектов

У каждого объекта 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.