Identyfikatory obiektów

Każdy obiekt API ma id. Zapisz je w swoim systemie, jeśli chcesz później wrócić do obiektu: nazwy i tytuły mogą się zmieniać, identyfikatory – nigdy.

Obiekt	`id`	Przykład
Karta, folder	Ciąg znaków	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Zdarzenie	Ciąg znaków z prefiksem `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Przesyłanie	Ciąg znaków z prefiksem `upl_`	`"upl_8b0c…"`
Aplikacja OAuth	Ciąg znaków z prefiksem `app_`	`"app_5f1c…"`
Kolekcja, użytkownik, grupa, klucz API, webhook, zadanie i większość pozostałych	Liczba całkowita	`3`

Traktuj identyfikatory jako nieprzezroczyste. Nie parsuj ich i nie zakładaj formatu wykraczającego poza typ: identyfikator tekstowy może być dowolnym ciągiem znaków o długości, na jaką pozwala jego pole.

Nowe rodzaje obiektów, do których prawdopodobnie będziesz się odwoływać z własnych systemów, otrzymują identyfikatory tekstowe z krótkim prefiksem nazywającym rodzaj obiektu, po którym następują 32 znaki szesnastkowe.

Odwołania między obiektami

Obiekty odwołują się do siebie przez ID, w polach o nazwach <object>_id: collection_id, owner_id, folder_id. Aby otrzymać powiązany obiekt w tej samej odpowiedzi, użyj expand[].

Parametry ścieżki, które przyjmują ID, mają nazwy utworzone w ten sam sposób: {card_id}, {webhook_id}, {upload_id}.

Kolekcje według ID

Kolekcje mają zarówno id, jak i unikalną nazwę name, np. support. Ścieżki, które istniały, zanim zaczęto preferować identyfikatory, przyjmują nazwę kolekcji:

GET /v1/collections/support/stats

Te same ścieżki przyjmują też ID zapisane jako id:<number>:

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

W nowym kodzie preferuj formę id:: administrator może zmienić nazwę kolekcji, ale jej ID pozostaje takie samo. Segment złożony wyłącznie z cyfr, np. /v1/collections/3, nadal oznacza kolekcję o nazwie 3. Nazwa kolekcji nie może zawierać :, więc obie formy nigdy się nie mylą.

W treściach żądań i parametrach zapytania collection_id występuje obok wcześniejszego collection (nazwy). Gdy przekażesz oba, pierwszeństwo ma collection_id. Wartość collection_id, która nie istnieje w organizacji lub której klucz nie może widzieć, zwraca 404 z kodem collections.not_found.

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

Własne identyfikatory

Karty mogą przechowywać w external_id identyfikator rekordu, z którego pochodzą w Twoim systemie: do 512 znaków, unikalny wśród kart organizacji. Dzięki temu nigdy nie musisz przechowywać identyfikatora karty w Sursie:

Operacja	Co robi
`PUT /v1/cards-by-external-id/{external_id}`	Tworzy kartę albo zastępuje jej treść, jeśli karta istnieje.
`GET /v1/cards-by-external-id/{external_id}`	Odczytuje kartę.
`GET /v1/cards?external_id=…`	Znajduje kartę na liście, razem z innymi filtrami.

Zakoduj external_id do postaci URL, gdy jest częścią ścieżki: crm/A-1042 staje się crm%2FA-1042.

Dokumenty własnego źródła mają własne external_id w obrębie swojego źródła. Te identyfikatory nie kolidują ze sobą: kartę własnego źródła zmienia się, wysyłając dokument ponownie do jej źródła, a nie przez PUT /v1/cards-by-external-id/…, które w takim przypadku odpowiada 409 z kodem cards.managed_by_source.