Guida all’API delle Schede

Una Scheda è il registro digitale di un singolo oggetto fisico, ad esempio una risorsa, un componente, un documento o un elemento di un flusso di lavoro. Contiene un nome e una descrizione, dati di campo tipizzati, file allegati, identificatori associati e una cronologia degli eventi. Le Schede appartengono a un Team, pertanto ogni richiesta richiede un bearer token e l’intestazione Dust-Ctx-Org-Id (oltre a Dust-Ctx-Team-Id per operare come un Team specifico): consulta Autenticazione e Convenzioni.

Questa guida illustra i flussi principali. Per tutti i parametri e gli schemi delle risposte, consulta il riferimento API.

Panoramica degli endpoint

Operazione	Metodo e percorso
Crea una o più Schede	POST /api/v1/threads
Elenca / cerca Schede	GET /api/v1/threads
Conta le Schede	GET /api/v1/threads/count
Ottieni una Scheda	GET /api/v1/threads/{thread_id}
Aggiorna metadati e campi	POST /api/v1/threads/{thread_id}
Aggiorna solo i campi	POST /api/v1/threads/{thread_id}/data
Elenca i dati di campo archiviati	GET /api/v1/threads/{thread_id}/data/archived
Ripristina i dati di campo archiviati	POST /api/v1/threads/{thread_id}/data/restore
Archivia le Schede	PATCH /api/v1/threads/archive
Ripristina le Schede	PATCH /api/v1/threads/restore
Controlla le autorizzazioni del chiamante	POST /api/v1/threads/permissions
Segnale periodico di presenza	POST /api/v1/threads/{thread_id}/presence
Elenca i file di una Scheda	GET /api/v1/threads/{thread_id}/files
Imposta / carica la miniatura	PATCH / POST /api/v1/threads/{thread_id}/thumbnail

Gli aggiornamenti delle miniature accettano un resourceId autorizzato oppure un imageUri inline contenente un’immagine raster in base64, con dimensione massima decodificata di 5 MiB. Gli URL di immagini remote vengono rifiutati. Il caricamento dei file rimane disponibile tramite l’endpoint di caricamento delle miniature. Le miniature basate su una risorsa seguono le autorizzazioni di lettura correnti della Risorsa di origine: le risposte restituiscono null sia per thumbnail sia per thumbnailId quando l’accesso viene negato o la risorsa di origine non è più allegata. Le miniature caricate senza una Risorsa di origine seguono la visibilità della Scheda.

Creare una Scheda

POST /api/v1/threads accetta tre strutture del corpo, selezionate tramite type: single (una Scheda), list (più Schede normalizzate) e raw (registri chiave-valore piatti). Tutte e tre accettano un bundleId facoltativo per creare le Schede all’interno di una Cartella.

curl

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 } }
    ]
  }'

TypeScript

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 } },
  ],
});

I valori dei campi sono annidati sotto value in base al tipo: { "text": … }, { "number": … } e così via. La specifica definisce gli input per testo, testo lungo, numero, valore booleano, data, intervallo di date, data e ora, ora, durata, email, telefono, URL, JSON, selezione singola, selezione multipla, identificatori, riferimenti a risorse (file) e riferimenti a schede.

Importazione in blocco

Usa type: "list" quando disponi già di oggetti { thread, data } normalizzati, oppure type: "raw" per passare all’API registri piatti: i campi vengono derivati dalle coppie chiave-valore di ciascun oggetto, usando nameKey e descriptionKey (per impostazione predefinita name / description) per i metadati della Scheda:

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

Per importare intere strutture di assiemi in modo atomico, consulta POST /api/v1/imports/plan e POST /api/v1/imports/commit nel riferimento.

Leggere le Schede

GET /api/v1/threads/{thread_id} restituisce la Scheda con i relativi dati di campo (una query facoltativa maxEvents include gli eventi recenti). GET /api/v1/threads restituisce un elenco con paginazione tramite cursore (cursor, pageSize, order, orderCol) e supporta filtri tra cui:

