ID de los objetos

Cada objeto de la API tiene un id. Guárdelo en su sistema cuando necesite volver al objeto: los nombres y los títulos pueden cambiar; los ID, nunca.

Objeto	`id`	Ejemplo
Tarjeta, carpeta	Cadena	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Evento	Cadena con el prefijo `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Subida	Cadena con el prefijo `upl_`	`"upl_8b0c…"`
Aplicación OAuth	Cadena con el prefijo `app_`	`"app_5f1c…"`
Colección, usuario, grupo, clave de API, webhook, trabajo y la mayoría de los demás	Entero	`3`

Trate los ID como opacos. No los analice ni dé por supuesto ningún formato más allá del tipo: un ID de tipo cadena puede ser cualquier cadena, hasta la longitud que permita su campo.

Los tipos de objeto nuevos a los que probablemente hará referencia desde sus propios sistemas reciben ID de tipo cadena con un prefijo corto que nombra el tipo, seguido de 32 caracteres hexadecimales.

Referencias entre objetos

Los objetos se refieren unos a otros mediante el ID, en campos con el nombre <object>_id: collection_id, owner_id, folder_id. Para obtener el objeto relacionado en la misma respuesta, use expand[].

Los parámetros de ruta que reciben un ID se nombran de la misma manera: {card_id}, {webhook_id}, {upload_id}.

Colecciones por ID

Las colecciones tienen un id y también un name único, como support. Las rutas que ya existían antes de que se diera preferencia a los ID reciben el nombre de la colección:

GET /v1/collections/support/stats

Las mismas rutas también aceptan el ID, escrito como id:<number>:

curl https://api.sursa.com/v1/collections/id:3/stats \
  -H "Authorization: Bearer $SURSA_API_KEY"

En el código nuevo, prefiera la forma id:: un administrador puede cambiar el nombre de una colección, pero su ID no cambia. Un segmento formado solo por cifras, como /v1/collections/3, sigue significando la colección llamada 3. El nombre de una colección no puede contener :, así que las dos formas nunca se confunden.

En los cuerpos de las solicitudes y en los parámetros de consulta, collection_id está junto al anterior collection (el nombre). Si pasa ambos, prevalece collection_id. Un collection_id que no existe en la organización o que la clave no tiene permiso para ver devuelve 404 con el código collections.not_found.

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "collection_id=3"

Sus propios ID

Las tarjetas pueden llevar en external_id el ID del registro de su sistema del que proceden: hasta 512 caracteres, único entre las tarjetas de la organización. Con él, nunca tiene que guardar el ID de Sursa de una tarjeta:

Endpoint	Qué hace
`PUT /v1/cards-by-external-id/{external_id}`	Crea la tarjeta o, si existe, sustituye su contenido.
`GET /v1/cards-by-external-id/{external_id}`	Lee la tarjeta.
`GET /v1/cards?external_id=…`	Busca la tarjeta en una lista, junto con otros filtros.

Codifique el external_id para URL cuando forme parte de la ruta: crm/A-1042 se convierte en crm%2FA-1042.

Los documentos de una fuente personalizada tienen su propio external_id dentro de su fuente. Los dos no chocan: una tarjeta de una fuente personalizada se cambia volviendo a enviar el documento a su fuente, no con PUT /v1/cards-by-external-id/…, que en ese caso responde 409 con el código cards.managed_by_source.