Identificatorii obiectelor

Fiecare obiect al API-ului are un id. Stocați-l în sistemul propriu când trebuie să reveniți la obiect: numele și titlurile se pot schimba, identificatorii niciodată.

Obiect	`id`	Exemplu
Fișă, dosar	Șir	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Eveniment	Șir cu prefixul `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Încărcare	Șir cu prefixul `upl_`	`"upl_8b0c…"`
Aplicație OAuth	Șir cu prefixul `app_`	`"app_5f1c…"`
Colecție, utilizator, grup, cheie API, webhook, job și majoritatea celorlalte	Număr întreg	`3`

Tratați identificatorii ca opaci. Nu îi analizați și nu presupuneți un format dincolo de tip: un identificator de tip șir poate fi orice șir, până la lungimea permisă de câmpul lui.

Tipurile noi de obiecte la care probabil veți face trimitere din sistemele proprii primesc identificatori de tip șir cu un prefix scurt care numește tipul, urmat de 32 de caractere hexazecimale.

Trimiteri între obiecte

Obiectele fac trimitere unele la altele prin identificator, în câmpuri numite <object>_id: collection_id, owner_id, folder_id. Pentru a primi obiectul asociat în același răspuns, folosiți expand[].

Parametrii de cale care primesc un identificator sunt numiți la fel: {card_id}, {webhook_id}, {upload_id}.

Colecții după identificator

Colecțiile au atât un id, cât și un name unic, de exemplu support. Căile care existau înainte ca identificatorii să devină forma preferată primesc numele colecției:

GET /v1/collections/support/stats

Aceleași căi primesc și identificatorul, scris ca id:<number>:

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

În codul nou preferați forma id:: un administrator poate redenumi o colecție, dar identificatorul ei rămâne același. Un segment format doar din cifre, cum ar fi /v1/collections/3, înseamnă în continuare colecția numită 3. Numele unei colecții nu poate conține :, așa că cele două forme nu se confundă niciodată.

În corpurile cererilor și în parametrii de interogare, collection_id stă alături de collection (numele), folosit anterior. Când le transmiteți pe amândouă, are prioritate collection_id. Un collection_id care nu există în organizație sau pe care cheia nu are voie să-l vadă returnează 404 cu codul collections.not_found.

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

Propriile ID-uri

Fișele pot purta, în external_id, identificatorul înregistrării din care provin în sistemul propriu: cel mult 512 caractere, unic între fișele organizației. Cu el nu mai trebuie să stocați niciodată identificatorul Sursa al unei fișe:

Endpoint	Ce face
`PUT /v1/cards-by-external-id/{external_id}`	Creează fișa sau îi înlocuiește conținutul dacă există.
`GET /v1/cards-by-external-id/{external_id}`	Citește fișa.
`GET /v1/cards?external_id=…`	Găsește fișa într-o listă, împreună cu alte filtre.

Codificați pentru URL valoarea external_id când face parte din cale: crm/A-1042 devine crm%2FA-1042.

Documentele unei surse personalizate au propriul external_id în cadrul sursei lor. Cele două nu intră în conflict: o fișă a unei surse personalizate se modifică trimițând din nou documentul către sursa lui, nu cu PUT /v1/cards-by-external-id/…, care în acest caz răspunde 409 cu codul cards.managed_by_source.