Objektu ID

Katram API objektam ir id. Saglabājiet to savā sistēmā, ja pie objekta būs jāatgriežas: nosaukumi un virsraksti var mainīties, ID – nekad.

Objekts	`id`	Piemērs
Kartīte, mape	Virkne	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Notikums	Virkne ar prefiksu `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Augšupielāde	Virkne ar prefiksu `upl_`	`"upl_8b0c…"`
OAuth lietotne	Virkne ar prefiksu `app_`	`"app_5f1c…"`
Kolekcija, lietotājs, grupa, API atslēga, webhook galapunkts, darbs un vairums citu	Vesels skaitlis	`3`

Uztveriet ID kā necaurredzamus. Neparsējiet tos un nepieņemiet nekādu formātu papildus tipam: virknes ID var būt jebkura virkne līdz garumam, ko atļauj tā lauks.

Jauniem objektu veidiem, uz kuriem jūs, visticamāk, atsauksieties no savām sistēmām, tiek piešķirti virknes ID: īss prefikss, kas nosauc veidu, un aiz tā 32 heksadecimālas rakstzīmes.

Atsauces starp objektiem

Objekti atsaucas cits uz citu ar ID laukos, kuru nosaukums ir <object>_id: collection_id, owner_id, folder_id. Lai saistīto objektu saņemtu tajā pašā atbildē, izmantojiet expand[].

Ceļa parametri, kas pieņem ID, ir nosaukti tāpat: {card_id}, {webhook_id}, {upload_id}.

Kolekcijas pēc ID

Kolekcijām ir gan id, gan unikāls name, piemēram, support. Ceļi, kas pastāvēja, pirms priekšroka tika dota ID, pieņem kolekcijas nosaukumu:

GET /v1/collections/support/stats

Tie paši ceļi pieņem arī ID, kas rakstīts kā id:<number>:

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

Jaunā kodā dodiet priekšroku formai id:: administrators var kolekciju pārdēvēt, bet tās ID paliek tas pats. Segments tikai no cipariem, piemēram, /v1/collections/3, joprojām nozīmē kolekciju ar nosaukumu 3. Kolekcijas nosaukumā nevar būt :, tāpēc abas formas nekad nesajaucas.

Pieprasījumu saturā un vaicājuma parametros collection_id ir blakus agrākajam collection (nosaukumam). Ja nododat abus, noteicošais ir collection_id. collection_id, kas organizācijā neeksistē vai kuru atslēgai nav atļauts redzēt, atgriež 404 ar kodu collections.not_found.

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

Jūsu pašu ID

Kartītēs laukā external_id var glabāt tā jūsu sistēmas ieraksta ID, no kura kartīte nāk: līdz 512 rakstzīmēm, unikāls starp organizācijas kartītēm. Ar to jums nekad nav jāglabā kartītes Sursas ID:

Operācija	Ko tā dara
`PUT /v1/cards-by-external-id/{external_id}`	Izveido kartīti vai aizstāj tās saturu, ja tā jau eksistē.
`GET /v1/cards-by-external-id/{external_id}`	Nolasa kartīti.
`GET /v1/cards?external_id=…`	Atrod kartīti sarakstā, kopā ar citiem filtriem.

Ja external_id ir ceļa daļa, kodējiet to URL kodējumā: crm/A-1042 kļūst par crm%2FA-1042.

Pielāgota avota dokumentiem ir savs external_id sava avota robežās. Tie nesaduras: pielāgota avota kartīti maina, vēlreiz nosūtot dokumentu tās avotam, nevis ar PUT /v1/cards-by-external-id/…, kas šādā gadījumā atbild ar 409 un kodu cards.managed_by_source.