Метаданни

metadata е набор от ваши собствени двойки ключ–стойност върху обект: ID на записа във вашата CRM система, екипът, който отговаря за него, изпълнението на синхронизацията, което го е записало. Sursa ги съхранява, връща ги заедно с обекта и в събитията и ви позволява да филтрирате по тях списъците на карти, колекции и папки. Sursa по никакъв начин не ги тълкува.

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

Обекти с metadata: карти, колекции и папки. Документ на собствен източник също носи metadata; те стават metadata на картата на документа.

Лимити

Заявка, която нарушава лимит, връща 400 с кода api.metadata_invalid. error.details.key посочва ключа, а error.details.reason казва какво не е наред: too_many_keys, key_invalid, value_too_long, too_large или value_invalid (стойността не е низ).

Стойностите са низове. Съхранявайте и числата, и датите като низове, например "2026-10-24".

Задаване на метаданни

Когато създавате или заменяте обект (POST, PUT), metadata се задава изцяло:

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, например при качване на файл, изпратете metadata като поле на формуляра, чиято стойност е JSON обектът: metadata={"crm_id":"A-1042"}.

Актуализиране на метаданни

PATCH слива изпратените ключове със съществуващите. Ключ със стойност "" или null се премахва; ключовете, които не изпращате, остават както са:

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": {} не променя нищо. За да премахнете всички двойки, изпратете всеки ключ с null.

Филтриране по метаданни

Тези списъци приемат metadata[<key>]=<value>:

• карти: GET /v1/cards и GET /v1/cards/count;
• колекции: GET /v1/collections;
• папки: GET /v1/folders и GET /v1/collections/{name}/folders.

Условието съвпада точно със стойността. Може да комбинирате до 3 условия и обектът трябва да отговаря на всички:

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"

С филтър дървото на папките идва като плосък списък: folders на всяка колекция съдържа съвпадащите папки с празен children, а parent_id показва къде се намира всяка от тях. Тогава GET /v1/folders пропуска колекциите без съвпадащи папки. Повече от 3 условия или невалиден ключ връщат 400 с кода api.metadata_invalid.

Какво не са метаданните

• Не са съдържание. Търсенето и отговорите на асистента не ги използват. Поставете онова, което хората трябва да намират, в текста на картата, в заглавието ѝ или в етикетите ѝ.
• Не са лични. Всеки, който вижда обекта, вижда и метаданните му. Никога не съхранявайте в тях тайни, токени или лични данни, които читателите на обекта не бива да виждат.
• Не заместват external_id. За да намирате карта по ID на вашия запис, задайте на картата external_id; той е уникален, а стойностите на метаданните – не.