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.

Référence de l'API pour les développeurs

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

Créer une clé API

  1. 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).
  2. 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.
  3. 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é.
  4. 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

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" }
}
HTTPerrorSignification
400invalid_json, use_www_host, bad_requestRequête mal formée : corps JSON invalide, hôte incorrect (utilisez l'hôte www.) ou requête illisible.
401missing_key, invalid_key, revoked_key, expired_key, user_inactive, office_not_foundLa clé est manquante, invalide, révoquée ou expirée, son titulaire n'est plus actif, ou le cabinet de la clé est introuvable.
403scope_missing, module_forbidden, forbidden, office_api_disabled, licence_expired, office_archivedUne autorisation manque sur la clé ou sur l'utilisateur, ou le cabinet n'a pas activé l'API.
404not_found, matter_not_visible, unknown_endpoint, upload_not_finished, replay_not_visibleL'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).
405delete_not_allowed, update_not_allowed, method_not_allowedLa suppression est impossible via l'API ; la modification n'est possible que là où la description propose une opération PATCH.
409client_exists, client_exists_generic, idempotency_key_reused, duplicate_in_progress, record_conflict, record_locked, duplicate_nameUn 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.
413request_too_large, file_too_largeLe 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).
422validation_failed, unknown_client, unknown_colleague, blocked_file_type, upload_token_invalid, folder_not_in_matter, document_name_too_longUn 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).
429rate_limited, auth_rate_limitedTrop de requêtes (300 par minute et par clé) ; l'en-tête Retry-After indique quand réessayer.
500server_errorErreur 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.
503office_maintenance, office_setup_incomplete, temporarily_unavailableLe 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.