オブジェクトの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は、フィールドで許される長さまでの任意の文字列になりえます。

自社のシステムから参照することが多い新しい種類のオブジェクトには、種類を表す短いプレフィックスと32文字の16進数からなる文字列の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という名前のコレクションを意味します。コレクションの名前には:を含められないので、2つの形が混同されることはありません。

リクエストボディとクエリパラメーターでは、以前のcollection（名前）と並んでcollection_idを使えます。両方を渡すとcollection_idが優先されます。組織に存在しない、またはキーで参照できないcollection_idを指定すると、コードcollections.not_foundとともに404が返ります。

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/…では変更できず、その場合はコードcards.managed_by_sourceとともに409が返ります。