Modello di base

L’API della piattaforma DUST modella i flussi di lavoro relativi agli oggetti fisici come un piccolo insieme di risorse componibili. Una Scheda è il registro digitale di un articolo fisico; tutto il resto — identificatori, file, cartelle, assiemi, condivisioni, spedizioni — si collega alle Schede, le organizza o le sposta. Questa pagina ne offre una mappa: una breve sezione per ciascun concetto, con gli endpoint principali e un collegamento alla guida di approfondimento.

Mappa dei nomi

Alcuni namespace API sono precedenti all’attuale terminologia del prodotto. L’applicazione web DICE e questa documentazione usano i nomi a sinistra; i percorsi API mantengono i nomi a destra.

Nome in DICE / nella documentazione	Namespace API	Note
Schede	/api/v1/threads	—
Identificatori	/api/v1/tags	Denominazione legacy tags nei percorsi
File	/api/v1/files	Chiamati risorse in alcuni schemi
Cartelle e categorie	/api/v1/bundles	Bundle è il nome usato nell’implementazione
Assiemi	/api/v1/assemblies	Gli assiemi sono Schede di tipo assembly
Team	/api/v1/teams	Selezionato per ogni richiesta tramite l’header Dust-Ctx-Team-Id (l’header legacy Dust-Ctx-Grp-Id è ancora accettato)
Connessioni	/api/v1/connections	Gli schemi wire mantengono la denominazione legacy team link
Condivisione	/api/v1/sharing	—
Spedizioni	/api/v1/transfers	Denominazione legacy transfers nei percorsi
Suddivisioni	/api/v1/slices	—
Fabric	/api/v1/fabric	Grafo di provenienza tra organizzazioni
Certificati	/api/v1/certificates, /api/v1/certificate-forms	—
Pagine pubbliche	/api/v1/public-pages, /api/v1/public-page-designs	La pubblicazione richiede l’autorizzazione publisher del Team
Eventi	/api/v1/events	—

Ogni richiesta include un bearer token AuthD; gli endpoint con ambito organizzazione — quasi tutti — aggiungono l’header Dust-Ctx-Org-Id (e, facoltativamente, Dust-Ctx-Team-Id per selezionare un Team). Consulta Autenticazione e Convenzioni. La documentazione completa a livello di parametro è disponibile nella documentazione di riferimento dell’API.

Schede

Una Scheda è il registro di una singola risorsa fisica, di un componente, di un documento o di un articolo del flusso di lavoro: comprende un nome e una descrizione, dati dei campi tipizzati, file allegati, identificatori associati e una cronologia degli eventi. Le Schede hanno un kind: unità ordinarie oppure assembly (vedi sotto).

• POST /api/v1/threads — crea una o più Schede
• GET /api/v1/threads — cerca e restituisce un elenco (paginazione tramite cursore)
• GET /api/v1/threads/{thread_id} — recupera una Scheda, inclusi i dati dei campi
• POST /api/v1/threads/{thread_id}/data — inserisce, aggiorna o rimuove i valori dei campi
• PATCH /api/v1/threads/archive / PATCH /api/v1/threads/restore — ciclo di vita dell’archiviazione

Approfondimento: Guida all’API delle Schede.

Campi e modelli

I valori dei campi sono tipizzati (text, number, date, select, riferimenti a risorse e persino campi il cui valore è una Scheda) e annidati per tipo. I modelli definiscono i campi previsti per un tipo ripetibile di Scheda.

• POST /api/v1/templates / GET /api/v1/templates — crea ed elenca i modelli
• GET /api/v1/templates/{templateId} / PATCH /api/v1/templates/{templateId} — legge e aggiorna

Identificatori

Un identificatore associa una marcatura fisica — un identificatore DUST, un codice QR, un codice a barre, un simbolo Data Matrix o un chip NFC — a una Scheda, affinché una scansione sul campo venga risolta nel registro digitale. Il namespace API è /api/v1/tags (denominazione legacy).

