Guida API a Team, condivisione e connessioni

Ogni elemento della piattaforma DUST appartiene a un Team ed è accessibile tramite i Team. Questa guida descrive i quattro livelli che determinano chi può vedere cosa:

1. Contesto — per conto di quale Organizzazione e Team agisce una richiesta.
2. Condivisione — concessione a un altro Team dell’accesso come visualizzatore o editor a Schede e Cartelle.
3. Connessioni — l’accordo permanente tra due Team, generalmente appartenenti a Organizzazioni diverse, che rende possibili la condivisione e le Spedizioni.
4. Spedizioni e Suddivisioni — trasferimento o derivazione di registri oltre tali confini.

Schemi completi: riferimento API.

Contesto della richiesta

L’identità risiede in AuthD; l’API della piattaforma definisce l’ambito di ogni chiamata tramite intestazioni:

Authorization: Bearer <authd-token>
Dust-Ctx-Org-Id: <organization-uuid>
Dust-Ctx-Team-Id: <team-uuid>

Dust-Ctx-Org-Id è obbligatorio per le chiamate con ambito di organizzazione. Dust-Ctx-Team-Id seleziona il Team che agisce e, per impostazione predefinita, corrisponde al Team radice dell’Organizzazione (Dust-Ctx-Grp-Id è la forma precedente ancora accettata). Consulta Autenticazione e Convenzioni.

• GET /api/v1/me — utente corrente, sessione, Organizzazione attiva e Organizzazioni disponibili
• GET /api/v1/me/feature-flags — flag delle funzionalità per il chiamante

Team

I Team suddividono un’Organizzazione; Schede, Cartelle e condivisioni appartengono tutti a un Team. L’aggiornamento dei metadati di un Team ne conserva l’Organizzazione e l’ID del Team; le proprietà di aggiornamento non dichiarate vengono rifiutate.

Operazione	Metodo e percorso
Elenca i Team che puoi vedere	GET /api/v1/teams
Elenca i Team partner connessi	GET /api/v1/teams/connected
Crea Team (amministratore dell’organizzazione)	POST /api/v1/org/teams
Elenca tutti i Team dell’Organizzazione (amministratore dell’organizzazione)	GET /api/v1/org/teams
Aggiorna / elimina un Team (amministratore dell’organizzazione)	PATCH / DELETE /api/v1/org/teams/{team_id}
Aggiungi o aggiorna appartenenze (amministratore dell’organizzazione)	POST /api/v1/org/teams/members
Elenca / rimuovi appartenenze (amministratore dell’organizzazione)	GET / DELETE /api/v1/org/teams/members

GET /api/v1/teams supporta q, role, rootId e includeLinked (per includere nei selettori i Team partner connessi). GET /api/v1/teams/connected elenca i Team partner raggiungibili tramite Connessioni attive, ossia i destinatari validi per condivisioni e Spedizioni.

Condivisione

Una condivisione concede a un Team l’accesso a un oggetto, ossia una Scheda o una cartella (Cartella/Categoria), come viewer o editor. Le autorizzazioni vengono archiviate come tuple di relazione e l’accesso può anche essere ottenuto indirettamente (una Cartella condivisa rende accessibili i propri contenuti); esistono quindi due modelli di lettura: l’elenco delle autorizzazioni non elaborate e il riepilogo degli accessi effettivi.

curl

curl -fsS "$APID_URL/api/v1/sharing" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Dust-Ctx-Team-Id: $DUST_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "item": "thread", "id": "'"$THREAD_ID"'", "teamId": "'"$PARTNER_TEAM_ID"'", "relation": "viewer" }
    ]
  }'

TypeScript

await client.sharing.add({
  items: [
    { item: "thread", id: threadId, teamId: partnerTeamId, relation: "viewer" },
  ],
});

Operazione	Metodo e percorso
Crea condivisioni	POST /api/v1/sharing
Elenca le condivisioni	GET /api/v1/sharing?direction=in|out
Aggiorna la relazione di una condivisione	PATCH /api/v1/sharing/{tuple_id}
Rimuovi condivisioni	DELETE /api/v1/sharing (corpo: { "ids": […] })
Accesso effettivo a un oggetto	GET /api/v1/sharing/access-summary?objectId=…&objectType=thread|bundle
Tutto ciò che è condiviso con un partner	GET /api/v1/sharing/partner-inventory?teamId=…

direction=out elenca ciò che il tuo Team ha condiviso; direction=in ciò che è stato condiviso con il tuo Team. Il riepilogo degli accessi risolve le autorizzazioni dirette, l’ereditarietà delle Cartelle e le relazioni tra Team nelle autorizzazioni effettive per un oggetto; l’inventario del partner è la vista per Connessione, utile prima di sospendere o modificare una Connessione.

Funzioni pratiche relative alle Schede: GET /api/v1/threads/{thread_id}/shared (con chi è condivisa questa Scheda) e POST /api/v1/threads/permissions (cosa può fare il chiamante) — consulta la guida alle Schede.

