Αναγνωριστικά αντικειμένων

Κάθε αντικείμενο του API έχει ένα id. Αποθηκεύστε το στο σύστημά σας, όταν χρειάζεται να επιστρέψετε στο αντικείμενο: τα ονόματα και οι τίτλοι μπορεί να αλλάξουν, τα αναγνωριστικά ποτέ.

Αντικείμενο	`id`	Παράδειγμα
Κάρτα, φάκελος	Συμβολοσειρά	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Συμβάν	Συμβολοσειρά με το πρόθεμα `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Μεταφόρτωση	Συμβολοσειρά με το πρόθεμα `upl_`	`"upl_8b0c…"`
Εφαρμογή OAuth	Συμβολοσειρά με το πρόθεμα `app_`	`"app_5f1c…"`
Συλλογή, χρήστης, ομάδα, κλειδί API, webhook, εργασία και τα περισσότερα άλλα	Ακέραιος	`3`

Χειρίζεστε τα αναγνωριστικά ως αδιαφανή. Μην τα αναλύετε και μην υποθέτετε κάποια μορφή πέρα από τον τύπο: ένα αναγνωριστικό τύπου συμβολοσειράς μπορεί να είναι οποιαδήποτε συμβολοσειρά, έως το μήκος που επιτρέπει το πεδίο του.

Τα νέα είδη αντικειμένων στα οποία πιθανότατα θα παραπέμπετε από τα δικά σας συστήματα παίρνουν αναγνωριστικά τύπου συμβολοσειράς με ένα σύντομο πρόθεμα που δηλώνει το είδος, ακολουθούμενο από 32 δεκαεξαδικούς χαρακτήρες.

Αναφορές μεταξύ αντικειμένων

Τα αντικείμενα παραπέμπουν το ένα στο άλλο μέσω ID, σε πεδία με όνομα <object>_id: collection_id, owner_id, folder_id. Για να λάβετε το συσχετισμένο αντικείμενο στην ίδια απόκριση, χρησιμοποιήστε το expand[].

Οι παράμετροι διαδρομής που δέχονται ένα ID ονομάζονται με τον ίδιο τρόπο: {card_id}, {webhook_id}, {upload_id}.

Συλλογές με βάση το ID

Οι συλλογές έχουν και id και ένα μοναδικό name, όπως support. Οι διαδρομές που υπήρχαν πριν προτιμηθούν τα αναγνωριστικά δέχονται το όνομα της συλλογής:

GET /v1/collections/support/stats

Οι ίδιες διαδρομές δέχονται και το ID, γραμμένο ως id:<number>:

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

Στον νέο κώδικα προτιμήστε τη μορφή id:: ένας διαχειριστής μπορεί να μετονομάσει μια συλλογή, αλλά το ID της μένει ίδιο. Ένα τμήμα διαδρομής μόνο με ψηφία, όπως /v1/collections/3, εξακολουθεί να σημαίνει τη συλλογή με όνομα 3. Το όνομα μιας συλλογής δεν μπορεί να περιέχει :, οπότε οι δύο μορφές δεν μπερδεύονται ποτέ.

Στα σώματα αιτημάτων και στις παραμέτρους ερωτήματος, το collection_id στέκεται δίπλα στο παλαιότερο collection (το όνομα). Όταν περνάτε και τα δύο, υπερισχύει το collection_id. Ένα collection_id που δεν υπάρχει στον οργανισμό ή που το κλειδί δεν επιτρέπεται να δει επιστρέφει 404 με τον κωδικό collections.not_found.

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

Τα δικά σας αναγνωριστικά

Οι κάρτες μπορούν να φέρουν στο external_id το αναγνωριστικό της εγγραφής από την οποία προέρχονται στο σύστημά σας: έως 512 χαρακτήρες, μοναδικό ανάμεσα στις κάρτες του οργανισμού. Με αυτό δεν χρειάζεται ποτέ να αποθηκεύετε το ID μιας κάρτας στη Sursa:

Τελικό σημείο	Τι κάνει
`PUT /v1/cards-by-external-id/{external_id}`	Δημιουργεί την κάρτα ή αντικαθιστά το περιεχόμενό της, αν υπάρχει.
`GET /v1/cards-by-external-id/{external_id}`	Διαβάζει την κάρτα.
`GET /v1/cards?external_id=…`	Βρίσκει την κάρτα σε μια λίστα, μαζί με άλλα φίλτρα.

Κωδικοποιείτε το external_id για URL, όταν είναι μέρος της διαδρομής: το crm/A-1042 γίνεται crm%2FA-1042.

Τα έγγραφα μιας προσαρμοσμένης πηγής έχουν το δικό τους external_id μέσα στην πηγή τους. Τα δύο δεν συγκρούονται: μια κάρτα προσαρμοσμένης πηγής αλλάζει με εκ νέου αποστολή του εγγράφου στην πηγή του, όχι με PUT /v1/cards-by-external-id/…, που σε αυτή την περίπτωση απαντά 409 με τον κωδικό cards.managed_by_source.