Expansão de objetos relacionados

Os objetos se referem a objetos relacionados pelo ID: um cartão tem owner_id e collection_id. Quando você precisa do próprio objeto relacionado, não é necessário fazer uma segunda requisição. Peça-o com expand[], e ele vem na mesma resposta, dentro de expanded:

curl -G https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "expand[]=owner" \
  --data-urlencode "expand[]=collection"

{
  "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60",
  "title": "Refund policy",
  "owner_id": 7,
  "collection_id": 3,
  "expanded": {
    "owner": {"id": 7, "username": "anna", "display_name": "Anna Petrova", "role": "editor"},
    "collection": {"id": 3, "name": "support", "title": "Support"}
  }
}

O exemplo está resumido: um objeto expandido tem todos os campos da própria operação de leitura dele. Os campos de ID continuam onde estão, então um código que não usa expand[] recebe a mesma resposta de antes.

Estas operações expandem objetos relacionados. Um caminho com ponto expande um vínculo do objeto expandido: por exemplo, collection.default_owner é o responsável padrão da coleção do cartão.

Operação	Caminhos
`GET /v1/cards/{card_id}`, `GET /v1/cards-by-external-id/{external_id}`	`collection`, `owner`, `verifiers`, `folders`, `collection.default_owner`
`GET /v1/cards`	`data.collection`, `data.owner`, `data.verifiers`, `data.folders`
`GET /v1/jobs/{job_id}`	`card`, `card.collection`, `card.owner`, `card.verifiers`, `card.folders`
`GET /v1/jobs`	`data.card`
`GET /v1/webhooks/{webhook_id}/deliveries/{delivery_id}`	`event`
`GET /v1/webhooks/{webhook_id}/deliveries`	`data.event`
`GET /v1/push/sources/{source_id}/documents/{external_id}`	`card`, `card.collection`, `card.owner`, `card.verifiers`, `card.folders`
`GET /v1/push/sources/{source_id}/syncs/{sync_number}/documents`	`data.card`

Cada vínculo vem na forma da operação que lê o objeto relacionado:

Vínculo	O que vem em `expanded`
`collection`	A coleção, como em `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	O usuário, como em `GET /v1/users`: o item completo para quem faz a chamada e pode gerenciar usuários, o item resumido (`brief=true`, só usuários ativos) para os demais. `verifiers` é uma lista na ordem de `verifier_ids`.
`folders`	As pastas do cartão na coleção dele que quem faz a chamada pode ver, como em `GET /v1/folders/{folder_id}` sem `path`.
`card`	O cartão, como um item de `GET /v1/cards`.
`event`	O evento, como em `GET /v1/webhook-events/{event_id}`.

Em listas

Em uma lista, comece o caminho com data.: ele vale para cada item da página. É assim tanto para uma lista que retorna um array, como GET /v1/cards, quanto para uma lista que guarda os itens em um campo, como jobs de GET /v1/jobs ou items do registro de entregas.

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "expand[]=data.owner" \
  --data-urlencode "expand[]=data.collection"

O Sursa carrega cada vínculo de uma vez para a página inteira, então expandir uma lista custa mais ou menos o mesmo que uma requisição a mais, e não uma por item. O cursor da próxima página não depende de expand[], então você pode pedir outros vínculos na próxima página.

Regras

Até 10 caminhos por requisição, cada um com no máximo 2 segmentos: data.owner em uma lista, collection.default_owner em um objeto.
Um caminho desconhecido, mais de 10 caminhos ou um caminho com mais de 2 segmentos retorna 400 com o código api.expand_invalid. details.path indica o caminho, e details.reason diz o que está errado: unknown_path, too_deep ou too_many_paths.
Um objeto relacionado só é expandido para quem poderia lê-lo com uma requisição própria. A chave precisa do escopo dessa operação: cards:read para cartões, coleções e pastas, users:read para usuários, webhooks:manage para eventos. O objeto também precisa estar visível para quem faz a chamada, por exemplo dentro das coleções de uma chave limitada a algumas coleções. Caso contrário, o vínculo é expandido como null, e em verifiers aparece null no lugar do usuário. O ID dele continua sendo retornado. folders lista só as pastas que quem faz a chamada pode ver.
Uma chave de fonte personalizada não lê cartões, então com ela o card de um documento é sempre null. Para obter o cartão, chame a API de envio com uma chave de API que tenha os escopos import:write e cards:read.
Um evento com mais de 30 dias e o evento de uma entrega de teste são expandidos como null.
expand[] só acrescenta dados à resposta. Nunca muda o que a requisição faz.