객체 ID

API의 모든 객체에는 id가 있어요. 나중에 그 객체를 다시 찾아야 한다면 시스템에 저장해 두세요. 이름과 제목은 바뀔 수 있지만 ID는 절대 바뀌지 않아요.

객체	`id`	예
카드, 폴더	문자열	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
이벤트	접두사가 `evt_`인 문자열	`"evt_0123456789abcdef0123456789abcdef"`
업로드	접두사가 `upl_`인 문자열	`"upl_8b0c…"`
OAuth 애플리케이션	접두사가 `app_`인 문자열	`"app_5f1c…"`
컬렉션, 사용자, 그룹, API 키, 웹훅, 작업 등 대부분의 객체	정수	`3`

ID는 불투명한 값으로 다루세요. 파싱하지 말고, 타입 외의 형식을 가정하지 마세요. 문자열 ID는 필드가 허용하는 길이 안에서 어떤 문자열이든 될 수 있어요.

회사의 시스템에서 가리킬 가능성이 높은 새로운 종류의 객체에는 종류를 나타내는 짧은 접두사 뒤에 16진수 32자가 붙은 문자열 ID가 부여돼요.

객체 간 참조

객체는 <object>_id 형식의 이름을 가진 필드로 서로를 ID로 가리켜요. 예: collection_id, owner_id, folder_id. 관련 객체를 같은 응답에서 받으려면 expand[]를 사용하세요.

ID를 받는 경로 파라미터도 같은 방식으로 이름을 지어요. 예: {card_id}, {webhook_id}, {upload_id}.

ID로 컬렉션 지정하기

컬렉션에는 id와 support 같은 고유한 name이 모두 있어요. ID를 우선하기 전부터 있던 경로는 컬렉션 이름을 받아요.

GET /v1/collections/support/stats

같은 경로는 id:<number> 형식으로 쓴 ID도 받아요.

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

카드에는 회사 시스템에 있는 원본 항목의 ID를 external_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 코드로 응답해요.