Metadate

metadata este un set de perechi cheie–valoare proprii pe un obiect: identificatorul înregistrării din CRM, echipa responsabilă, rularea sincronizării care l-a scris. Sursa le stochează, le returnează împreună cu obiectul și în evenimente și vă permite să filtrați după ele listele de fișe, colecții și dosare. Nu le interpretează în niciun fel.

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

Obiectele cu metadata: fișele, colecțiile și dosarele. Un document al unei surse personalizate are și el metadata; acestea devin metadata ale fișei documentului.

Limite

O cerere care încalcă o limită returnează 400 cu codul api.metadata_invalid. error.details.key numește cheia, iar error.details.reason spune ce nu este în regulă: too_many_keys, key_invalid, value_too_long, too_large sau value_invalid (valoarea nu este un șir).

Valorile sunt șiruri. Stocați și numerele, și datele calendaristice tot ca șiruri, de exemplu "2026-10-24".

Setarea metadatelor

Când creați sau înlocuiți un obiect (POST, PUT), metadata se setează în întregime:

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

Într-o cerere multipart/form-data, de exemplu la încărcarea unui fișier, trimiteți metadata ca un câmp de formular a cărui valoare este obiectul JSON: metadata={"crm_id":"A-1042"}.

Actualizarea metadatelor

PATCH combină cheile trimise cu cele existente. O cheie cu valoarea "" sau null este eliminată; cheile pe care nu le trimiteți rămân așa cum sunt:

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": {} nu schimbă nimic. Pentru a elimina toate perechile, trimiteți fiecare cheie cu null.

Filtrarea după metadate

Aceste liste acceptă metadata[<key>]=<value>:

• fișele: GET /v1/cards și GET /v1/cards/count;
• colecțiile: GET /v1/collections;
• dosarele: GET /v1/folders și GET /v1/collections/{name}/folders.

Valoarea trebuie să coincidă exact. Puteți combina cel mult 3 condiții, iar un obiect trebuie să le îndeplinească pe toate:

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"

Cu un filtru, un arbore de dosare vine ca listă simplă: folders din fiecare colecție conține dosarele potrivite, cu children goale, iar parent_id arată unde se află fiecare. În acest caz, GET /v1/folders omite colecțiile fără dosare potrivite. Mai mult de 3 condiții sau o cheie invalidă returnează 400 cu codul api.metadata_invalid.

Ce nu sunt metadatele

• Nu sunt conținut. Căutarea și răspunsurile asistentului nu le folosesc. Ce trebuie să găsească utilizatorii puneți în textul fișei, în titlul ei sau în etichetele ei.
• Nu sunt private. Oricine poate vedea obiectul îi poate vedea și metadatele. Nu stocați niciodată secrete, tokenuri sau date personale pe care cititorii obiectului nu ar trebui să le vadă.
• Nu înlocuiesc external_id. Pentru a găsi o fișă după identificatorul înregistrării proprii, dați fișei un external_id; acesta este unic, pe când valorile metadatelor nu sunt.