ID của đối tượng

Mọi đối tượng của API đều có id. Hãy lưu nó trong hệ thống của bạn khi cần quay lại đối tượng: tên và tiêu đề có thể thay đổi, ID thì không bao giờ.

Đối tượng	`id`	Ví dụ
Thẻ, thư mục	Chuỗi	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Sự kiện	Chuỗi có tiền tố `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Lượt tải lên	Chuỗi có tiền tố `upl_`	`"upl_8b0c…"`
Ứng dụng OAuth	Chuỗi có tiền tố `app_`	`"app_5f1c…"`
Bộ sưu tập, người dùng, nhóm, khóa API, webhook, tác vụ và hầu hết các đối tượng khác	Số nguyên	`3`

Hãy coi ID là không trong suốt. Không phân tích chúng và không giả định định dạng nào ngoài kiểu: ID dạng chuỗi có thể là bất kỳ chuỗi nào, dài tới mức trường của nó cho phép.

Những loại đối tượng mới mà bạn có thể sẽ tham chiếu từ hệ thống của mình nhận ID dạng chuỗi với một tiền tố ngắn chỉ loại đối tượng, theo sau là 32 ký tự thập lục phân.

Tham chiếu giữa các đối tượng

Đối tượng tham chiếu tới nhau bằng ID, trong các trường có tên <object>_id: collection_id, owner_id, folder_id. Để nhận đối tượng liên quan trong cùng phản hồi, hãy dùng expand[].

Tham số đường dẫn nhận ID cũng được đặt tên theo cách này: {card_id}, {webhook_id}, {upload_id}.

Bộ sưu tập theo ID

Bộ sưu tập có cả id lẫn name duy nhất, chẳng hạn support. Những đường dẫn có từ trước khi ID được ưu tiên nhận tên của bộ sưu tập:

GET /v1/collections/support/stats

Chính các đường dẫn đó cũng nhận ID, viết dưới dạng id:<number>:

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

Trong mã mới, hãy ưu tiên dạng id:: quản trị viên có thể đổi tên bộ sưu tập, nhưng ID của nó giữ nguyên. Một đoạn chỉ gồm chữ số, chẳng hạn /v1/collections/3, vẫn có nghĩa là bộ sưu tập có tên 3. Tên bộ sưu tập không thể chứa :, nên hai dạng này không bao giờ lẫn với nhau.

Trong phần thân yêu cầu và tham số truy vấn, collection_id đứng cạnh trường collection có từ trước (tên). Khi bạn truyền cả hai, collection_id được ưu tiên. collection_id không tồn tại trong tổ chức, hoặc khóa không được phép xem, trả về 404 với mã collections.not_found.

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

ID của riêng bạn

Thẻ có thể mang ID của bản ghi gốc trong hệ thống của bạn, trong external_id: tối đa 512 ký tự, duy nhất trong số các thẻ của tổ chức. Nhờ đó bạn không bao giờ phải lưu ID Sursa của thẻ:

Endpoint	Chức năng
`PUT /v1/cards-by-external-id/{external_id}`	Tạo thẻ, hoặc thay thế nội dung nếu thẻ đã tồn tại.
`GET /v1/cards-by-external-id/{external_id}`	Đọc thẻ.
`GET /v1/cards?external_id=…`	Tìm thẻ trong danh sách, cùng các bộ lọc khác.

Hãy mã hóa URL cho external_id khi nó là một phần của đường dẫn: crm/A-1042 thành crm%2FA-1042.

Tài liệu của một nguồn tùy chỉnh có external_id riêng trong phạm vi nguồn của chúng. Hai loại này không xung đột: thẻ của nguồn tùy chỉnh được thay đổi bằng cách gửi lại tài liệu tới nguồn của nó, chứ không phải bằng PUT /v1/cards-by-external-id/…, endpoint này khi đó trả về 409 với mã cards.managed_by_source.