IDs de objetos

Todo objeto da API tem um id. Guarde-o no seu sistema quando precisar voltar ao objeto: nomes e títulos podem mudar, os IDs nunca mudam.

Objeto	`id`	Exemplo
Cartão, pasta	String	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Evento	String com o prefixo `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Upload	String com o prefixo `upl_`	`"upl_8b0c…"`
App OAuth	String com o prefixo `app_`	`"app_5f1c…"`
Coleção, usuário, grupo, chave de API, webhook, job e a maioria dos outros	Inteiro	`3`

Trate os IDs como opacos. Não os decomponha e não presuma um formato além do tipo: um ID do tipo string pode ser qualquer string, até o comprimento que o campo dele permite.

Os novos tipos de objeto aos quais você provavelmente fará referência nos seus próprios sistemas recebem IDs do tipo string com um prefixo curto que indica o tipo, seguido de 32 caracteres hexadecimais.

Referências entre objetos

Os objetos se referem uns aos outros pelo ID, em campos chamados <object>_id: collection_id, owner_id, folder_id. Para receber o objeto relacionado na mesma resposta, use expand[].

Os parâmetros de caminho que recebem um ID seguem o mesmo padrão de nome: {card_id}, {webhook_id}, {upload_id}.

Coleções pelo ID

As coleções têm um id e também um name único, como support. Os caminhos que já existiam antes de os IDs passarem a ser preferidos recebem o nome da coleção:

GET /v1/collections/support/stats

Os mesmos caminhos também aceitam o ID, escrito como id:<number>:

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

Prefira a forma id: em código novo: um administrador pode renomear uma coleção, mas o ID dela continua o mesmo. Um segmento só de dígitos, como /v1/collections/3, continua significando a coleção chamada 3. O nome de uma coleção não pode conter :, então as duas formas nunca se confundem.

Nos corpos das requisições e nos parâmetros de consulta, collection_id fica ao lado do anterior collection (o nome). Quando você passa os dois, vale collection_id. Um collection_id que não existe na organização, ou que a chave não tem permissão para ver, retorna 404 com o código collections.not_found.

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

Seus próprios IDs

Os cartões podem trazer, em external_id, o ID do registro de origem no seu sistema: até 512 caracteres, único entre os cartões da organização. Com ele, você nunca precisa guardar o ID de um cartão no Sursa:

Endpoint	O que faz
`PUT /v1/cards-by-external-id/{external_id}`	Cria o cartão ou substitui o conteúdo dele, se já existir.
`GET /v1/cards-by-external-id/{external_id}`	Lê o cartão.
`GET /v1/cards?external_id=…`	Encontra o cartão em uma lista, com outros filtros.

Codifique o external_id para URL quando ele fizer parte do caminho: crm/A-1042 vira crm%2FA-1042.

Os documentos de uma fonte personalizada têm o próprio external_id dentro da fonte deles. Os dois não colidem: um cartão de uma fonte personalizada é alterado enviando de novo o documento para a fonte dele, e não com PUT /v1/cards-by-external-id/…, que nesse caso responde 409 com o código cards.managed_by_source.