Objektumazonosítók

Az API minden objektumának van id mezője. Tárold el a saját rendszeredben, ha később vissza kell térned az objektumhoz: a nevek és a címek változhatnak, az azonosítók soha.

Objektum	`id`	Példa
Kártya, mappa	Karakterlánc	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Esemény	Karakterlánc `evt_` előtaggal	`"evt_0123456789abcdef0123456789abcdef"`
Feltöltés	Karakterlánc `upl_` előtaggal	`"upl_8b0c…"`
OAuth-alkalmazás	Karakterlánc `app_` előtaggal	`"app_5f1c…"`
Gyűjtemény, felhasználó, csoport, API-kulcs, webhook, feladat és a legtöbb további objektum	Egész szám	`3`

Kezeld az azonosítókat átlátszatlan értékként. Ne bontsd elemeire őket, és a típuson túl ne feltételezz semmilyen formátumot: a karakterlánc-azonosító bármilyen karakterlánc lehet, a mezője által megengedett hosszig.

Azok az új objektumfajták, amelyekre valószínűleg a saját rendszereidből fogsz hivatkozni, olyan karakterlánc-azonosítót kapnak, amely a fajtát jelölő rövid előtagból és 32 hexadecimális karakterből áll.

Hivatkozások az objektumok között

Az objektumok azonosítóval hivatkoznak egymásra, <object>_id nevű mezőkben: collection_id, owner_id, folder_id. Ha ugyanabban a válaszban a kapcsolódó objektumot is meg szeretnéd kapni, használd az expand[] paramétert.

Az azonosítót váró útvonal-paraméterek neve ugyanígy épül fel: {card_id}, {webhook_id}, {upload_id}.

Gyűjtemények azonosító alapján

A gyűjteményeknek van id mezője és egyedi name mezője is, például support. Azok az útvonalak, amelyek még az azonosítók előtérbe kerülése előtt jöttek létre, a gyűjtemény nevét várják:

GET /v1/collections/support/stats

Ugyanezek az útvonalak az azonosítót is elfogadják, id:<number> alakban:

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

Új kódban az id: alakot részesítsd előnyben: egy adminisztrátor átnevezhet egy gyűjteményt, az azonosítója viszont nem változik. A csak számjegyekből álló szakasz, például a /v1/collections/3, továbbra is a 3 nevű gyűjteményt jelenti. A gyűjtemény neve nem tartalmazhat : karaktert, így a két alak soha nem keveredik össze.

A kéréstörzsekben és a lekérdezési paraméterekben a collection_id a korábbi collection (a név) mellett áll. Ha mindkettőt megadod, a collection_id érvényesül. Ha a collection_id értéke nem létezik a szervezetben, vagy a kulcs nem láthatja, a válasz 404 lesz a collections.not_found kóddal.

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

Saját azonosítók

A kártyák az external_id mezőben tárolhatják annak a rekordnak az azonosítóját, amelyből a saját rendszeredben származnak: legfeljebb 512 karakter, a szervezet kártyái között egyedi. Így soha nem kell eltárolnod a kártya Sursában használt azonosítóját:

Végpont	Mit csinál
`PUT /v1/cards-by-external-id/{external_id}`	Létrehozza a kártyát, vagy ha már létezik, lecseréli a tartalmát.
`GET /v1/cards-by-external-id/{external_id}`	Beolvassa a kártyát.
`GET /v1/cards?external_id=…`	Megkeresi a kártyát egy listában, más szűrőkkel együtt.

Ha az external_id az útvonal része, URL-kódold: a crm/A-1042 értékből crm%2FA-1042 lesz.

Az egyéni források dokumentumainak saját external_id értékük van a forrásukon belül. A kettő nem ütközik: egyéni forrás kártyáját úgy módosíthatod, hogy a dokumentumot újra elküldöd a forrásának, nem pedig a PUT /v1/cards-by-external-id/… végponttal, amely ilyenkor 409 választ ad a cards.managed_by_source kóddal.