Flowyer
Connecter des assistants IA externes
Comment connecter ChatGPT, Claude, Gemini, Grok, DeepSeek ou Cursor à Flowyer, et ce qu'une clé API peut et ne peut pas faire.
De quoi s'agit-il ?
Grâce à une clé API personnelle, un assistant IA externe peut lire et créer des enregistrements dans Flowyer en votre nom : dossiers, clients, contacts des clients, tâches, saisies de temps, frais, documents, réservations, tickets de support, messages du portail client, événements de l'agenda, entrées de contentieux, dates d'audience, entrées du registre du courrier, articles de la base de connaissances et commentaires ; les factures, les e-mails d'un dossier et les demandes d'absence sont en lecture seule. Lorsque vous l'autorisez, il peut également modifier des enregistrements. Chaque requête s'exécute avec exactement vos autorisations, restreintes en outre par ce que vous autorisez sur la clé. Certaines actions peuvent également envoyer un message à votre client (réponse à un ticket par e-mail, confirmation de réservation, message du portail client) ; le système ne les envoie jamais qu'après votre confirmation explicite et distincte. Les dossiers, clients et tâches créés par un bot portent dans les listes un petit marqueur indiquant quelle clé les a créés ; pour les saisies de temps, les frais, les documents et les contacts des clients, la clé créatrice est enregistrée mais n'est visible que par un administrateur du cabinet, sous « Enregistrements créés via l'API ».
Ce qu'une clé ne peut PAS faire
- Elle ne peut jamais rien supprimer (une requête DELETE renvoie toujours 405).
- Elle ne peut modifier un enregistrement qu'au moyen des opérations PATCH et des champs proposés, en transmettant la valeur expected_updated_at de l'enregistrement (409 en cas de conflit) ; rien d'autre n'est écrasé.
- Elle ne peut télécharger le contenu d'un document qu'avec l'autorisation de téléchargement distincte (documents:download), au moyen du lien signé de courte durée de documents.download ; elle n'a aucun autre accès aux fichiers.
- Elle ne voit jamais plus que vous : les murailles de Chine et les autorisations par module s'appliquent sans changement.
Créer une clé API
- Un administrateur du cabinet active l'accès à l'API pour le cabinet sous Paramètres > Clés API (il est désactivé par défaut).
- Sur la même page, vous créez une clé : donnez-lui un nom (par exemple « ChatGPT ») afin de savoir ultérieurement quel bot chaque clé identifie.
- Cochez ce que le bot peut faire (lire, créer ou modifier) et définissez une date d'expiration. Les autorisations d'une clé ne peuvent pas être modifiées par la suite : si vous avez besoin de davantage, créez une nouvelle clé.
- La clé n'est affichée qu'une seule fois : copiez-la dans les paramètres de l'assistant. Vous pouvez la révoquer à tout moment, avec effet immédiat.
Attribuez à chaque bot sa propre clé. Elles peuvent ainsi être révoquées séparément, et les listes de dossiers, de clients et de tâches indiquent laquelle a créé un enregistrement.
Autorisations disponibles
matters:readConsulter les dossiersmatters:createCréer des dossiersmatters:updateModifier des dossiersclients:readConsulter les clientsclients:createCréer des clientsclients:updateModifier des clientscontacts:readConsulter les contactscontacts:createCréer des contactscontacts:updateModifier des contactstasks:readConsulter les tâchestasks:createCréer des tâchestasks:updateModifier des tâchesworkhours:readConsulter les saisies de tempsworkhours:createSaisir du tempsworkhours:updateModifier les saisies de tempscosts:readConsulter les fraiscosts:createEnregistrer des fraiscosts:updateModifier des fraisinvoices:readConsulter les facturesdocuments:readLister les documents (métadonnées uniquement, sans téléchargement)documents:downloadTélécharger les documents (contenu intégral)documents:createImporter des documentsdocuments:updateRenommer des documentscolleagues:readLister les membres de l'équipe (noms uniquement)knowledge:readConsulter la base de connaissancesknowledge:createCréer des entrées dans la base de connaissancesknowledge:updateModifier des entrées de la base de connaissancesemails:readConsulter les e-mails des dossierslitigation:readLister l'historique de procédurelitigation:createCréer des entrées d'historique de procédurelitigation:updateModifier des entrées d'historique de procéduremail_register:readConsulter le registre du courriermail_register:createCréer des entrées au registre du courriermail_register:updateModifier des entrées du registre du courriercomments:readConsulter les commentaires des dossierscomments:createPublier des commentaires sur les dossierscomments:updateModifier ses propres commentaires sur les dossierstrials:readConsulter les audiencestrials:createCréer des audiencestrials:updateModifier des audiencescourts:readLister les juridictionshr:readConsulter les absences (dates uniquement)calendar:readConsulter les événements de l'agendacalendar:createCréer des événements dans l'agendacalendar:updateModifier des événements de l'agendabookings:readConsulter les réservations de rendez-vousbookings:createCréer des réservations de rendez-vous (envoie un e-mail au client)bookings:updateReprogrammer et modifier des réservationsbookings:sendConfirmer ou annuler des réservations (envoie un e-mail au client)tickets:readConsulter les tickets de supporttickets:replyRépondre aux tickets (envoie un e-mail au client)tickets:updateModifier le statut des ticketsportal:readPortail client : consulter les fils de discussion et les messagesportal:replyPortail client : répondre au client (publie un message et lui envoie un e-mail)
Connexion
Utilisez toujours exactement l'hôte https commençant par www. (une redirection supprimerait l'en-tête d'autorisation). Pour les connexions par clé API, envoyez la clé sous la forme "Authorization: Bearer <key>" ; les clients MCP s'authentifient quant à eux via OAuth, en se connectant dans le navigateur : aucune clé n'est à saisir.
- URL de base
https://www.flowyer.fr/api/agent- OpenAPI
https://www.flowyer.fr/api/agent/openapi.json- MCP
-
https://mcp.flowyer.com/mcp
ChatGPT (Actions)
Dans un GPT personnalisé, importez la description OpenAPI ci-dessous sous Actions, choisissez l'authentification par clé API avec le type « Bearer » et collez votre clé Flowyer.
https://www.flowyer.fr/api/agent/openapi.json
Grok
Indiquez à Grok l'adresse de la description OpenAPI et la clé ; la description lui indique quelles opérations existent et quels paramètres elles acceptent.
Claude Code
Claude Code se connecte au serveur MCP ; lors de la première utilisation, il vous connecte via le navigateur (OAuth), sans clé :
claude mcp add --transport http flowyer https://mcp.flowyer.com/mcp
Claude Desktop / Cursor / Gemini CLI / DeepSeek
Claude Desktop, Cursor, la Gemini CLI et les clients MCP basés sur DeepSeek acceptent la même adresse MCP dans leur fichier de configuration ; lors de la première connexion, le client vous connecte via le navigateur (OAuth), aucune clé n'est à saisir :
{
"mcpServers": {
"flowyer": {
"url": "https://mcp.flowyer.com/mcp"
}
}
}
REST (curl)
Exemples d'appels REST directs :
curl -H "Authorization: Bearer flw_..." https://www.flowyer.fr/api/agent/me
curl -H "Authorization: Bearer flw_..." "https://www.flowyer.fr/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.fr/api/agent/clients
Règles
Nouvelles tentatives sûres (Idempotency-Key)
Chaque création accepte un en-tête Idempotency-Key (ou un champ idempotency_key) : une requête répétée avec la même valeur renvoie le même enregistrement au lieu d'en créer un autre, et des clés différentes créent toujours des enregistrements différents. Sans clé, une création identique dans un délai de 120 secondes renvoie le premier enregistrement.
Erreurs
Toutes les erreurs ont la même structure : un code machine (error), un message en anglais (message) et le message dans la langue du cabinet (message_localized). Le message indique la marche à suivre. Il est inutile de réessayer une requête inchangée en cas de 401, 403, 404 et 422, à deux exceptions près : en cas de 404 upload_not_finished, terminez d'abord l'import vers upload_url, puis appelez à nouveau complete ; en cas de jeton d'accès OAuth expiré (401 expired_key), renouvelez d'abord le jeton.
{
"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 | Signification |
|---|---|---|
| 400 | invalid_json, use_www_host, bad_request | Requête mal formée : corps JSON invalide, hôte incorrect (utilisez l'hôte www.) ou requête illisible. |
| 401 | missing_key, invalid_key, revoked_key, expired_key, user_inactive, office_not_found | La clé est manquante, invalide, révoquée ou expirée, son titulaire n'est plus actif, ou le cabinet de la clé est introuvable. |
| 403 | scope_missing, module_forbidden, forbidden, office_api_disabled, licence_expired, office_archived | Une autorisation manque sur la clé ou sur l'utilisateur, ou le cabinet n'a pas activé l'API. |
| 404 | not_found, matter_not_visible, unknown_endpoint, upload_not_finished, replay_not_visible | L'enregistrement n'existe pas ou l'utilisateur n'est pas autorisé à le voir ; point de terminaison inconnu ; le fichier importé n'est pas encore arrivé dans l'espace de stockage (upload_not_finished : importez-le vers upload_url, puis appelez à nouveau complete) ; ou une création répétée dont l'enregistrement a été créé auparavant mais a depuis été supprimé ou masqué (replay_not_visible : rien de nouveau n'a été créé, ne le créez pas à nouveau). |
| 405 | delete_not_allowed, update_not_allowed, method_not_allowed | La suppression est impossible via l'API ; la modification n'est possible que là où la description propose une opération PATCH. |
| 409 | client_exists, client_exists_generic, idempotency_key_reused, duplicate_in_progress, record_conflict, record_locked, duplicate_name | Un client portant ce nom existe déjà ; un document portant ce nom existe déjà dans le répertoire (duplicate_name) ; l'enregistrement a été modifié depuis votre lecture (record_conflict : relisez-le et renvoyez la modification avec la nouvelle valeur updated_at) ; l'enregistrement a été facturé ou verrouillé (record_locked : effectuez la modification dans Flowyer) ; l'Idempotency-Key a été utilisée sur une autre ressource ; ou une requête identique est en cours de traitement. |
| 413 | request_too_large, file_too_large | Le corps de la requête est trop volumineux (request_too_large), ou le fichier à importer dépasse la limite (file_too_large ; details.max indique la limite en octets). |
| 422 | validation_failed, unknown_client, unknown_colleague, blocked_file_type, upload_token_invalid, folder_not_in_matter, document_name_too_long | Un champ invalide ou manquant (details.fields indique lequel) ; un jeton d'import invalide, déjà utilisé ou expiré (upload_token_invalid : recommencez l'import) ; ou un répertoire qui n'appartient pas au dossier (folder_not_in_matter). |
| 429 | rate_limited, auth_rate_limited | Trop de requêtes (300 par minute et par clé) ; l'en-tête Retry-After indique quand réessayer. |
| 500 | server_error | Erreur inattendue. La requête a été journalisée sous son request_id ; réessayez plus tard et, si l'erreur se reproduit, communiquez cet identifiant au support Flowyer. |
| 503 | office_maintenance, office_setup_incomplete, temporarily_unavailable | Le cabinet est temporairement indisponible (maintenance ou configuration en cours) ; l'en-tête Retry-After indique quand réessayer. |
Confidentialité
Le fournisseur de l'assistant (par exemple OpenAI, Anthropic, xAI) voit toutes les données que la clé renvoie. Ne confiez une clé qu'à un bot dont le traitement des données a été accepté par le cabinet, et uniquement avec les autorisations dont il a réellement besoin.