• POST /api/v1/tags/extract — analizza un’acquisizione DUST per ricavarne un’impronta canonica senza effettuare alcuna associazione
• POST /api/v1/tags/bind — associa un identificatore a una Scheda
• POST /api/v1/tags/identify — trova la Scheda corrispondente a una scansione
• POST /api/v1/tags/verify — conferma che una scansione corrisponda agli identificatori di una specifica Scheda
• POST /api/v1/tags/unbind — dissocia un identificatore

Approfondimento: Guida all’API degli Identificatori.

File

I file (chiamati risorse in alcuni schemi) vengono conservati nell’archiviazione a oggetti e allegati alle Schede direttamente o tramite campi di tipo risorsa. I caricamenti di grandi dimensioni usano il protocollo ripristinabile tus; quelli piccoli usano un’unica richiesta POST multipart.

• POST /api/v1/files — semplice caricamento multipart
• POST /api/v1/files/finalize — converte i caricamenti tus completati in registri di risorse
• GET /api/v1/files/{resource_id}/download — scarica
• POST /api/v1/files/urls — URL firmati di breve durata
• GET /api/v1/files/search — cerca tra i file

Approfondimento: Guida all’API dei file.

Team e organizzazioni

L’identità risiede in AuthD; tramite gli header di contesto, l’API della piattaforma assegna ogni richiesta con ambito organizzazione a un’Organizzazione e a un Team. I Team possiedono le Schede, mentre condivisioni, connessioni e spedizioni operano tutte tra Team.

• GET /api/v1/me — utente corrente e organizzazioni disponibili
• GET /api/v1/teams — Team visibili al chiamante
• POST /api/v1/org/teams / PATCH /api/v1/org/teams/{team_id} — gestione dei Team (amministratori dell’organizzazione)
• POST /api/v1/org/teams/members — gestisce le appartenenze (amministratori dell’organizzazione)

Approfondimento: Team, condivisione e connessioni.

Cartelle e categorie

Le cartelle e le categorie organizzano le Schede. Nell’API sono entrambe bundle: kind: "folder" per il contenimento esclusivo e kind: "category" per l’etichettatura non esclusiva. Le cartelle possono essere annidate per formare strutture ad albero.

• POST /api/v1/bundles — crea (con kind e un elemento padre childOfId facoltativo)
• GET /api/v1/bundles / GET /api/v1/bundles/children — elenca o percorre l’albero in modo differito
• POST /api/v1/bundles/{bundle_id}/add / PATCH /api/v1/bundles/{bundle_id}/move — colloca le Schede
• PATCH /api/v1/bundles/parent — assegna una cartella a un nuovo elemento padre

Assiemi e componenti

Un assieme è una Scheda di tipo assembly i cui componenti sono altre Schede: una struttura di distinta base. È possibile impedire il distacco dei componenti e aggregare in modo transitivo gli elenchi dei componenti.

• GET /api/v1/assemblies — elenca le Schede di tipo assieme
• POST /api/v1/assemblies/{assembly_id}/parts / DELETE /api/v1/assemblies/{assembly_id}/parts — collega e scollega i componenti
• GET /api/v1/assemblies/{assembly_id}/rolled-up-parts — elenco transitivo dei componenti
• PATCH /api/v1/assemblies/{assembly_id}/kind — converte una Scheda da unit ad assembly e viceversa
• POST /api/v1/imports/plan / POST /api/v1/imports/commit — esegue una simulazione e conferma un intero pacchetto di importazione di un assieme

Collegamenti e relazioni tra Schede

Le Schede possono fare riferimento l’una all’altra mediante collegamenti tipizzati. Le definizioni delle relazioni denominano i tipi di relazione; i collegamenti tra Schede ne sono le istanze.

