Flowyer

Collegare assistenti IA esterni

Come collegare ChatGPT, Claude, Gemini, Grok, DeepSeek o Cursor a Flowyer, e cosa può e non può fare una chiave API.

Di cosa si tratta?

Con una chiave API personale un assistente IA esterno può leggere e creare record (pratiche, clienti, attività, ore, costi e documenti) in Flowyer a suo nome e, dove lei lo consente, modificarli. Ogni richiesta viene eseguita esattamente con i suoi permessi, ulteriormente limitati da quanto consentito sulla chiave; le pratiche, i clienti e le attività creati da un bot mostrano negli elenchi un piccolo contrassegno con la chiave che li ha creati, mentre per le ore, i costi e i documenti la chiave che li ha creati viene registrata ma è visibile solo a un amministratore dello studio, in "Record creati tramite API".

Cosa NON può fare una chiave

Non può mai eliminare nulla (una richiesta DELETE risponde sempre 405).
Può modificare un record solo tramite le operazioni e i campi PATCH offerti, indicando l'expected_updated_at del record (409 in caso di conflitto); nient'altro viene sovrascritto.
Può scaricare il contenuto di un documento solo con il permesso di download separato (documents:download), tramite il link firmato a breve scadenza di documents.download; non ha altro accesso ai file.
Non vede mai più di lei: le barriere tra pratiche e i permessi dei moduli valgono invariati.

Creare una chiave API

Un amministratore dello studio abilita l'accesso API per lo studio in Impostazioni > Chiavi API (disattivato per impostazione predefinita).
Nella stessa pagina lei crea una chiave: le dia un nome (es. "ChatGPT") per sapere in seguito quale bot corrisponde a quale chiave.
Selezioni cosa può fare il bot (lettura, creazione o modifica) e imposti una scadenza. I permessi di una chiave non si possono modificare in seguito: se serve di più, crei una nuova chiave.
La chiave viene mostrata una sola volta: la copi nelle impostazioni dell'assistente. Può revocarla in qualsiasi momento, con effetto immediato.

Assegni a ogni bot una chiave propria. Si revocano separatamente e gli elenchi di pratiche, clienti e attività mostrano quale ha creato un record.

Permessi disponibili

