> This page is for Piattaforma, version Versione precedente. > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 sperimentale: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Versione precedente: https://next.developer.frame.io/platform/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # Gestione degli utenti ## Panoramica Questa esercitazione spiega la gestione di base degli utenti tramite l'API Frame.io. Si presuppone che il lettore abbia già configurato l'[autenticazione](/getting-started/authentication) tramite OAuth2.0 o con un token sviluppatore. ### Concetti fondamentali Tralasciando le sfumature specifiche dei diversi ruoli e delle diverse autorizzazioni dei membri del team, ci sono due aspetti importanti da comprendere quando si gestiscono gli utenti tramite l'API Frame.io: 1. **I membri del team appartengono ai team** e hanno accesso a tutti i progetti non privati all'interno di quei team. I team manager e gli amministratori del team sono estensioni della ruolo di membro del team. 2. **I collaboratori del progetto appartengono a singoli progetti**. A seconda della configurazione di questi progetti, possono creare o meno presentazioni, scaricare risorse o invitare altri collaboratori. Per ulteriori informazioni, fai riferimento alla nostra documentazione di supporto a proposito di [membri del team rispetto ai collaboratori](https://support.frame.io/getting-started/sharing-with-your-team-or-clients/difference-between-team-members-vs-collaborators) e ai [ruoli per la gestione degli account](https://support.frame.io/enterprise-accounts/enterprise-account-management-roles). ### Modalità di partecipazione degli utenti agli account In generale, i nuovi utenti vengono invitati dagli utenti attuali, direttamente o tramite URL univoco di partecipazione al progetto. I membri del team possono anche: 1. Aggiungersi a progetti non privati all'interno di team pubblici nel loro account 2. Aggiungersi a team pubblici all'interno del loro account 3. Richiedere di unirsi a team privati all'interno del loro account In tutti i casi, le attività di partecipazione seguiranno una serie di passaggi logici che includono il controllo dell'appartenenza precedente, la creazione di record "in sospeso" e l'invio di e-mail di invito o di richiesta di partecipazione, se appropriato. La buona notizia è che tutta questa logica è astratta dall'API Frame.io. Se vuoi aggiungere qualcuno a un progetto, usa gli instradamenti dei collaboratori; se vuoi invitare qualcuno a un team, usa gli instradamenti dei membri del team. ### Ambiti richiesti | Ambito | Motivo | | ---------- | ---------- | | **Team:** aggiornamento | Aggiungi e rimuovi membri del team. | | **Progetti:** aggiornamento | Aggiungi e rimuovi collaboratori del progetto. | ## Gestione dei membri del team ### Aggiunta di membri del team Per aggiungere un nuovo membro a un team, ti serve: 1. L'`id` del team di destinazione. 2. L'indirizzo e-mail dell'utente di destinazione. Poi basta eseguire una richiesta `POST` autorizzata a `https://api.frame.io/v2/teams/:id/members` con l'e-mail dell'utente di destinazione nel payload del corpo, come segue: ```json { "email": "user@example.com" } ``` **Se l'utente che hai invitato è già un membro del team nella tua organizzazione**, la risposta API lo indicherà: ```json { "_type": "team_member", "id": "", "role": "member", "team_id": "", "user_id": "" } ``` **Se l'utente che hai invitato non fa ancora parte della tua organizzazione**, la richiesta attiverà un flusso di invito e la risposta API avrà un aspetto simile al seguente: ```json { "_type": "pending_team_member", "email": "user@example.com", "id": "", "role": "member", "team_id": " } ``` **Nota**: poiché l'utente non è ancora stato creato o riconosciuto, non ci sarà uno `user_id` mappabile nella risposta `pending_team_member`. ### Rimozione di membri del team Per rimuovere un membro da un team, ti serve: 1. L'`id` del team di destinazione. 2. L'indirizzo e-mail dell'utente di destinazione. Devi quindi effettuare una chiamata `DELETE` allo stesso URL che useresti per aggiungere un membro del team, passando una stringa di richiesta speciale: `DELETE` [`https://api.frame.io/v2/teams/:id/members/_?email=user@example.com`](ref:post_teams-teamid-members) **Nota** sulla la costruzione `/_?email=`: questo è un pattern speciale nell'API Frame.io chiamato "include" che consente di richiedere dati aggiuntivi nella richiesta API (in questo caso, l'indirizzo e-mail dell'utente). Se la chiamata riesce, l'API restituirà un payload simile all'aggiunta di membri del team. Se il membro del team viene eliminato per la prima volta, vedrai un attributo `updated_at` corrispondente all'ora della chiamata. Se il membro del team è stato eliminato in precedenza, la marca temporale non si aggiornerà, ovvero rifletterà l'ora in cui il membro del team è stato rimosso inizialmente. ```json { "_type": "team_member", "id": "", "role": "member", "team_id": "", "user_id": "", "updated_at": "" } ``` I tentativi di rimuovere membri del team che non esistono o non sono mai stati associati al team causeranno degli errori 404. ## Gestione dei collaboratori del progetto ### Aggiunta di collaboratori del progetto La gestione dei collaboratori è molto simile alla gestione dei membri del team. Per aggiungere un nuovo collaboratore a un team, ti serve: 1. L'`id` del progetto di destinazione. 2. L'indirizzo e-mail dell'utente di destinazione. Devi quindi eseguire un richiesta `POST` autorizzata a [ `https://api.frame.io/v2/projects/:id/collaborators`](ref:post_projects-projectid-collaborators), con l'e-mail dell'utente di destinazione nel payload del corpo: ```json { "email": "user@example.com" } ``` **Se l'utente che hai invitato viene riconosciuto** e il ruolo di collaboratore può essere creato immediatamente, la risposta API lo indicherà e invierà un oggetto utente completo: ```json { "_type": "collaborator", "creator_id": "", "id": "", "project_id": "", "user": { "_type": "user", <...> }, "user_id": "" } ``` Se l'utente è già un membro del team nella tua organizzazione, ma non è membro del progetto di destinazione, puoi comunque utilizzare l'instradamento di collaborazione e l'API risponderà come indicato in alto. Il membro del team verrà aggiunto in background al progetto di destinazione e rimarrà un membro del team. In altre parole, non puoi "far retrocedere" accidentalmente i membri del team con questo instradamento. **Se l'utente che hai invitato è nuovo nella tua organizzazione**, la tua richiesta attiverà un flusso di invito e l'API risponderà con un record `pending_collaborator`, come segue: ```json { "_type": "pending_collaborator", "email": "user@example.com", "id": "", "project_id": "" } ``` ### Rimozione dei collaboratori del progetto **Nota:** questo processo è praticamente identico a come vengono gestiti i membri del team (descritto in alto). Per rimuovere un collaboratore da un progetto, ti serve: 1. L'`id` del progetto di destinazione. 2. L'indirizzo e-mail dell'utente di destinazione. Devi quindi effettuare una chiamata `DELETE` allo stesso URL che useresti per aggiungere un collaboratore, passando una stringa di richiesta speciale. `DELETE` [`https://api.frame.io/v2/projects/:id/collaborators/_?email=user@example.com`](ref:post_teams-teamid-members) Su la chiamata riesce, l'API restituirà un payload simile all'aggiunta di un collaboratore del progetto: ```json { "_type": "collaborator", "creator_id": "", "id": "", "project_id": "", "user": { "_type": "user", <...> }, "user_id": "" } ``` I tentativi di rimuovere collaboratori che non esistono o non sono mai stati associati al progetto causeranno degli errori 404. A differenza della rimozione di membri del team, i tentativi di rimuovere collaboratori già rimossi causeranno degli errori 404