Metaduomenys

metadata – jūsų pačių rakto ir reikšmės porų rinkinys objekte: įrašo ID jūsų CRM sistemoje, už jį atsakinga komanda, jį įrašiusios sinchronizacijos paleidimas. Sursa juos saugo, grąžina kartu su objektu ir įvykiuose ir leidžia pagal juos filtruoti kortelių, rinkinių ir aplankų sąrašus. Jokiu būdu jų neinterpretuoja.

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

Objektai su metadata: kortelės, rinkiniai ir aplankai. metadata turi ir pasirinktinio šaltinio dokumentas; jie tampa dokumento kortelės metadata.

Limitai

Užklausa, viršijanti limitą, grąžina 400 su kodu api.metadata_invalid. error.details.key nurodo raktą, o error.details.reason – kas negerai: too_many_keys, key_invalid, value_too_long, too_large arba value_invalid (reikšmė nėra eilutė).

Reikšmės yra eilutės. Skaičius ir datas taip pat saugokite kaip eilutes, pavyzdžiui, "2026-10-24".

Metaduomenų nustatymas

Kai kuriate arba pakeičiate objektą (POST, PUT), metadata nustatomi visi iš karto:

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 užklausoje, pavyzdžiui, įkeliant failą, metadata siųskite kaip formos lauką, kurio reikšmė yra JSON objektas: metadata={"crm_id":"A-1042"}.

Metaduomenų atnaujinimas

PATCH sulieja jūsų siunčiamus raktus su esamais. Raktas su reikšme "" arba null pašalinamas; raktai, kurių nesiunčiate, lieka tokie, kokie yra:

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": {} nieko nekeičia. Kad pašalintumėte visas poras, kiekvieną raktą siųskite su null.

Filtravimas pagal metaduomenis

Šie sąrašai priima metadata[<key>]=<value>:

• kortelės: GET /v1/cards ir GET /v1/cards/count;
• rinkiniai: GET /v1/collections;
• aplankai: GET /v1/folders ir GET /v1/collections/{name}/folders.

Reikšmė turi sutapti tiksliai. Galite derinti iki 3 sąlygų, ir objektas turi atitikti jas visas:

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"

Su filtru aplankų medis grąžinamas kaip plokščias sąrašas: kiekvieno rinkinio folders yra atitinkantys aplankai su tuščiu children, o parent_id rodo, kur kiekvienas iš jų yra. Tada GET /v1/folders praleidžia rinkinius be atitinkančių aplankų. Daugiau nei 3 sąlygos arba netinkamas raktas grąžina 400 su kodu api.metadata_invalid.

Kas metaduomenys nėra

• Tai ne turinys. Paieška ir asistento atsakymai jų nenaudoja. Tai, ką žmonės turėtų rasti, rašykite kortelės tekste, pavadinime ar žymose.
• Tai ne privatūs duomenys. Kiekvienas, kas mato objektą, mato ir jo metaduomenis. Niekada nesaugokite juose paslapčių, žetonų ar asmens duomenų, kurių objekto skaitytojai neturėtų matyti.
• Tai ne external_id pakaitalas. Kad rastumėte kortelę pagal savo įrašo ID, suteikite kortelei external_id: jis unikalus, o metaduomenų reikšmės – ne.