Filtro	Significato
q, queryCol	Ricerca testuale, facoltativamente limitata a una colonna
bundleId	Schede in una Cartella o Categoria
templateId	Schede create da un Modello
tagType	Schede a cui è associato un identificatore di questo tipo
hasResources	Schede con file allegati
includeArchived, archivedOnly	Visibilità dell’archivio
createdBy, ownedByTeam	Filtri di provenienza
excludeTransferred, transferredOnly	Schede spedite altrove
withActiveShipment	Annota ciascun articolo con la relativa Spedizione attiva, se presente

GET /api/v1/threads/count accetta gli stessi filtri e restituisce soltanto il conteggio, utile per dashboard e riepiloghi della paginazione.

Aggiornare una Scheda

Due endpoint, con finalità distinte:

• POST /api/v1/threads/{thread_id} — accetta { thread, update?, remove? }: metadati della Scheda (nome, descrizione, modello, …) e modifiche facoltative ai campi in un’unica chiamata.
• POST /api/v1/threads/{thread_id}/data — solo campi: { threadId, update, remove?, expectedUpdatedAt? }. I campi in update vengono inseriti o aggiornati (corrispondenza per nome/ID); remove accetta gli ID dei campi.

POST /api/v1/threads/{thread_id}/data

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

Concorrenza ottimistica

Passa expectedUpdatedAt (il valore updatedAt letto per ultimo) con gli aggiornamenti dei dati. Se nel frattempo qualcun altro ha modificato la Scheda, la richiesta non riesce invece di sovrascrivere le modifiche senza avvisare.

Dati di campo archiviati

La rimozione di un campo lo archivia anziché distruggerlo. GET /api/v1/threads/{thread_id}/data/archived elenca i campi archiviati e POST /api/v1/threads/{thread_id}/data/restore li ripristina in base all’ID ({ threadId, restore: ["field-id", …] }).

Archiviare e ripristinare le Schede

L’archiviazione è eseguita in blocco ed è reversibile:

• PATCH /api/v1/threads/archive — { threadIds: […], toggle? }. Con toggle: true, in un’unica chiamata le Schede archiviate presenti nell’elenco vengono rimosse dall’archivio e quelle attive vengono archiviate.
• PATCH /api/v1/threads/restore — ripristina le Schede archiviate.

Le Schede archiviate non compaiono negli elenchi predefiniti; usa includeArchived o archivedOnly per visualizzarle.

Autorizzazioni

Prima di mostrare i controlli di modifica o tentare operazioni di scrittura su più Schede, verifica quali operazioni il chiamante può effettivamente eseguire:

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 restituisce le autorizzazioni effettive del chiamante per ciascuna Scheda nel contesto del Team corrente. Letture correlate: GET /api/v1/threads/{thread_id}/access (quali Team forniscono l’accesso) e GET /api/v1/threads/{thread_id}/shared (con chi è condivisa la Scheda), entrambe descritte in Team, condivisione e connessioni.

Presenza

POST /api/v1/threads/{thread_id}/presence è un segnale periodico: invialo periodicamente mentre un utente visualizza una Scheda (facoltativamente con name / image da mostrare e con leaving: true all’uscita); la risposta elenca gli utenti che stanno visualizzando la Scheda. DICE lo utilizza per l’indicatore «chi altro è qui».

File e miniature

I file vengono allegati alle Schede tramite l’API dei file; le letture dal lato della Scheda si trovano qui:

• GET /api/v1/threads/{thread_id}/files — i file della Scheda, con paginazione tramite cursore (includeArchived è obbligatorio).
• GET /api/v1/threads/{thread_id}/files/{res_id} / POST …/files/{res_id} — legge e aggiorna un singolo file allegato.
• POST /api/v1/threads/{thread_id}/thumbnail — carica un’immagine (multipart, campo thumbnail) e la imposta come miniatura della Scheda in un unico passaggio.
• PATCH /api/v1/threads/{thread_id}/thumbnail — imposta la miniatura a partire dall’ID di una risorsa esistente o da un URI di immagine.

Pagine correlate

• Modello principale — come le Schede si relazionano a tutto il resto
• Guida all’API degli identificatori — associazione degli identificatori fisici alle Schede
• Guida all’API dei file — caricamenti e download
• Riferimento API — schemi completi per ogni endpoint sopra indicato