• POST /api/v1/relations / GET /api/v1/relations — definisce ed elenca i tipi di relazione
• POST /api/v1/links / GET /api/v1/links — crea ed elenca i collegamenti tra Schede
• GET /api/v1/threads/{thread_id}/links — collegamenti dalla prospettiva di una Scheda
• DELETE /api/v1/links/{link_id} — rimuove un collegamento

Condivisione

La condivisione concede a un altro Team l’accesso viewer o editor a una Scheda o a una cartella. Le autorizzazioni sono memorizzate come tuple di relazione; il riepilogo degli accessi mostra il risultato effettivo, incluso l’accesso ereditato.

• POST /api/v1/sharing — condivide Schede o cartelle con altri Team
• GET /api/v1/sharing — elenca le autorizzazioni (direction=in|out)
• GET /api/v1/sharing/access-summary — accesso effettivo a un oggetto
• GET /api/v1/sharing/partner-inventory — tutto ciò che è condiviso con un determinato Team partner

Approfondimento: Team, condivisione e connessioni.

Connessioni

Una Connessione (nell’API: team link) è l’accordo permanente tra due Team, spesso appartenenti a Organizzazioni diverse, che consente condivisioni e spedizioni con una direzione ammessa per il flusso dei dati. Prevede una procedura di invito, accettazione e conferma e un ciclo di vita di sospensione e ripresa.

• POST /api/v1/connections — crea (invita)
• PATCH /api/v1/connections/accept / confirm / reject / cancel — procedura di accordo
• PATCH /api/v1/connections/pause / resume — sospende e ripristina
• POST /api/v1/connections/amend/propose — propone una modifica della direzione

Spedizioni

Una Spedizione (nell’API: transfer) trasferisce la proprietà delle Schede da un Team a un altro: si prepara una bozza della distinta, la si invia e il destinatario la accetta, la rifiuta oppure richiede modifiche.

• POST /api/v1/transfers — crea una bozza
• POST /api/v1/transfers/{transfer_id}/items — aggiunge articoli alla distinta
• POST /api/v1/transfers/{transfer_id}/send — invia al Team destinatario
• POST /api/v1/transfers/{transfer_id}/respond — accetta / rifiuta / richiede modifiche
• GET /api/v1/transfers — viste degli elementi in arrivo, in uscita e inviati

Semantica e ciclo di vita: Spedizioni; riepilogo degli endpoint in Team, condivisione e connessioni.

Suddivisioni

Una suddivisione deriva una nuova Scheda da una Scheda esistente all’interno dello stesso Team, copiando o collegando i campi, i file e gli identificatori selezionati, generalmente per preparare un sottoinsieme condivisibile.

• POST /api/v1/slices — suddivide una Scheda
• POST /api/v1/slices/batch — deriva più Schede contemporaneamente
• GET /api/v1/slices/{slice_id} — una suddivisione con i relativi collegamenti Fabric

Fabric

Fabric è il livello di provenienza tra organizzazioni: quando le Schede vengono trasferite o divulgate oltre i confini di un Team, Fabric registra il grafo delle Schede collegate e controlla esattamente quali dati possa vedere ciascun soggetto a valle (divulgazione), revisione dopo revisione.

• GET /api/v1/fabric/threads/{thread_id}/graph — grafo di provenienza visibile da una Scheda
• GET /api/v1/fabric/links/{link_id}/context — dati attualmente divulgati tramite un collegamento
• POST /api/v1/fabric/threads/{thread_id}/disclosure/revise / redact — modifica ciò che viene divulgato
• POST /api/v1/fabric/threads/{thread_id}/disclosure/push — propaga una divulgazione a valle
• GET /api/v1/fabric/notifications — notifiche di divulgazione per i proprietari a valle

Concetti: Fabric.

Certificati

I certificati rappresentano i dati delle Schede sotto forma di documenti emessi e verificabili. I moduli dei certificati ne definiscono il layout; la generazione collega un modulo a una Scheda in base al nome del campo.

