Guia da API de Registos

Um Registo é o registo digital de um item físico — um ativo, uma peça, um documento ou um item de fluxo de trabalho. Contém um nome e uma descrição, dados de campos tipificados, ficheiros anexados, identificadores vinculados e um histórico de eventos. Os Registos pertencem a uma Equipa, pelo que cada pedido requer um bearer token e o cabeçalho Dust-Ctx-Org-Id (e Dust-Ctx-Team-Id para atuar como uma Equipa específica) — consulte Autenticação e Convenções.

Este guia aborda os principais fluxos. Para todos os parâmetros e esquemas de resposta, consulte a referência da API.

Resumo dos endpoints

Operação	Método e caminho
Criar um ou vários Registos	`POST /api/v1/threads`
Listar / pesquisar Registos	`GET /api/v1/threads`
Contar Registos	`GET /api/v1/threads/count`
Obter um Registo	`GET /api/v1/threads/{thread_id}`
Atualizar metadados e campos	`POST /api/v1/threads/{thread_id}`
Atualizar apenas campos	`POST /api/v1/threads/{thread_id}/data`
Listar dados de campos arquivados	`GET /api/v1/threads/{thread_id}/data/archived`
Restaurar dados de campos arquivados	`POST /api/v1/threads/{thread_id}/data/restore`
Arquivar Registos	`PATCH /api/v1/threads/archive`
Restaurar Registos	`PATCH /api/v1/threads/restore`
Verificar as permissões do autor do pedido	`POST /api/v1/threads/permissions`
Sinal de presença	`POST /api/v1/threads/{thread_id}/presence`
Listar os ficheiros de um Registo	`GET /api/v1/threads/{thread_id}/files`
Definir / carregar a miniatura	`PATCH` / `POST /api/v1/threads/{thread_id}/thumbnail`

As atualizações de miniaturas aceitam um resourceId autorizado ou um imageUri inline de uma imagem raster em base64, com um tamanho máximo de 5 MiB após descodificação. Os URLs de imagens remotas são rejeitados. O carregamento de ficheiros continua disponível através do endpoint de carregamento de miniaturas. As miniaturas baseadas em Recursos seguem as permissões de leitura atuais do Recurso de origem: as respostas devolvem null tanto para thumbnail como para thumbnailId quando o acesso é negado ou a origem já não está anexada. As miniaturas carregadas sem um Recurso de origem seguem a visibilidade do Registo.

Criar um Registo

POST /api/v1/threads aceita três formatos de corpo, selecionados por type: single (um Registo), list (vários Registos normalizados) e raw (registos simples de pares chave-valor). Os três aceitam um bundleId opcional para criar os Registos dentro de uma Pasta.

curl
TypeScript

curl -fsS "$APID_URL/api/v1/threads" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "single",
    "thread": { "name": "Tire SZ3J-11-ZJ17" },
    "data": [
      { "name": "Serial Number", "type": "text", "value": { "text": "SZ3J-11-ZJ17" } },
      { "name": "Max PSI", "type": "number", "value": { "number": 51 } }
    ]
  }'

const created = await client.threads.create({
  type: "single",
  thread: { name: "Tire SZ3J-11-ZJ17" },
  data: [
    { name: "Serial Number", type: "text", value: { text: "SZ3J-11-ZJ17" } },
    { name: "Max PSI", type: "number", value: { number: 51 } },
  ],
});

Os valores dos campos são aninhados em value de acordo com o tipo — { "text": … }, { "number": … } e assim por diante. A especificação define dados de entrada para texto, texto longo, número, booleano, data, intervalo de datas, data e hora, hora, duração, email, telefone, URL, JSON, seleção, seleção múltipla, etiquetas, referências a recursos (ficheiros) e referências a registos.

Importação em massa

Utilize type: "list" quando já tiver objetos { thread, data } normalizados ou type: "raw" para fornecer à API registos simples — os campos são derivados dos pares chave-valor de cada objeto, utilizando nameKey e descriptionKey (por predefinição, name / description) para os metadados do próprio Registo:

{
  "type": "raw",
  "nameKey": "serial",
  "raw": [
    { "serial": "SZ3J-11-ZJ17", "part": "P355/30R19", "maxPsi": 51 }
  ]
}

Para importar atomicamente estruturas de conjuntos completas, consulte POST /api/v1/imports/plan e POST /api/v1/imports/commit na referência.

Consultar Registos

