Modelo fundamental

A API da plataforma DUST representa fluxos de trabalho de objetos físicos como um pequeno conjunto de recursos componíveis. Um Registo é o registo digital de um item físico; tudo o resto — identificadores, ficheiros, pastas, conjuntos, partilha, envios — é associado a Registos, organiza-os ou move-os. Esta página é o mapa: uma breve secção por conceito, com os principais endpoints e uma ligação para o guia mais aprofundado.

Mapa de nomes

Alguns espaços de nomes da API são anteriores ao vocabulário atual do produto. A aplicação Web DICE e esta documentação utilizam os nomes à esquerda; os caminhos da API mantêm os nomes à direita.

Nome no DICE / na documentação	Espaço de nomes da API	Notas
Registos	/api/v1/threads	—
Identificadores	/api/v1/tags	Denominação legada tags nos caminhos
Ficheiros	/api/v1/files	Denominados recursos em alguns esquemas
Pastas e Categorias	/api/v1/bundles	Bundle é o nome de implementação
Conjuntos	/api/v1/assemblies	Os Conjuntos são Registos do tipo assembly
Equipas	/api/v1/teams	Selecionadas por pedido através do cabeçalho Dust-Ctx-Team-Id (o cabeçalho legado Dust-Ctx-Grp-Id continua a ser aceite)
Ligações	/api/v1/connections	Os esquemas transmitidos mantêm a denominação legada team link
Partilha	/api/v1/sharing	—
Envios	/api/v1/transfers	Denominação legada transfers nos caminhos
Divisões	/api/v1/slices	—
Fabric	/api/v1/fabric	Grafo de proveniência entre organizações
Certificados	/api/v1/certificates, /api/v1/certificate-forms	—
Páginas públicas	/api/v1/public-pages, /api/v1/public-page-designs	A publicação requer a concessão publisher da Equipa
Eventos	/api/v1/events	—

Cada pedido inclui um token bearer do AuthD; os endpoints no âmbito da organização — praticamente todos — acrescentam o cabeçalho Dust-Ctx-Org-Id (e, opcionalmente, Dust-Ctx-Team-Id para selecionar uma Equipa). Consulte Autenticação e Convenções. A referência completa ao nível dos parâmetros encontra-se na referência da API.

Registos

Um Registo é o registo de um ativo físico, peça, documento ou item de fluxo de trabalho: um nome e uma descrição, dados de campos tipificados, ficheiros anexados, identificadores vinculados e um histórico de eventos. Os Registos têm um kind — unidades comuns ou assembly (ver abaixo).

• POST /api/v1/threads — criar um ou vários
• GET /api/v1/threads — pesquisar e listar (paginação por cursor)
• GET /api/v1/threads/{thread_id} — obter um, com os dados dos campos
• POST /api/v1/threads/{thread_id}/data — inserir, atualizar ou remover valores de campos
• PATCH /api/v1/threads/archive / PATCH /api/v1/threads/restore — ciclo de vida de arquivo

Mais detalhes: Guia da API de Registos.

Campos e Modelos

Os valores dos campos são tipificados (text, number, date, select, referências a recursos e até campos cujo valor é um registo) e estão aninhados por tipo. Os Modelos definem os campos esperados para um tipo de Registo repetível.

• POST /api/v1/templates / GET /api/v1/templates — criar e listar modelos
• GET /api/v1/templates/{templateId} / PATCH /api/v1/templates/{templateId} — ler e atualizar

Identificadores

Um identificador vincula uma marcação física — uma etiqueta DUST, um código QR, um código de barras, um símbolo Data Matrix ou um chip NFC — a um Registo, para que uma digitalização no terreno seja resolvida para o registo digital. O espaço de nomes da API é /api/v1/tags (denominação legada).

• POST /api/v1/tags/extract — analisar uma captura DUST para obter uma impressão digital canónica sem a vincular
• POST /api/v1/tags/bind — associar um identificador a um Registo
• POST /api/v1/tags/identify — encontrar o Registo correspondente a uma digitalização
• POST /api/v1/tags/verify — confirmar que uma digitalização corresponde aos identificadores de um Registo específico
• POST /api/v1/tags/unbind — desassociar um identificador

Mais detalhes: Guia da API de Identificadores.

Ficheiros

Os Ficheiros (denominados recursos em alguns esquemas) são guardados num armazenamento de objetos e associados diretamente a Registos ou através de campos tipificados como recursos. Os carregamentos de grandes dimensões utilizam o protocolo reanudável tus; os mais pequenos utilizam um único POST multipart.

