对象 ID

API 中的每个对象都有 id。之后需要再次访问该对象时，请把 ID 保存在您的系统中：名称和标题可能会变，ID 永远不变。

对象	`id`	示例
卡片、文件夹	字符串	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
事件	带前缀 `evt_` 的字符串	`"evt_0123456789abcdef0123456789abcdef"`
上传	带前缀 `upl_` 的字符串	`"upl_8b0c…"`
OAuth 应用	带前缀 `app_` 的字符串	`"app_5f1c…"`
合集、用户、用户组、API 密钥、Webhook、作业和大多数其他对象	整数	`3`

请把 ID 当作不透明的值。不要解析 ID，除了类型以外也不要假定其格式：字符串 ID 可以是任意字符串，长度不超过其字段允许的范围。

您可能会在自己的系统中引用的新对象种类，使用带短前缀的字符串 ID：前缀表示对象种类，后跟 32 个十六进制字符。

对象之间的引用

对象通过 ID 相互引用，字段名为 <object>_id：collection_id、owner_id、folder_id。要在同一个响应中获取关联对象，请使用 expand[]。

接受 ID 的路径参数也按同样的方式命名：{card_id}、{webhook_id}、{upload_id}。

按 ID 指定合集

合集既有 id，也有唯一的 name，例如 support。在优先使用 ID 之前就已存在的路径接受合集的名称：

GET /v1/collections/support/stats

这些路径也接受 ID，写作 id:<number>：

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

新代码请优先使用 id: 形式：管理员可以重命名合集，但合集的 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"

您自己的 ID

卡片可以在 external_id 中保存其来源记录在您系统中的 ID：最多 512 个字符，在组织的所有卡片中唯一。有了它，就不必保存卡片在 Sursa 中的 ID：

接口	作用
`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。