Identifiants des objets

Chaque objet de l’API a un id. Conservez-le dans votre système quand vous devez revenir à l’objet : les noms et les titres peuvent changer, les identifiants jamais.

Objet	`id`	Exemple
Fiche, dossier	Chaîne	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Événement	Chaîne avec le préfixe `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Téléversement	Chaîne avec le préfixe `upl_`	`"upl_8b0c…"`
Application OAuth	Chaîne avec le préfixe `app_`	`"app_5f1c…"`
Collection, utilisateur, groupe, clé API, webhook, job et la plupart des autres	Entier	`3`

Traitez les identifiants comme des valeurs opaques. Ne les analysez pas et ne présumez d’aucun format au-delà du type : un identifiant de type chaîne peut être n’importe quelle chaîne, dans la limite de la longueur que permet son champ.

Les nouveaux types d’objets que vous serez sans doute amené à désigner depuis vos propres systèmes reçoivent des identifiants de type chaîne, avec un court préfixe qui nomme le type, suivi de 32 caractères hexadécimaux.

Références entre objets

Les objets se désignent les uns les autres par leur identifiant, dans des champs nommés <object>_id : collection_id, owner_id, folder_id. Pour obtenir l’objet lié dans la même réponse, utilisez expand[].

Les paramètres de chemin qui prennent un identifiant sont nommés de la même façon : {card_id}, {webhook_id}, {upload_id}.

Collections par identifiant

Les collections ont à la fois un id et un name unique, comme support. Les chemins qui existaient avant que les identifiants soient privilégiés prennent le nom de la collection :

GET /v1/collections/support/stats

Les mêmes chemins acceptent aussi l’identifiant, écrit sous la forme id:<number> :

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

Dans le nouveau code, préférez la forme id: : un administrateur peut renommer une collection, mais son identifiant ne change pas. Un segment composé uniquement de chiffres, comme /v1/collections/3, désigne toujours la collection nommée 3. Un nom de collection ne peut pas contenir : : les deux formes ne se confondent donc jamais.

Dans les corps de requête et les paramètres de requête, collection_id côtoie l’ancien collection (le nom). Si vous passez les deux, collection_id l’emporte. Un collection_id qui n’existe pas dans l’organisation, ou que la clé n’a pas le droit de voir, renvoie 404 avec le code collections.not_found.

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

Vos propres identifiants

Les fiches peuvent porter, dans external_id, l’identifiant de l’enregistrement dont elles proviennent dans votre système : jusqu’à 512 caractères, unique parmi les fiches de l’organisation. Vous n’avez alors jamais à conserver l’identifiant Sursa d’une fiche :

Point de terminaison	Ce qu’il fait
`PUT /v1/cards-by-external-id/{external_id}`	Crée la fiche, ou remplace son contenu si elle existe.
`GET /v1/cards-by-external-id/{external_id}`	Lit la fiche.
`GET /v1/cards?external_id=…`	Trouve la fiche dans une liste, avec d’autres filtres.

Encodez l'external_id pour l’URL quand il fait partie du chemin : crm/A-1042 devient crm%2FA-1042.

Les documents d’une source personnalisée ont leur propre external_id au sein de leur source. Les deux n’entrent pas en collision : une fiche d’une source personnalisée se modifie en renvoyant le document à sa source, et non avec PUT /v1/cards-by-external-id/…, qui répond alors 409 avec le code cards.managed_by_source.