Metaadatok

A metadata saját kulcs–érték párok halmaza egy objektumon: a rekord azonosítója a CRM-edben, a felelős csapat, a szinkronizálási futás, amely írta. A Sursa tárolja, visszaadja az objektummal és az eseményekben, és lehetővé teszi, hogy szerinte szűrd a kártyák, a gyűjtemények és a mappák listáit. Semmilyen módon nem értelmezi.

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

metadata mezővel rendelkező objektumok: kártyák, gyűjtemények és mappák. Egy egyéni forrás dokumentuma is hordoz metadata mezőt; ebből lesz a dokumentum kártyájának metadata mezője.

Korlátok

A korlátot megsértő kérésre a válasz 400 az api.metadata_invalid kóddal. Az error.details.key megnevezi a kulcsot, az error.details.reason pedig megmondja, mi a hiba: too_many_keys, key_invalid, value_too_long, too_large vagy value_invalid (az érték nem karakterlánc).

Az értékek karakterláncok. A számokat és a dátumokat is karakterláncként tárold, például "2026-10-24".

Metaadatok megadása

Amikor létrehozol vagy lecserélsz egy objektumot (POST, PUT), a metadata egészében beállítódik:

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 kérésben, például fájlfeltöltéskor, a metadata értékét olyan űrlapmezőként küldd, amelynek az értéke a JSON-objektum: metadata={"crm_id":"A-1042"}.

Metaadatok frissítése

A PATCH az elküldött kulcsokat összefésüli a meglévőkkel. A "" vagy null értékű kulcs törlődik; az el nem küldött kulcsok változatlanok maradnak:

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

A "metadata": {} semmit nem változtat. Az összes pár törléséhez minden kulcsot küldj el null értékkel.

Szűrés metaadatok szerint

Ezek a listák elfogadják a metadata[<key>]=<value> paramétert:

• kártyák: GET /v1/cards és GET /v1/cards/count;
• gyűjtemények: GET /v1/collections;
• mappák: GET /v1/folders és GET /v1/collections/{name}/folders.

A paraméter pontos egyezést vizsgál. Legfeljebb 3 feltételt kombinálhatsz, és az objektumnak mindegyiknek meg kell felelnie:

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"

Szűréskor a mappafa lapos listaként érkezik: minden gyűjtemény folders mezője az egyező mappákat tartalmazza üres children mezővel, a parent_id pedig megmutatja, hol helyezkedik el az egyes mappa. A GET /v1/folders ilyenkor kihagyja azokat a gyűjteményeket, amelyekben nincs egyező mappa. 3-nál több feltétel vagy érvénytelen kulcs esetén a válasz 400 az api.metadata_invalid kóddal.

Mi nem a metaadat

• Nem tartalom. A keresés és az asszisztens válaszai nem használják. Amit a felhasználóknak meg kell találniuk, azt a kártya szövegébe, címébe vagy címkéibe írd.
• Nem titkos. Aki látja az objektumot, a metaadatait is látja. Soha ne tárolj benne titkos kulcsokat, tokeneket vagy olyan személyes adatokat, amelyeket az objektum olvasói nem láthatnak.
• Nem helyettesíti az external_id mezőt. Ha a rekordod azonosítója alapján szeretnél megtalálni egy kártyát, adj a kártyának external_id értéket; az egyedi, a metaadatok értékei viszont nem.