Un modulo può contenere più zone QR Vlink. La generazione del certificato accetta una configurazione Vlink per ogni identificatore della zona e restituisce tutte le associazioni emesse tra zone e Vlink.

• POST /api/v1/certificate-forms / GET /api/v1/certificate-forms — gestisce i moduli
• POST /api/v1/certificates/preflight — verifica che un modulo possa essere risolto rispetto a una Scheda
• POST /api/v1/certificates/generate — emette un certificato
• GET /api/v1/certificates — elenca i certificati di una Scheda
• POST /api/v1/certificates/void — annulla un certificato

Concetti: Certificati.

Pagine pubbliche

Una pagina pubblica è la vista web non autenticata di una Scheda: il passaporto digitale del prodotto che un consumatore raggiunge scansionando un identificatore. Ciò che mostra è determinato interamente da un design della pagina pubblica riutilizzabile e appartenente al Team; pertanto la pubblicazione non richiede dati di contenuto specifici per ciascuna Scheda: la pubblicazione risolve il design rispetto alla Scheda. L’URL di una pagina viene riservato e associato prima che venga pubblicato alcunché, così è possibile stampare prima le etichette.

La pubblicazione di un design rende immutabile una versione del design; ogni pagina fa riferimento a una versione del design e a un’istantanea dei dati (i valori risolti per quella Scheda). Una pubblicazione in blocco ripubblica tutte le pagine di un ambito — cartella, categoria, modello o selezione esplicita — tramite un’unica versione del design, come esecuzione in background con registri autonomi dell’avanzamento e degli errori.

La prenotazione dell’URL di una pagina e la relativa associazione a una Scheda richiedono il livello membro: la prenotazione di un indirizzo non pubblica nulla, quindi le etichette possono essere stampate prima che qualcuno decida di pubblicare. Tutto ciò che rende pubblici i dati — pubblicare una pagina, attivarla o archiviarla, creare un design, pubblicare una versione del design, distribuirla ed eseguire pubblicazioni in blocco — richiede l’autorizzazione publisher del Team (implicita per gli amministratori del Team), così come i controlli preliminari e di anteprima. Il valore x-required-role di ogni operazione nella documentazione di riferimento dell’API è quello ufficiale.

• POST /api/v1/public-pages / POST /api/v1/public-pages/{publicPageId}/bind — riserva un URL permanente per la pagina, quindi lo associa a una Scheda
• GET / PUT /api/v1/public-pages/thread/{threadId} — legge oppure recupera o crea la pagina di una Scheda
• GET /api/v1/public-pages/thread/{threadId}/activity — visualizzazioni anonime e scansioni di verifica sulla pagina pubblicata
• POST /api/v1/public-pages/{publicPageId}/publish — pubblica un’istantanea tramite la versione più recente del design
• PATCH /api/v1/public-pages/{publicPageId} — attiva o archivia una pagina senza modificarne l’URL
• GET /api/v1/public-pages/{publicPageId}/publications — cronologia delle pubblicazioni
• POST /api/v1/public-pages/preflight / preflight/batch — verifica che un design possa essere risolto rispetto a una o più Schede
• POST /api/v1/public-page-designs / GET / PATCH /api/v1/public-page-designs/{designId} — crea una bozza del design
• POST /api/v1/public-page-designs/{designId}/versions — pubblica una versione del design (GET le elenca)
• POST /api/v1/public-pages/designs/{designId}/roll-out — rende online la versione più recente di un design in tutte le relative pagine
• POST /api/v1/public-pages/waves — avvia una pubblicazione in blocco (GET ne recupera il registro di esecuzione, gli articoli e l’elenco)
• POST /api/v1/public-pages/waves/{waveId}/retry-failed / cancel — riprova le operazioni non riuscite oppure interrompe il lavoro rimanente

La distribuzione procede soltanto in avanti: una versione del design non viene mai ripristinata e l’annullamento di una pubblicazione in blocco mantiene le pagine già pubblicate sulla versione che hanno ricevuto.

