Tu as activé l'API et créé ta clé ? Direction Activer l'API Kraaft pour bien démarrer ⚡

Cet article rassemble les subtilités qu'on ne découvre qu'en testant l'API en profondeur — garde-le sous la main si ton scénario Make bloque, si un champ te semble bizarre, ou si tu ne retrouves pas une conversation créée par l'API 🕵️

📦 Les ressources de l'API, en détail

🗂️ Workspaces — liste les espaces accessibles avec ta clé
📋 Schemas — te donne la structure d'un rapport (les champs, et pour les champs à choix, la correspondance entre chaque id et son libellé)
📝 Records — liste, consulte, crée et modifie les rapports d'un schéma donné
💬 Conversations (Rooms) — consulte, crée et modifie une conversation, gère ses membres, et envoie des messages (texte et fichiers)
⚡ Events — liste les événements passés ou reste connecté pour les recevoir en temps réel, dès qu'un rapport change

🤖 Se connecter à Make, n8n ou Zapier

✅ Make — installe l'app Kraaft directement depuis make.kraaft.co : l'authentification se fait en OAuth, en un clic, plus besoin de copier une clé API à la main
🔧 n8n, Zapier et autres — pas de connecteur natif Kraaft pour l'instant : utilise le module HTTP ou requête API de ton outil, avec ta clé API Kraaft en Bearer token

🔒 Les 4 rôles de clé, ce qu'ils font vraiment

Chaque clé API a un rôle, comme un utilisateur Kraaft classique : Externe, Standard, Administrateur, Propriétaire 👤 Mais leur comportement réel a des surprises ⬇️

🚫 Externe — ne peut pas créer de conversation (erreur "Room.create" manquante). Elle peut seulement agir (envoyer un message, créer un rapport) dans les conversations où elle est déjà membre
⚠️ Standard — peut créer une conversation, MAIS n'y est pas ajoutée automatiquement comme membre ! Pense à appeler juste après l'endpoint qui ajoute un membre à la conversation — avec une clé Admin/Propriétaire, ou une autre clé déjà membre, sinon la clé Standard reste bloquée pour lire ou écrire dans la conversation qu'elle vient de créer
✅ Administrateur & Propriétaire — accès complet à l'espace, sans avoir besoin d'être membre d'une conversation : elles voient et modifient toutes les conversations non privées, même celles qu'elles viennent de créer

💡 Le bon réflexe si tu es bloqué : si ton scénario Make avec une clé Standard "ne voit rien" ou "plante après la création d'une conversation", c'est très probablement ce piège d'appartenance à la conversation — pas un bug. Deux solutions : utilise une clé Admin/Propriétaire pour ce scénario, ou fais ajouter ta clé comme membre par quelqu'un qui a déjà accès à la conversation.

🆔 Résoudre un ID en libellé

Les champs à choix (statut, catégories…) et les champs utilisateur ne renvoient pas le libellé affiché dans l'app — seulement un identifiant technique 🔢

✅ Pour un champ à choix : va chercher le schéma du rapport (GET Schema) — chaque option y liste son id et son label, il suffit de faire la correspondance
❌ Pour un utilisateur : pas de solution automatique côté API — il n'existe pas d'endpoint qui donne le nom ou l'email d'un utilisateur à partir de son ID. Demande à notre support un export des ID de ton espace pour faire la correspondance

🧩 Comprendre les champs liste et tableau via l'API

Pour un rapport avec des champs simples (texte, nombre, case, date, choix, photo), le schéma te donne toute la donnée directement. Pour les champs liste et tableau — fréquents dans les rapports (pointages, matériel, contrôles) — la structure est plus complexe 🧩

Exemple : un pointage hebdomadaire. Dans l'app, le champ "Pointage de la semaine" affiche une section par jour (Lundi, Mardi…) avec plusieurs champs chacune. Côté API, ce même champ renvoie :

"pointage_de_la": { "type": "multiple", "ofType": "recordId", "value": ["id_lundi", "id_mardi", "id_mercredi", ...] }

En résumé : l'API fonctionne bien pour les champs simples, mais pas encore dans le détail pour les champs liste et tableau — le contenu précis de chaque ligne n'est pas directement accessible.

⚡ Filtrage et temps réel : ce qui existe

Deux capacités avancées existent et valent le coup d'être connues, sans forcément entrer dans le détail ici (la doc developers.kraaft.co couvre tout ça) :

🔍 Filtrer côté serveur — les listes de rapports et d'événements acceptent un paramètre de filtre (par exemple : uniquement les rapports dont le statut a changé) plutôt que de tout récupérer puis trier soi-même
📡 Recevoir les événements en temps réel — en plus d'interroger l'API à intervalles réguliers, il est possible de rester connecté et de recevoir chaque changement dès qu'il se produit (utile pour une intégration réactive, ex : notifier un ERP en moins d'une seconde)

🚫 Ce qui reste impossible aujourd'hui

⚠️ Pas encore possible via l'API

🗑️ Supprimer un rapport ou une conversation — seul l'archivage d'une conversation est possible, pas la suppression
👤 Retrouver automatiquement le nom ou l'email d'un utilisateur à partir de son ID — demande un export à notre support si tu en as besoin (voir plus haut)

💬 Besoin d'aide ?

Contacte notre support !

🔍 Aller plus loin avec l'API Kraaft