Metadatos

metadata es un conjunto de pares clave-valor propios en un objeto: el ID del registro en su CRM, el equipo responsable, la ejecución de la sincronización que lo escribió. Sursa lo guarda, lo devuelve con el objeto y en los eventos, y le permite filtrar por él las listas de tarjetas, colecciones y carpetas. No lo interpreta de ninguna manera.

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

Objetos con metadata: tarjetas, colecciones y carpetas. Un documento de una fuente personalizada también lleva metadata, que pasa a ser el metadata de la tarjeta del documento.

Límites

Una solicitud que supera un límite devuelve 400 con el código api.metadata_invalid. error.details.key indica la clave, y error.details.reason, qué falla: too_many_keys, key_invalid, value_too_long, too_large o value_invalid (el valor no es una cadena).

Los valores son cadenas. Guarde también los números y las fechas como cadenas, por ejemplo "2026-10-24".

Establecer los metadatos

Cuando crea o sustituye un objeto (POST, PUT), metadata se establece completo:

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

En una solicitud multipart/form-data, como la subida de un archivo, envíe metadata como un campo de formulario cuyo valor es el objeto JSON: metadata={"crm_id":"A-1042"}.

Actualizar los metadatos

PATCH combina las claves que envía con las existentes. Una clave con el valor "" o null se elimina; las claves que no envía se quedan como están:

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": {} no cambia nada. Para eliminar todos los pares, envíe cada clave con null.

Filtrar por metadatos

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

• tarjetas: GET /v1/cards y GET /v1/cards/count;
• colecciones: GET /v1/collections;
• carpetas: GET /v1/folders y GET /v1/collections/{name}/folders.

Coincide con el valor exacto. Puede combinar hasta 3 condiciones, y un objeto debe cumplirlas todas:

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"

Con un filtro, un árbol de carpetas llega como una lista plana: folders de cada colección contiene las carpetas que coinciden, con children vacío, y parent_id indica dónde está cada una. En ese caso, GET /v1/folders omite las colecciones sin carpetas que coincidan. Más de 3 condiciones o una clave no válida devuelven 400 con el código api.metadata_invalid.

Lo que no son los metadatos

• No son contenido. La búsqueda y las respuestas del asistente no los usan. Ponga lo que la gente debe encontrar en el texto de la tarjeta, en su título o en sus etiquetas.
• No son privados. Todos los que pueden ver el objeto pueden ver sus metadatos. Nunca guarde secretos, tokens ni datos personales que no deban ver los lectores del objeto.
• No sustituyen a external_id. Para encontrar una tarjeta por el ID de su registro, asigne a la tarjeta un external_id; es único, mientras que los valores de los metadatos no lo son.