Metadados

metadata é um conjunto de pares chave-valor seus em um objeto: o ID do registro no seu CRM, a equipe responsável por ele, a execução da sincronização que o gravou. O Sursa o armazena, o retorna com o objeto e nos eventos e permite filtrar por ele as listas de cartões, coleções e pastas. Ele não o interpreta de forma alguma.

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

Objetos com metadata: cartões, coleções e pastas. Um documento de uma fonte personalizada também leva metadata, que se torna o metadata do cartão do documento.

Limites

Uma requisição que ultrapassa um limite retorna 400 com o código api.metadata_invalid. error.details.key indica a chave, e error.details.reason diz o que está errado: too_many_keys, key_invalid, value_too_long, too_large ou value_invalid (o valor não é uma string).

Os valores são strings. Guarde números e datas também como strings, por exemplo "2026-10-24".

Definição dos metadados

Quando você cria ou substitui um objeto (POST, PUT), metadata é definido por inteiro:

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

Em uma requisição multipart/form-data, como um upload de arquivo, envie metadata como um campo de formulário cujo valor é o objeto JSON: metadata={"crm_id":"A-1042"}.

Atualização dos metadados

PATCH mescla as chaves que você envia com as que já existem. Uma chave com o valor "" ou null é removida; as chaves que você não envia ficam como estão:

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": {} não altera nada. Para remover todos os pares, envie cada chave com null.

Filtro por metadados

Estas listas aceitam metadata[<key>]=<value>:

• cartões: GET /v1/cards e GET /v1/cards/count;
• coleções: GET /v1/collections;
• pastas: GET /v1/folders e GET /v1/collections/{name}/folders.

O filtro compara o valor de forma exata. Você pode combinar até 3 condições, e um objeto precisa atender a todas elas:

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"

Com um filtro, uma árvore de pastas vem como uma lista plana: folders de cada coleção traz as pastas que atendem ao filtro, com children vazio, e parent_id indica onde cada uma fica. GET /v1/folders então omite as coleções sem pastas que atendam ao filtro. Mais de 3 condições ou uma chave inválida retornam 400 com o código api.metadata_invalid.

O que os metadados não são

• Não são conteúdo. A busca e as respostas do assistente não os usam. Coloque o que as pessoas devem encontrar no texto do cartão, no título ou nas etiquetas dele.
• Não são privados. Todos que podem ver o objeto podem ver os metadados dele. Nunca guarde segredos, tokens ou dados pessoais que os leitores do objeto não devem ver.
• Não substituem o external_id. Para encontrar um cartão pelo ID do seu registro, dê ao cartão um external_id; ele é único, enquanto os valores dos metadados não são.