ID degli oggetti

Ogni oggetto dell’API ha un id. Conservalo nel tuo sistema quando devi tornare all’oggetto: nomi e titoli possono cambiare, gli ID mai.

Oggetto	`id`	Esempio
Scheda, cartella	Stringa	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Evento	Stringa con il prefisso `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Caricamento	Stringa con il prefisso `upl_`	`"upl_8b0c…"`
Applicazione OAuth	Stringa con il prefisso `app_`	`"app_5f1c…"`
Raccolta, utente, gruppo, chiave API, webhook, job e quasi tutti gli altri	Intero	`3`

Tratta gli ID come opachi. Non analizzarli e non presupporre un formato oltre al tipo: un ID stringa può essere qualsiasi stringa, fino alla lunghezza consentita dal suo campo.

I nuovi tipi di oggetti a cui probabilmente farai riferimento dai tuoi sistemi ricevono ID stringa con un breve prefisso che indica il tipo, seguito da 32 caratteri esadecimali.

Riferimenti tra oggetti

Gli oggetti fanno riferimento l’uno all’altro tramite ID, in campi con il nome <object>_id: collection_id, owner_id, folder_id. Per ottenere l’oggetto correlato nella stessa risposta, usa expand[].

I parametri di percorso che accettano un ID hanno nomi dello stesso tipo: {card_id}, {webhook_id}, {upload_id}.

Raccolte per ID

Le raccolte hanno sia un id sia un name univoco, come support. I percorsi che esistevano prima che si preferissero gli ID accettano il nome della raccolta:

GET /v1/collections/support/stats

Gli stessi percorsi accettano anche l’ID, scritto come id:<number>:

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

Nel codice nuovo preferisci la forma id:: un amministratore può rinominare una raccolta, ma il suo ID resta lo stesso. Un segmento di sole cifre, come /v1/collections/3, indica ancora la raccolta con il nome 3. Il nome di una raccolta non può contenere :, quindi le due forme non si confondono mai.

Nei corpi delle richieste e nei parametri di query, collection_id si affianca al precedente collection (il nome). Se li passi entrambi, prevale collection_id. Un collection_id che non esiste nell’organizzazione, o che la chiave non può vedere, restituisce 404 con il codice collections.not_found.

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

I tuoi ID

Le schede possono portare l’ID del record da cui provengono nel tuo sistema, in external_id: fino a 512 caratteri, univoco tra le schede dell’organizzazione. Così non devi mai conservare l’ID di Sursa di una scheda:

Endpoint	Cosa fa
`PUT /v1/cards-by-external-id/{external_id}`	Crea la scheda, oppure ne sostituisce il contenuto se esiste.
`GET /v1/cards-by-external-id/{external_id}`	Legge la scheda.
`GET /v1/cards?external_id=…`	Trova la scheda in un elenco, insieme ad altri filtri.

Codifica per URL l’external_id quando fa parte del percorso: crm/A-1042 diventa crm%2FA-1042.

I documenti di una fonte personalizzata hanno un proprio external_id all’interno della loro fonte. I due non si sovrappongono: una scheda di una fonte personalizzata si modifica inviando di nuovo il documento alla sua fonte, non con PUT /v1/cards-by-external-id/…, che in quel caso risponde 409 con il codice cards.managed_by_source.