Concetti: Pagine pubbliche.

Eventi

Ogni modifica significativa — modifiche ai campi, associazioni, condivisioni e spedizioni — viene registrata come evento e forma la traccia di controllo mostrata in DICE come registro delle transazioni.

• GET /api/v1/events — elenca gli eventi, filtrabili per Scheda, Team, azione e intervallo temporale, con raggruppamento facoltativo delle attività (groupBy)
  • lineage=upstream (con threadId) restituisce anche gli eventi di ogni Scheda precedente nella genealogia Fabric della Scheda — la storia completa di una Scheda ricevuta — limitatamente a ciò che ogni fonte ha divulgato. Le righe a monte includono un oggetto lineage (Scheda di origine, Team di origine, collegamento, hop) e possono essere redacted; una successiva modifica della divulgazione da parte di una fonte compare come riga di sola lettura fabric.disclosure.revised. Se omesso, la risposta contiene soltanto gli eventi della Scheda stessa.
  • resourceId, tagId o fieldId (uno alla volta, con threadId) limitano la cronologia a un singolo file, identificatore o campo; un certificato viene indicato tramite il suo file. Con lineage=upstream viene seguita la genealogia della risorsa stessa.
  • Una Scheda ricevuta in una spedizione o creata da una suddivisione apre la propria cronologia con transfer.received / slice.derived, attribuiti alla persona che ha accettato o suddiviso; non ha un created.thread né un bind propri.
• GET /api/v1/summary — metriche riepilogative dei conteggi
• GET /api/v1/notifications — notifiche del chiamante

Passaggi successivi

Guida introduttiva

Effettua la tua prima chiamata autenticata nella guida introduttiva.

Client TypeScript

Usa il client tipizzato @dustid/apid-client invece di HTTP non elaborato.

Convenzioni

Header, paginazione ed errori nelle convenzioni dell’API.

Documentazione completa

Tutti i percorsi, i parametri e gli schemi nella documentazione di riferimento dell’API.

Ricevute PDF

Scarica un PDF su richiesta con GET /api/v1/receipts/{kind}/{id}, dove kind è file, thread o shipment e id è l’UUID corrispondente. Usa l’autenticazione abituale e le intestazioni di contesto dell’organizzazione e del team attivi. La risposta è application/pdf, con un nome file per l’allegato e impostazioni della cache private e no-store. Accept-Language seleziona la lingua della ricevuta.

Le ricevute dei file includono metadati, il checksum SHA-256 salvato quando disponibile, informazioni sulla scheda associata e voci consentite del registro delle transazioni. Le ricevute delle schede includono campi, identificatori, file e checksum, relazioni, informazioni sull’assieme e sulla genealogia, e registri consentiti. Le ricevute delle spedizioni iniziano con le informazioni sulla spedizione, il suo stato attuale e la distinta, quindi includono i dettagli e i registri delle schede visibili. Le spedizioni in sospeso usano le istantanee offerte; gli altri stati usano i record a cui il chiamante può attualmente accedere.

Per un file visibile tramite una divulgazione, fornisci linkId; per un file offerto in una spedizione in sospeso, fornisci transferId. Questi parametri di query UUID facoltativi non possono essere combinati e si applicano solo alle ricevute dei file. Mantengono le stesse restrizioni di accesso e divulgazione dell’anteprima corrispondente.

Le ricevute includono l’indicazione temporale di generazione e un collegamento QR a DICE. Sono istantanee non firmate dei record visibili al chiamante, non firme digitali. La generazione è di sola lettura: non viene salvato alcun allegato della ricevuta né alcun evento nel registro delle transazioni. Le esportazioni che superano 10.000 eventi visibili in un registro non riescono, anziché essere troncate senza avviso. I collegamenti in una ricevuta richiedono comunque l’accesso a DICE.