Μεταδεδομένα

Το metadata είναι ένα σύνολο δικών σας ζευγών κλειδιού–τιμής σε ένα αντικείμενο: το ID της εγγραφής στο CRM σας, η ομάδα που είναι υπεύθυνη γι’ αυτό, η εκτέλεση του συγχρονισμού που το έγραψε. Η Sursa τα αποθηκεύει, τα επιστρέφει μαζί με το αντικείμενο και στα συμβάντα και σας επιτρέπει να φιλτράρετε με βάση αυτά τις λίστες καρτών, συλλογών και φακέλων. Δεν τα ερμηνεύει με κανέναν τρόπο.

{
  "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60",
  "title": "Refund policy",
  "metadata": {"crm_id": "A-1042", "team": "support"}
}

Αντικείμενα με metadata: κάρτες, συλλογές και φάκελοι. Ένα έγγραφο μιας προσαρμοσμένης πηγής φέρει επίσης metadata· αυτό γίνεται το metadata της κάρτας του εγγράφου.

Όρια

Ένα αίτημα που παραβιάζει ένα όριο επιστρέφει 400 με τον κωδικό api.metadata_invalid. Το error.details.key κατονομάζει το κλειδί και το error.details.reason λέει τι είναι λάθος: too_many_keys, key_invalid, value_too_long, too_large ή value_invalid (η τιμή δεν είναι συμβολοσειρά).

Οι τιμές είναι συμβολοσειρές. Αποθηκεύετε και τους αριθμούς και τις ημερομηνίες ως συμβολοσειρές, για παράδειγμα "2026-10-24".

Ορισμός μεταδεδομένων

Όταν δημιουργείτε ή αντικαθιστάτε ένα αντικείμενο (POST, PUT), το metadata ορίζεται ως σύνολο:

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refund policy",
    "body": "Refunds are processed within 14 days.",
    "metadata": {"crm_id": "A-1042", "team": "support"}
  }'

Σε ένα αίτημα multipart/form-data, όπως μια μεταφόρτωση αρχείου, στείλτε το metadata ως πεδίο φόρμας με τιμή το αντικείμενο JSON: metadata={"crm_id":"A-1042"}.

Ενημέρωση μεταδεδομένων

Το PATCH συγχωνεύει τα κλειδιά που στέλνετε με τα υπάρχοντα. Ένα κλειδί με τιμή "" ή null αφαιρείται· τα κλειδιά που δεν στέλνετε μένουν όπως είναι:

curl -X PATCH https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"team": "billing", "legacy_flag": null}}'

{"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "metadata": {"crm_id": "A-1042", "team": "billing"}}

Το "metadata": {} δεν αλλάζει τίποτα. Για να αφαιρέσετε όλα τα ζεύγη, στείλτε κάθε κλειδί με null.

Φιλτράρισμα με βάση τα μεταδεδομένα

Αυτές οι λίστες δέχονται metadata[<key>]=<value>:

• κάρτες: GET /v1/cards και GET /v1/cards/count·
• συλλογές: GET /v1/collections·
• φάκελοι: GET /v1/folders και GET /v1/collections/{name}/folders.

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

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "metadata[team]=support" \
  --data-urlencode "metadata[crm_id]=A-1042"

Με φίλτρο, ένα δέντρο φακέλων έρχεται ως επίπεδη λίστα: το folders κάθε συλλογής περιέχει τους φακέλους που ταιριάζουν με κενό children και το parent_id δείχνει πού βρίσκεται ο καθένας. Το GET /v1/folders τότε παραλείπει τις συλλογές χωρίς φακέλους που ταιριάζουν. Περισσότερες από 3 συνθήκες ή ένα μη έγκυρο κλειδί επιστρέφουν 400 με τον κωδικό api.metadata_invalid.

Τι δεν είναι τα μεταδεδομένα

• Δεν είναι περιεχόμενο. Η αναζήτηση και οι απαντήσεις του Βοηθού AI δεν τα χρησιμοποιούν. Ό,τι πρέπει να βρίσκουν οι άνθρωποι, βάλτε το στο κείμενο της κάρτας, στον τίτλο της ή στις ετικέτες της.
• Δεν είναι ιδιωτικά. Όποιος βλέπει το αντικείμενο βλέπει και τα μεταδεδομένα του. Μην αποθηκεύετε ποτέ μυστικά, διακριτικά ή προσωπικά δεδομένα που δεν πρέπει να βλέπουν οι αναγνώστες του αντικειμένου.
• Δεν υποκαθιστούν το external_id. Για να βρίσκετε μια κάρτα με βάση το ID της εγγραφής σας, δώστε στην κάρτα ένα external_id· αυτό είναι μοναδικό, ενώ οι τιμές των μεταδεδομένων όχι.