Connessioni

Una Connessione (nome nell’API: team link) collega due Team e regola tutte le attività tra Team. Include una direzione consentita per il flusso dei dati — send, receive o send_receive, espressa dal punto di vista del Team richiedente — e viene stabilita tramite una procedura in tre passaggi: il richiedente crea il collegamento, il partner lo accetta e il richiedente lo conferma. I collegamenti sono identificati dal relativo code di invito.

Operazione	Metodo e percorso
Crea (invito)	POST /api/v1/connections — corpo { "allow": "send" | "receive" | "send_receive", "email"? }
Elenca le Connessioni	GET /api/v1/connections
Ottieni / elimina una Connessione	GET / DELETE /api/v1/connections/{code}
Accetta (partner)	PATCH /api/v1/connections/accept
Rifiuta (partner)	PATCH /api/v1/connections/reject
Conferma (richiedente)	PATCH /api/v1/connections/confirm
Annulla	PATCH /api/v1/connections/cancel
Sospendi / riprendi	PATCH /api/v1/connections/pause / resume

La sospensione di una Connessione interrompe le attività di condivisione e Spedizione che dipendono da essa senza eliminare la relazione.

Modifiche della direzione

La modifica della direzione di una Connessione attiva richiede a sua volta una procedura di conferma, affinché nessuna delle parti possa ampliare unilateralmente il flusso dei dati: uno dei Team propone la modifica, l’altro Team la accetta e chi l’ha proposta la conferma; la direzione precedente rimane in vigore fino alla conferma:

• POST /api/v1/connections/amend/propose — corpo { "code", "allow" }
• PATCH /api/v1/connections/amend/accept / confirm / cancel

Le condivisioni il cui flusso non è più consentito dalla nuova direzione diventano inattive anziché essere eliminate.

Spedizioni

Una Spedizione (spazio dei nomi dell’API: /api/v1/transfers, denominazione precedente) trasferisce la proprietà delle Schede a un Team connesso: si prepara una distinta in bozza, la si invia e il destinatario risponde. Gli endpoint, nell’ordine del ciclo di vita:

Fase	Metodo e percorso
Crea bozza	POST /api/v1/transfers
Aggiungi / aggiorna / rimuovi articoli della distinta	POST /api/v1/transfers/{transfer_id}/items, PATCH / DELETE …/items/{item_id}
Imposta la Scheda principale	PUT /api/v1/transfers/{transfer_id}/primary-thread
Invia	POST /api/v1/transfers/{transfer_id}/send
Anteprima (destinatario, dopo l’invio)	GET /api/v1/transfers/{transfer_id}/preview
Rispondi: accetta / rifiuta / richiedi modifiche	POST /api/v1/transfers/{transfer_id}/respond
Conversa	POST /api/v1/transfers/{transfer_id}/messages
Annulla (bozza, inviata o con modifiche richieste)	POST /api/v1/transfers/{transfer_id}/cancel
Riprova una Spedizione non riuscita	POST /api/v1/transfers/{transfer_id}/retry
Abbandona una Spedizione non riuscita	POST /api/v1/transfers/{transfer_id}/abandon
Riparti dalla distinta di una Spedizione interrotta	POST /api/v1/transfers/{transfer_id}/start-from-prior-manifest
Elenca (viste delle caselle)	GET /api/v1/transfers?box=inbox|outbox|sent
Ottieni una Spedizione con la relativa distinta	GET /api/v1/transfers/{transfer_id}

La risposta accetta { "value": "accept" | "reject" | "request_changes" } (per le richieste di modifica è obbligatorio un reason). L’elenco supporta i filtri box, view, status e direction=inbound|outbound.

Nota

Questa tabella è intenzionalmente solo una mappa. Il contenuto di una distinta, il funzionamento della divulgazione e il significato di ogni stato sono descritti in Spedizioni; il modello di provenienza alla base della visibilità dei dati tra Team è descritto in Fabric.

Suddivisioni

Una Suddivisione deriva una nuova Scheda da una Scheda esistente all’interno del tuo Team, usando un sottoinsieme selezionato di campi, file e identificatori, in genere per preparare esattamente ciò che intendi condividere o spedire mantenendo privato il resto:

• POST /api/v1/slices — suddividi una Scheda (scegli la Cartella di destinazione tramite bundleId, seleziona fields, …)
• POST /api/v1/slices/batch — deriva più Schede in un’unica operazione
• GET /api/v1/slices/{slice_id} — una Suddivisione con i relativi collegamenti Fabric

Pagine correlate

• Modello principale — come Team, condivisioni e Connessioni si inseriscono nel dominio
• Spedizioni — semantica del ciclo di vita delle Spedizioni
• Fabric — provenienza e divulgazione tra organizzazioni
• Riferimento API — schemi completi per tutti gli endpoint precedenti