Metaandmed

metadata on teie enda võtme-väärtuse paaride kogum objektil: kirje ID teie CRM-is, objekti eest vastutav meeskond, sünkroonimise käivitus, mis objekti kirjutas. Sursa salvestab selle, tagastab selle koos objektiga ja sündmustes ning võimaldab selle järgi filtreerida kaartide, kogude ja kaustade loendeid. Sursa ei tõlgenda seda kuidagi.

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

Välja metadata toetavad kaardid, kogud ja kaustad. Ka kohandatud allika dokumendil on metadata; sellest saab dokumendi kaardi metadata.

Piirangud

Päring, mis rikub piirangut, tagastab 400 koodiga api.metadata_invalid. error.details.key nimetab võtme ja error.details.reason ütleb, mis on valesti: too_many_keys, key_invalid, value_too_long, too_large või value_invalid (väärtus ei ole string).

Väärtused on stringid. Salvestage ka arvud ja kuupäevad stringidena, näiteks "2026-10-24".

Metaandmete määramine

Kui loote või asendate objekti (POST, PUT), määratakse metadata tervikuna:

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"}
  }'

Päringus multipart/form-data, näiteks faili üleslaadimisel, saatke metadata vormiväljana, mille väärtus on JSON-objekt: metadata={"crm_id":"A-1042"}.

Metaandmete muutmine

PATCH liidab saadetud võtmed olemasolevatega. Võti väärtusega "" või null eemaldatakse; võtmed, mida te ei saada, jäävad samaks:

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": {} ei muuda midagi. Kõigi paaride eemaldamiseks saatke iga võti väärtusega null.

Filtreerimine metaandmete järgi

Need loendid võtavad vastu parameetri metadata[<key>]=<value>:

• kaardid: GET /v1/cards ja GET /v1/cards/count;
• kogud: GET /v1/collections;
• kaustad: GET /v1/folders ja GET /v1/collections/{name}/folders.

See sobitab väärtust täpselt. Võite kombineerida kuni 3 tingimust ja objekt peab vastama neile kõigile:

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"

Filtriga tuleb kaustapuu lameda loendina: iga kogu väli folders sisaldab sobivaid kaustu tühja väljaga children ja parent_id näitab, kus iga kaust asub. GET /v1/folders jätab siis välja kogud, milles sobivaid kaustu ei ole. Rohkem kui 3 tingimust või vigane võti tagastab 400 koodiga api.metadata_invalid.

Mida metaandmed ei ole

• Metaandmed ei ole sisu. Otsing ja assistendi vastused neid ei kasuta. Pange see, mida inimesed peaksid leidma, kaardi teksti, pealkirja või siltidesse.
• Metaandmed ei ole privaatsed. Igaüks, kes näeb objekti, näeb ka selle metaandmeid. Ärge kunagi salvestage saladusi, juurdepääsulubasid ega isikuandmeid, mida objekti lugejad ei tohiks näha.
• Metaandmed ei asenda välja external_id. Kaardi leidmiseks teie kirje ID järgi andke kaardile external_id; see on unikaalne, metaandmete väärtused aga mitte.