Objektų ID

Kiekvienas API objektas turi id. Išsaugokite jį savo sistemoje, kai prie objekto reikės grįžti: pavadinimai ir antraštės gali keistis, ID – niekada.

Objektas	`id`	Pavyzdys
Kortelė, aplankas	Eilutė	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Įvykis	Eilutė su priešdėliu `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Įkėlimas	Eilutė su priešdėliu `upl_`	`"upl_8b0c…"`
OAuth programa	Eilutė su priešdėliu `app_`	`"app_5f1c…"`
Rinkinys, naudotojas, grupė, API raktas, webhook galinis taškas, darbas ir dauguma kitų	Sveikasis skaičius	`3`

ID laikykite nepermatomais. Jų neanalizuokite ir nedarykite prielaidų apie formatą, išskyrus tipą: eilutės ID gali būti bet kokia eilutė, ne ilgesnė, nei leidžia jos laukas.

Naujų rūšių objektai, į kuriuos tikėtina nurodysite iš savo sistemų, gauna eilutės ID su trumpu rūšį nurodančiu priešdėliu ir po jo 32 šešioliktainiais simboliais.

Objektų nuorodos

Objektai vienas į kitą nurodo pagal ID, laukuose, pavadintuose <object>_id: collection_id, owner_id, folder_id. Kad susijusį objektą gautumėte tame pačiame atsake, naudokite expand[].

Kelio parametrai, kuriems perduodamas ID, pavadinti taip pat: {card_id}, {webhook_id}, {upload_id}.

Rinkiniai pagal ID

Rinkiniai turi ir id, ir unikalų name, pavyzdžiui, support. Keliai, kurie egzistavo dar prieš pirmenybę suteikiant ID, priima rinkinio pavadinimą:

GET /v1/collections/support/stats

Tie patys keliai priima ir ID, užrašytą kaip id:<number>:

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

Naujame kode rinkitės formą id:: administratorius gali pervadinti rinkinį, bet jo ID nesikeičia. Segmentas vien iš skaitmenų, pavyzdžiui, /v1/collections/3, vis dar reiškia rinkinį, pavadintą 3. Rinkinio pavadinime negali būti :, todėl šios dvi formos niekada nesusipainioja.

Užklausų turinyje ir užklausos parametruose collection_id yra šalia ankstesnio collection (pavadinimo). Jei perduodate abu, viršenybę turi collection_id. collection_id, kurio organizacijoje nėra arba kurio raktui neleidžiama matyti, grąžina 404 su kodu collections.not_found.

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

Jūsų ID

Kortelės lauke external_id gali turėti jūsų sistemos įrašo, iš kurio jos kilusios, ID: iki 512 simbolių, unikalų tarp organizacijos kortelių. Su juo jums niekada nereikia saugoti kortelės Sursos ID:

Operacija	Ką ji daro
`PUT /v1/cards-by-external-id/{external_id}`	Sukuria kortelę arba, jei ji yra, pakeičia jos turinį.
`GET /v1/cards-by-external-id/{external_id}`	Nuskaito kortelę.
`GET /v1/cards?external_id=…`	Randa kortelę sąraše, kartu su kitais filtrais.

Kai external_id yra kelio dalis, koduokite jį URL kodavimu: crm/A-1042 virsta crm%2FA-1042.

Pasirinktinio šaltinio dokumentai turi savo external_id savo šaltinio ribose. Jie nesikerta: pasirinktinio šaltinio kortelė keičiama dar kartą išsiunčiant dokumentą į jos šaltinį, o ne operacija PUT /v1/cards-by-external-id/…, kuri tokiu atveju grąžina 409 su kodu cards.managed_by_source.