Metapodaci

metadata je skup vaših vlastitih parova ključ–vrijednost na objektu: ID zapisa u vašem CRM-u, tim koji je vlasnik objekta, pokretanje sinkronizacije koje ga je zapisalo. Sursa ih pohranjuje, vraća ih s objektom i u događajima te omogućuje filtriranje popisa kartica, zbirki i mapa prema njima. Ni na koji ih način ne tumači.

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

Objekti s poljem metadata: kartice, zbirke i mape. I dokument vlastitog izvora nosi metadata; ti metapodaci postaju metadata kartice dokumenta.

Ograničenja

Zahtjev koji krši ograničenje vraća 400 s kodom api.metadata_invalid. error.details.key navodi ključ, a error.details.reason kaže što nije u redu: too_many_keys, key_invalid, value_too_long, too_large ili value_invalid (vrijednost nije niz znakova).

Vrijednosti su nizovi znakova. I brojeve i datume pohranjujte kao nizove znakova, na primjer "2026-10-24".

Postavljanje metapodataka

Kad stvarate ili zamjenjujete objekt (POST, PUT), metadata se postavlja u cjelini:

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

U zahtjevu multipart/form-data, primjerice pri učitavanju datoteke, pošaljite metadata kao polje obrasca čija je vrijednost JSON objekt: metadata={"crm_id":"A-1042"}.

Ažuriranje metapodataka

PATCH spaja ključeve koje pošaljete s postojećima. Ključ s vrijednošću "" ili null uklanja se; ključevi koje ne pošaljete ostaju nepromijenjeni:

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": {} ne mijenja ništa. Da biste uklonili sve parove, pošaljite svaki ključ s vrijednošću null.

Filtriranje prema metapodacima

Ovi popisi prihvaćaju metadata[<key>]=<value>:

• kartice: GET /v1/cards i GET /v1/cards/count;
• zbirke: GET /v1/collections;
• mape: GET /v1/folders i GET /v1/collections/{name}/folders.

Vrijednost se mora točno podudarati. Možete kombinirati do 3 uvjeta, a objekt mora zadovoljiti sve:

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"

S filtrom stablo mapa stiže kao ravan popis: folders svake zbirke sadrži odgovarajuće mape s praznim children, a parent_id pokazuje gdje se svaka od njih nalazi. GET /v1/folders tada izostavlja zbirke bez odgovarajućih mapa. Više od 3 uvjeta ili nevaljan ključ vraća 400 s kodom api.metadata_invalid.

Što metapodaci nisu

• Nisu sadržaj. Pretraživanje i odgovori asistenta ne koriste ih. Ono što ljudi trebaju pronaći stavite u tekst kartice, njezin naslov ili oznake.
• Nisu privatni. Svatko tko vidi objekt vidi i njegove metapodatke. Nikada ne pohranjujte tajne, tokene ni osobne podatke koje čitatelji objekta ne bi smjeli vidjeti.
• Nisu zamjena za external_id. Da biste karticu pronašli prema ID-u svojeg zapisa, dodijelite kartici external_id; on je jedinstven, a vrijednosti metapodataka nisu.