• POST /api/v1/files — carregamento multipart simples
• POST /api/v1/files/finalize — converter carregamentos tus concluídos em registos de recursos
• GET /api/v1/files/{resource_id}/download — transferir
• POST /api/v1/files/urls — URLs assinados de curta duração
• GET /api/v1/files/search — pesquisar em todos os ficheiros

Mais detalhes: Guia da API de Ficheiros.

Equipas e Organizações

A identidade reside no AuthD; a API da plataforma define o âmbito de cada pedido no âmbito da organização para uma Organização e uma Equipa através de cabeçalhos de contexto. As Equipas são proprietárias dos Registos, e a partilha, as ligações e os envios decorrem entre Equipas.

• GET /api/v1/me — utilizador atual e organizações disponíveis
• GET /api/v1/teams — Equipas visíveis para o autor da chamada
• POST /api/v1/org/teams / PATCH /api/v1/org/teams/{team_id} — gestão de Equipas (administradores da organização)
• POST /api/v1/org/teams/members — gerir membros (administradores da organização)

Mais detalhes: Equipas, partilha e ligações.

Pastas e Categorias

As Pastas e as Categorias organizam os Registos. Ambas são bundles na API — kind: "folder" para inclusão exclusiva, kind: "category" para classificação não exclusiva — e os bundles são aninhados para formar árvores.

• POST /api/v1/bundles — criar (com kind e um progenitor childOfId opcional)
• GET /api/v1/bundles / GET /api/v1/bundles/children — listar ou percorrer a árvore de forma diferida
• POST /api/v1/bundles/{bundle_id}/add / PATCH /api/v1/bundles/{bundle_id}/move — colocar Registos
• PATCH /api/v1/bundles/parent — atribuir um novo progenitor a um bundle

Conjuntos e Peças

Um Conjunto é um Registo do tipo assembly cujas Peças são outros Registos — uma estrutura de lista de materiais. As Peças podem ser protegidas contra a desassociação e as listas de peças podem ser agregadas transitivamente.

• GET /api/v1/assemblies — listar Registos de Conjuntos
• POST /api/v1/assemblies/{assembly_id}/parts / DELETE /api/v1/assemblies/{assembly_id}/parts — associar e desassociar Peças
• GET /api/v1/assemblies/{assembly_id}/rolled-up-parts — lista transitiva de peças
• PATCH /api/v1/assemblies/{assembly_id}/kind — converter um Registo entre unit e assembly
• POST /api/v1/imports/plan / POST /api/v1/imports/commit — simular e confirmar a importação de um pacote de conjunto completo

Ligações e Relações entre Registos

Os Registos podem referenciar-se entre si através de ligações tipificadas. As definições de relações atribuem nomes aos tipos de relação; as ligações entre registos são as respetivas instâncias.

• POST /api/v1/relations / GET /api/v1/relations — definir e listar tipos de relações
• POST /api/v1/links / GET /api/v1/links — criar e listar ligações entre Registos
• GET /api/v1/threads/{thread_id}/links — ligações na perspetiva de um Registo
• DELETE /api/v1/links/{link_id} — remover a ligação

Partilha

A partilha concede a outra Equipa acesso viewer ou editor a um Registo ou bundle. As concessões são armazenadas como tuplos de relações; o resumo de acesso mostra o resultado efetivo, incluindo o acesso herdado.

• POST /api/v1/sharing — partilhar Registos ou bundles com Equipas
• GET /api/v1/sharing — listar concessões (direction=in|out)
• GET /api/v1/sharing/access-summary — acesso efetivo a um objeto
• GET /api/v1/sharing/partner-inventory — tudo o que foi partilhado com uma Equipa parceira

Mais detalhes: Equipas, partilha e ligações.

Ligações

Uma Ligação (API: team link) é o acordo permanente entre duas Equipas — frequentemente de Organizações diferentes — que permite a partilha e os envios, com uma direção permitida para o fluxo de dados. Inclui uma sequência de convite, aceitação e confirmação, bem como um ciclo de vida de pausa e retoma.

• POST /api/v1/connections — criar (convidar)
• PATCH /api/v1/connections/accept / confirm / reject / cancel — sequência de estabelecimento
• PATCH /api/v1/connections/pause / resume — suspender e retomar
• POST /api/v1/connections/amend/propose — propor uma alteração de direção

Envios

Um Envio (API: transfer) transfere a propriedade de Registos de uma Equipa para outra: criar um rascunho do manifesto, enviá-lo e permitir que o destinatário o aceite, rejeite ou solicite alterações.