matters:read Lettura pratiche
matters:create Creazione pratiche
matters:update Modifica pratiche
clients:read Lettura clienti
clients:create Creazione clienti
clients:update Modifica clienti
tasks:read Lettura attività
tasks:create Creazione attività
tasks:update Modifica attività
workhours:read Lettura ore
workhours:create Registrazione ore
workhours:update Modifica ore
costs:read Lettura costi
costs:create Registrazione costi
costs:update Modifica costi
invoices:read Lettura fatture
documents:read Elenco documenti (solo metadati, senza download)
documents:download Download documenti (contenuto completo)
documents:create Caricamento documenti
documents:update Rinomina documenti
colleagues:read Elenco dei colleghi (solo nomi)
knowledge:read Lettura della knowledge base
knowledge:create Creazione di voci nella knowledge base
knowledge:update Modifica di voci nella knowledge base
emails:read Lettura email delle pratiche
litigation:read Elenco cronologia processuale
litigation:create Creazione voce cronologia processuale
litigation:update Modifica voce cronologia processuale
mail_register:read Lettura registro postale
mail_register:create Creazione voci registro postale
mail_register:update Modifica voci registro postale
comments:read Lettura dei commenti del caso
comments:create Pubblicazione di commenti al caso
comments:update Modifica dei propri commenti
trials:read Lettura delle udienze
trials:create Creazione udienze
trials:update Modifica udienze
courts:read Elenco dei tribunali
hr:read Lettura delle assenze (solo date)
calendar:read Lettura eventi del calendario
calendar:create Creazione eventi del calendario
calendar:update Modifica eventi del calendario
bookings:read Visualizzare le prenotazioni di appuntamenti
bookings:create Creare prenotazioni di appuntamenti (invia un'email al cliente)
bookings:update Riprogrammare e modificare le prenotazioni
bookings:send Confermare o annullare prenotazioni (invia un'email al cliente)
tickets:read Lettura dei ticket di assistenza
tickets:reply Rispondere ai ticket (invia un'e-mail al cliente)
tickets:update Modifica dello stato del ticket
portal:read Portale clienti: lettura di conversazioni e messaggi
portal:reply Portale clienti: rispondere al cliente (invia un messaggio e una e-mail di notifica)

Collegamento

Usi sempre esattamente l'host https che inizia con www. (un reindirizzamento eliminerebbe l'intestazione di autorizzazione). Per le connessioni con chiave API invii la chiave come "Authorization: Bearer <chiave>"; i client MCP si autenticano invece con OAuth, accedendo dal browser, quindi non è necessario inserire alcuna chiave.

URL di base: https://www.flowyer.it/api/agent
OpenAPI: https://www.flowyer.it/api/agent/openapi.json
MCP: https://mcp.flowyer.com/mcp

ChatGPT (Actions)

In un GPT personalizzato importi la descrizione OpenAPI qui sotto nella sezione Actions, scelga l'autenticazione con chiave API di tipo "Bearer" e incolli la chiave Flowyer.

https://www.flowyer.it/api/agent/openapi.json

Grok

Fornisca a Grok l'indirizzo della descrizione OpenAPI e la chiave; dalla descrizione apprende quali operazioni esistono e quali parametri richiedono.

Claude Code

Claude Code si collega al server MCP; al primo utilizzo la fa accedere dal browser (OAuth), senza bisogno di una chiave:

claude mcp add --transport http flowyer https://mcp.flowyer.com/mcp

Claude Desktop / Cursor / Gemini CLI / DeepSeek

Claude Desktop, Cursor, la CLI di Gemini e i client MCP basati su DeepSeek usano lo stesso indirizzo MCP nel loro file di configurazione; alla prima connessione il client la fa accedere dal browser (OAuth), senza bisogno di inserire una chiave:

{
  "mcpServers": {
    "flowyer": {
      "url": "https://mcp.flowyer.com/mcp"
    }
  }
}

REST (curl)

Esempi di chiamate REST dirette:

curl -H "Authorization: Bearer flw_..." https://www.flowyer.it/api/agent/me
curl -H "Authorization: Bearer flw_..." "https://www.flowyer.it/api/agent/matters?q=2026/0025"
curl -X POST -H "Authorization: Bearer flw_..." -H "Content-Type: application/json" \
     -H "Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f" \
     -d '{"name":"Kovács Kft.","email":"info@kovacs.hu"}' https://www.flowyer.it/api/agent/clients

Regole

Ripetizioni sicure (Idempotency-Key)

Ogni creazione accetta un'intestazione Idempotency-Key (o un campo idempotency_key): una richiesta ripetuta con lo stesso valore restituisce lo stesso record invece di crearne un altro, mentre chiavi diverse creano sempre record distinti. Senza chiave, una creazione identica entro 120 secondi restituisce il primo record.

Errori

Ogni errore ha la stessa struttura: un codice (error), un messaggio in inglese (message) e il messaggio nella lingua dello studio (message_localized). Il messaggio indica cosa fare. Con 401, 403, 404 e 422 non ha senso ripetere la richiesta invariata, con due eccezioni: con 404 upload_not_finished completi prima il caricamento su upload_url, poi richiami complete; con un token di accesso OAuth scaduto (401 expired_key) rinnovi prima il token.

{
  "error": "scope_missing",
  "message": "This API key does not have the \"clients:create\" permission. ...",
  "message_localized": "Ehhez az API-kulcshoz nem tartozik \"clients:create\" jogosultság. ...",
  "locale": "hu",
  "details": { "required_scope": "clients:create" }
}

HTTP	error	Significato
400	invalid_json, use_www_host, bad_request	Richiesta non valida: corpo JSON non valido, host errato (usare l'host www.) o richiesta illeggibile.
401	missing_key, invalid_key, revoked_key, expired_key, user_inactive, office_not_found	La chiave manca, non è valida, è revocata o scaduta, il suo titolare non è più attivo, oppure lo studio della chiave non è stato trovato.
403	scope_missing, module_forbidden, forbidden, office_api_disabled, licence_expired, office_archived	Manca un permesso sulla chiave o sull'utente, oppure lo studio non ha abilitato l'API.
404	not_found, matter_not_visible, unknown_endpoint, upload_not_finished, replay_not_visible	Il record non esiste o l'utente non può vederlo; endpoint sconosciuto; il file caricato non è ancora arrivato nello storage (upload_not_finished: lo carichi su upload_url, poi richiami complete); oppure una creazione ripetuta il cui record era già stato creato ma nel frattempo è stato eliminato o nascosto (replay_not_visible: non è stato creato nulla di nuovo, non lo crei di nuovo).
405	delete_not_allowed, update_not_allowed, method_not_allowed	Eliminare non è possibile tramite l'API; modificare solo dove la descrizione offre un'operazione PATCH.
409	client_exists, client_exists_generic, idempotency_key_reused, duplicate_in_progress, record_conflict, record_locked, duplicate_name	Esiste già un cliente con quel nome; nella cartella esiste già un documento con quel nome (duplicate_name); il record è cambiato dopo la lettura (record_conflict: lo rilegga e reinvii la modifica con il nuovo updated_at); il record è stato fatturato o bloccato (record_locked: esegua la modifica in Flowyer); l'Idempotency-Key è stato usato su un'altra risorsa; oppure una richiesta identica è in elaborazione.
413	request_too_large, file_too_large	Il corpo della richiesta è troppo grande (request_too_large), oppure il file da caricare supera il limite (file_too_large; details.max indica il limite in byte).
422	validation_failed, unknown_client, unknown_colleague, blocked_file_type, upload_token_invalid, folder_not_in_matter, document_name_too_long	Un campo non valido o mancante (details.fields indica quale); un token di caricamento non valido, già usato o scaduto (upload_token_invalid: ricominci il caricamento); oppure una cartella che non appartiene alla pratica (folder_not_in_matter).
429	rate_limited, auth_rate_limited	Troppe richieste (300 al minuto per chiave); l'intestazione Retry-After indica quando riprovare.
500	server_error	Errore imprevisto. La richiesta è stata registrata con il suo request_id; riprovare più tardi e, se si ripete, comunicare questo ID all'assistenza Flowyer.
503	office_maintenance, office_setup_incomplete, temporarily_unavailable	Lo studio non è temporaneamente disponibile (manutenzione o configurazione in corso); l'intestazione Retry-After indica quando riprovare.

Privacy

Il fornitore dell'assistente (es. OpenAI, Anthropic, xAI) vede tutti i dati restituiti dalla chiave. Dia una chiave solo a un bot di cui lo studio ha accettato il trattamento dei dati, e solo con i permessi davvero necessari.