GET /api/v1/threads/{thread_id} devolve o Registo com os respetivos dados de campos (uma consulta maxEvents opcional inclui eventos recentes). GET /api/v1/threads apresenta uma lista com paginação por cursor (cursor, pageSize, order, orderCol) e suporta filtros, incluindo:

Filtro	Significado
`q`, `queryCol`	Pesquisa de texto, opcionalmente limitada a uma coluna
`bundleId`	Registos numa Pasta ou Categoria
`templateId`	Registos criados a partir de um Modelo
`tagType`	Registos com um identificador deste tipo vinculado
`hasResources`	Registos com ficheiros anexados
`includeArchived`, `archivedOnly`	Visibilidade dos arquivos
`createdBy`, `ownedByTeam`	Filtros de proveniência
`excludeTransferred`, `transferredOnly`	Registos enviados para outro local
`withActiveShipment`	Anotar cada item com o respetivo Envio ativo, caso exista

GET /api/v1/threads/count aceita os mesmos filtros e devolve apenas a contagem — útil para painéis e resumos de paginação.

Atualizar um Registo

Dois endpoints, cada um com uma finalidade distinta:

POST /api/v1/threads/{thread_id} — aceita { thread, update?, remove? }: metadados do Registo (nome, descrição, modelo, …) e alterações opcionais aos campos numa única chamada.
POST /api/v1/threads/{thread_id}/data — apenas campos: { threadId, update, remove?, expectedUpdatedAt? }. É efetuado um upsert dos campos em update (com correspondência por nome/ID); remove aceita IDs de campos.

{
  "threadId": "9f6a…",
  "update": [
    { "name": "VIN", "type": "text", "value": { "text": "1HGCM82633A004352" } }
  ],
  "remove": []
}

Dados de campos arquivados

A remoção de um campo arquiva-o, em vez de o destruir. GET /api/v1/threads/{thread_id}/data/archived lista os campos arquivados e POST /api/v1/threads/{thread_id}/data/restore restaura-os por ID ({ threadId, restore: ["field-id", …] }).

Arquivar e restaurar Registos

O arquivamento é efetuado em massa e é reversível:

PATCH /api/v1/threads/archive — { threadIds: […], toggle? }. Com toggle: true, os Registos arquivados da lista são desarquivados e os ativos são arquivados numa única chamada.
PATCH /api/v1/threads/restore — restaurar Registos arquivados.

Os Registos arquivados desaparecem das listagens predefinidas; utilize includeArchived ou archivedOnly para os ver.

Permissões

Antes de apresentar controlos de edição ou tentar efetuar operações de escrita em vários Registos, determine o que o autor do pedido pode efetivamente fazer:

curl -fsS "$APID_URL/api/v1/threads/permissions" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{ "threadIds": ["9f6a…", "c2d1…"] }'

POST /api/v1/threads/permissions devolve as permissões efetivas do autor do pedido para cada Registo no contexto da Equipa atual. Consultas relacionadas: GET /api/v1/threads/{thread_id}/access (quais as Equipas que concedem acesso) e GET /api/v1/threads/{thread_id}/shared (com quem o Registo é partilhado) — ambas abordadas em Equipas, partilha e ligações.

Presença

POST /api/v1/threads/{thread_id}/presence é um sinal de presença: envie-o periodicamente enquanto um utilizador visualiza um Registo (opcionalmente com name / image de apresentação e leaving: true ao sair) e a resposta lista os utilizadores que estão atualmente a visualizar o Registo. O DICE utiliza esta funcionalidade para o indicador «quem mais está aqui».

Ficheiros e miniaturas

Os ficheiros são anexados aos Registos através da API de Ficheiros; as consultas do lado do Registo encontram-se aqui:

GET /api/v1/threads/{thread_id}/files — os ficheiros do Registo, com paginação por cursor (includeArchived é obrigatório).
GET /api/v1/threads/{thread_id}/files/{res_id} / POST …/files/{res_id} — consultar e atualizar um único ficheiro anexado.
POST /api/v1/threads/{thread_id}/thumbnail — carregar uma imagem (multipart, campo thumbnail) e defini-la como miniatura do Registo num único passo.
PATCH /api/v1/threads/{thread_id}/thumbnail — definir a miniatura a partir de um ID de recurso existente ou de um URI de imagem.

Modelo principal — como os Registos se relacionam com todos os outros elementos
Guia da API de Identificadores — vincular identificadores físicos a Registos
Guia da API de Ficheiros — carregamentos e transferências
Referência da API — esquemas completos de todos os endpoints acima

Comunicar um problema na documentação