• POST /api/v1/transfers — criar um rascunho
• POST /api/v1/transfers/{transfer_id}/items — adicionar itens ao manifesto
• POST /api/v1/transfers/{transfer_id}/send — enviar para a Equipa destinatária
• POST /api/v1/transfers/{transfer_id}/respond — aceitar / rejeitar / solicitar alterações
• GET /api/v1/transfers — vistas da caixa de entrada, caixa de saída e itens enviados

Semântica e ciclo de vida: Envios; resumo dos endpoints em Equipas, partilha e ligações.

Divisões

Uma Divisão deriva um novo Registo de um já existente na mesma Equipa — copiando ou ligando campos, ficheiros e identificadores selecionados — normalmente para preparar um subconjunto que possa ser partilhado.

• POST /api/v1/slices — dividir um Registo
• POST /api/v1/slices/batch — derivar vários Registos de uma só vez
• GET /api/v1/slices/{slice_id} — uma Divisão com as respetivas ligações Fabric

Fabric

Fabric é a camada de proveniência entre organizações: quando os Registos são movidos ou divulgados além dos limites de uma Equipa, Fabric regista o grafo de Registos ligados e controla exatamente os dados que cada parte a jusante pode ver (divulgação), revisão a revisão.

• GET /api/v1/fabric/threads/{thread_id}/graph — o grafo de proveniência visível a partir de um Registo
• GET /api/v1/fabric/links/{link_id}/context — dados atualmente divulgados numa ligação
• POST /api/v1/fabric/threads/{thread_id}/disclosure/revise / redact — alterar o que é divulgado
• POST /api/v1/fabric/threads/{thread_id}/disclosure/push — enviar uma divulgação a jusante
• GET /api/v1/fabric/notifications — notificações de divulgação para proprietários a jusante

Conceitos: Fabric.

Certificados

Os Certificados apresentam os dados de Registos em documentos emitidos e verificáveis. Os Formulários de Certificado são os esquemas de apresentação; a geração vincula um formulário a um Registo através do nome do campo.

Um formulário pode conter várias zonas de QR Vlink. A geração de Certificados aceita uma configuração Vlink por Identificador de zona e devolve todas as associações emitidas entre zonas e Vlinks.

• POST /api/v1/certificate-forms / GET /api/v1/certificate-forms — gerir formulários
• POST /api/v1/certificates/preflight — conferir se um formulário é resolvido para um Registo
• POST /api/v1/certificates/generate — emitir um Certificado
• GET /api/v1/certificates — listar os Certificados de um Registo
• POST /api/v1/certificates/void — anular um

Conceitos: Certificados.

Páginas públicas

Uma Página pública é a vista Web não autenticada de um Registo — o passaporte digital do produto ao qual um consumidor acede ao digitalizar um Identificador. O que apresenta é determinado na íntegra por um Design de página pública reutilizável, pertencente à Equipa, pelo que a publicação não recebe conteúdo específico do Registo: ao publicar, o design é resolvido para o Registo. O URL de uma página é reservado e vinculado antes de qualquer publicação, para que as etiquetas possam ser impressas antecipadamente.

A publicação de um design fixa uma Versão do design imutável; cada página fica associada a uma Versão do design e a um Instantâneo de dados (os valores resolvidos para esse Registo). Uma Publicação em massa republica todas as páginas de um âmbito — Pasta, Categoria, Modelo ou uma seleção explícita — através de uma Versão do design, como uma execução em segundo plano com o seu próprio acompanhamento do progresso e contabilização de falhas.

Reservar o URL de uma página e vinculá-lo a um Registo são operações do nível de membro — reservar um endereço não publica nada, pelo que as etiquetas podem ser impressas antes de alguém decidir publicar. Tudo o que torna os dados públicos — publicar uma página, ativá-la ou arquivá-la, criar um design, publicar uma Versão do design, implementar e efetuar Publicações em massa — requer a concessão publisher da Equipa (que está implícita para o administrador da Equipa), tal como as verificações prévias e de pré-visualização. O x-required-role de cada operação na referência da API é a fonte autoritativa.

