Identifikátory objektů

Každý objekt API má id. Pokud se k objektu potřebujete vracet, uložte si ho ve svém systému: jména a názvy se mohou měnit, ID nikdy.

Objekt	`id`	Příklad
Karta, složka	Řetězec	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Událost	Řetězec s prefixem `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Nahrávání	Řetězec s prefixem `upl_`	`"upl_8b0c…"`
Aplikace OAuth	Řetězec s prefixem `app_`	`"app_5f1c…"`
Kolekce, uživatel, skupina, klíč API, webhook, úloha a většina ostatních	Celé číslo	`3`

Považujte ID za neprůhledná. Neparsujte je a nepředpokládejte žádný formát kromě typu: řetězcové ID může být jakýkoli řetězec až do délky, kterou jeho pole dovoluje.

Nové druhy objektů, na které budete pravděpodobně odkazovat ze svých systémů, dostávají řetězcová ID s krátkým prefixem, který pojmenovává druh objektu, a za ním 32 šestnáctkových znaků.

Odkazy mezi objekty

Objekty na sebe odkazují pomocí ID v polích pojmenovaných <object>_id: collection_id, owner_id, folder_id. Chcete-li související objekt získat ve stejné odpovědi, použijte expand[].

Parametry cesty, které přijímají ID, se pojmenovávají stejně: {card_id}, {webhook_id}, {upload_id}.

Kolekce podle ID

Kolekce mají id i jedinečný name, například support. Cesty, které existovaly dřív, než se začala upřednostňovat ID, přijímají název kolekce:

GET /v1/collections/support/stats

Tytéž cesty přijímají také ID zapsané jako id:<number>:

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

V novém kódu dávejte přednost tvaru id:: administrátor může kolekci přejmenovat, ale její ID zůstane stejné. Samotný segment číslic, například /v1/collections/3, stále znamená kolekci s názvem 3. Název kolekce nesmí obsahovat :, takže se oba tvary nikdy nepomíchají.

V tělech požadavků a parametrech dotazu stojí collection_id vedle dřívějšího collection (název). Když předáte obojí, platí collection_id. collection_id, které v organizaci neexistuje nebo které klíč nesmí vidět, vrátí 404 s kódem collections.not_found.

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

Vlastní identifikátory

Karty mohou v external_id nést identifikátor záznamu ve vašem systému, ze kterého pocházejí: až 512 znaků, jedinečný mezi kartami organizace. Díky němu si nikdy nemusíte ukládat ID, které kartě přidělila Sursa:

Operace	Co dělá
`PUT /v1/cards-by-external-id/{external_id}`	Vytvoří kartu, nebo nahradí její obsah, pokud už existuje.
`GET /v1/cards-by-external-id/{external_id}`	Přečte kartu.
`GET /v1/cards?external_id=…`	Najde kartu v seznamu spolu s dalšími filtry.

Když je external_id součástí cesty, zakódujte ho pro URL: z crm/A-1042 se stane crm%2FA-1042.

Dokumenty vlastního zdroje mají vlastní external_id v rámci svého zdroje. Obojí se nekříží: karta vlastního zdroje se mění opětovným odesláním dokumentu do jejího zdroje, ne pomocí PUT /v1/cards-by-external-id/…, které v takovém případě odpoví 409 s kódem cards.managed_by_source.