• POST /api/v1/public-pages / POST /api/v1/public-pages/{publicPageId}/bind — reservar um URL permanente para a página e, em seguida, vinculá-lo a um Registo
• GET / PUT /api/v1/public-pages/thread/{threadId} — ler ou obter/criar a página de um Registo
• GET /api/v1/public-pages/thread/{threadId}/activity — visualizações anónimas e digitalizações de verificação na página publicada
• POST /api/v1/public-pages/{publicPageId}/publish — publicar um instantâneo através da versão mais recente do design
• PATCH /api/v1/public-pages/{publicPageId} — ativar ou arquivar uma página sem alterar o respetivo URL
• GET /api/v1/public-pages/{publicPageId}/publications — histórico de publicações
• POST /api/v1/public-pages/preflight / preflight/batch — conferir se um design é resolvido para um ou vários Registos
• POST /api/v1/public-page-designs / GET / PATCH /api/v1/public-page-designs/{designId} — criar o rascunho de um design
• POST /api/v1/public-page-designs/{designId}/versions — publicar uma Versão do design (GET lista-as)
• POST /api/v1/public-pages/designs/{designId}/roll-out — implementar a versão mais recente de um design nas respetivas páginas
• POST /api/v1/public-pages/waves — iniciar uma Publicação em massa (GET obtém o respetivo registo de execução, itens e lista)
• POST /api/v1/public-pages/waves/{waveId}/retry-failed / cancel — voltar a tentar as operações que falharam ou interromper o trabalho restante

A implementação só avança: uma Versão do design nunca é restaurada e o cancelamento de uma publicação em massa mantém as páginas já publicadas na versão que receberam.

Conceitos: Páginas públicas.

Eventos

Todas as alterações relevantes — edições de campos, vinculações, partilhas, envios — são registadas como eventos, formando o rasto de auditoria apresentado como Registo de transações no DICE.

• GET /api/v1/events — listar eventos, filtráveis por Registo, Equipa, ação e tempo, com agrupamento opcional de atividades (groupBy)
  • lineage=upstream (com threadId) devolve também os eventos de todos os Registos anteriores na linhagem Fabric do Registo — a história completa de um Registo recebido — limitados ao que cada origem divulgou. As linhas a montante incluem um objeto lineage (Registo de origem, Equipa de origem, ligação, salto) e podem estar redacted; uma alteração posterior à divulgação por parte de uma origem surge como uma linha só de leitura fabric.disclosure.revised. Se for omitido, a resposta contém apenas os eventos do próprio Registo.
  • resourceId, tagId ou fieldId (um de cada vez, com threadId) restringem o histórico a um ficheiro, identificador ou campo; um certificado é endereçado através do respetivo ficheiro. Com lineage=upstream, é seguida a linhagem do próprio recurso.
  • Um Registo recebido num envio ou criado por uma divisão abre o seu histórico com transfer.received / slice.derived, atribuído à pessoa que aceitou ou dividiu; não tem created.thread nem bind próprios.
• GET /api/v1/summary — métricas de contagem principais
• GET /api/v1/notifications — notificações do autor da chamada

Próximos passos

Início rápido

Faça a primeira chamada autenticada no guia de início rápido.

Cliente TypeScript

Utilize o @dustid/apid-client tipificado em vez de HTTP em bruto.

Convenções

Cabeçalhos, paginação e erros nas convenções da API.

Referência completa

Todos os caminhos, parâmetros e esquemas na referência da API.

Comprovativos PDF

Transfira um PDF a pedido com GET /api/v1/receipts/{kind}/{id}, em que kind é file, thread ou shipment, e id é o UUID correspondente. Utilize a autenticação habitual e os cabeçalhos de contexto da organização e da equipa ativas. A resposta é application/pdf, com um nome de ficheiro de anexo e definições de cache private e no-store. Accept-Language seleciona o idioma do comprovativo.

Os comprovativos de ficheiros incluem metadados, a soma de verificação SHA-256 guardada quando disponível, informações sobre o registo associado e entradas permitidas do registo de transações. Os comprovativos de registos incluem campos, identificadores, ficheiros e somas de verificação, relações, informações do conjunto e da linhagem, e registos de transações permitidos. Os comprovativos de envios começam pelas informações do envio, pelo seu estado atual e pelo manifesto, seguindo-se os detalhes e os registos de transações dos registos visíveis. Os envios pendentes utilizam os instantâneos oferecidos; os outros estados utilizam os registos a que o chamador pode atualmente aceder.

Para um ficheiro visível através de uma divulgação, forneça linkId; para um ficheiro oferecido num envio pendente, forneça transferId. Estes parâmetros de consulta UUID opcionais não podem ser combinados e aplicam-se apenas a comprovativos de ficheiros. Mantêm as mesmas restrições de acesso e divulgação da pré-visualização correspondente.

Os comprovativos incluem a data e hora de geração e uma ligação QR de regresso à DICE. São instantâneos sem assinatura dos registos visíveis para o chamador, não assinaturas digitais. A geração é apenas de leitura: não é guardado nenhum anexo de comprovativo nem evento no registo de transações. As exportações que excedam 10 000 eventos visíveis num registo de transações falham, em vez de serem truncadas sem aviso. As ligações num comprovativo continuam a requerer acesso à DICE.