/
creer-notion-worker-assistant-code
Créer un Notion Worker avec un assistant de code

Lou Attal
Consultante certifiée Notion
Publié le 29 octobre 2026

Découvrez comment construire une synchronisation entre Notion et un outil externe avec un assistant de code, sans écrire une seule ligne de TypeScript.
Vos factures sont dans un outil, vos projets dans Notion, et vous recopiez les informations d'un côté à l'autre depuis des mois. La solution native s'appelle un Notion Worker, et elle a longtemps eu un défaut rédhibitoire : il fallait savoir programmer.
Ce n'est plus le cas. Notion a conçu les Workers pour être construits avec un assistant de code, et publie sa documentation dans un format que ces assistants savent lire. Nouveauté : l'IA de Notion fait désormais partie de ces assistants, en accès anticipé, et crée des Workers directement depuis Notion, sans passer par un terminal.
Dans cet article, découvrez comment déployer une première synchronisation Notion fonctionnelle sans écrire une ligne de TypeScript.
Ce que vous allez construire 🛠️
Une synchronisation, c'est-à-dire un programme qui va chercher des données dans un outil externe et les dépose dans une base Notion, à intervalle régulier, sans que personne n'intervienne. 🔄

Notion se charge du reste : il déclenche l'exécution selon la fréquence retenue, crée les lignes manquantes et met à jour celles qui ont changé. La suppression des lignes disparues de la source dépend du mode retenu : automatique quand la synchronisation renvoie à chaque fois l'ensemble des données (et seulement si l'exécution va jusqu'au bout), explicite quand elle ne renvoie que les changements.
⚠️ Si ce que vous cherchez reste à l'intérieur de Notion, un Worker est un détour inutile : un bouton ou une automatisation de base de données suffisent.
Choisir son assistant de code 🤖
Plusieurs assistants savent construire un Worker : Claude Code, Cursor, l'IA de Notion ou d'autres encore. La différence tient surtout à l'endroit où l'on travaille :
L'IA de Notion, en accès anticipé : la demande se formule directement dans Notion, sans terminal ni installation. La fonctionnalité n'est pas encore ouverte à tous les espaces.
Un assistant externe (Claude Code, Cursor, etc.) : accessible à tous, il travaille dans un dossier sur votre ordinateur et demande quelques installations, détaillées ci-dessous.
Les conseils sur la rédaction de la demande et la vérification du résultat s'appliquent à l'identique, quel que soit l'assistant.
Les prérequis ✅
Quatre prérequis avec un assistant externe, un seul avec l'assistant IA de Notion :
Un forfait Business ou Enterprise, avec les Workers activés par un propriétaire de l'espace dans les paramètres : ils ne sont pas disponibles en dessous (le guide du forfait Business détaille ce que ce niveau ouvre par ailleurs).

Un terminal : c'est le vrai obstacle avec un assistant externe, plus que le code.
Node.js en version 22 ou supérieure, avec npm 10 ou supérieur.
Un assistant de code externe, du type Claude Code ou Cursor, capable de lire une documentation en ligne et de modifier des fichiers dans un dossier.
Les quatre étapes 🧭
(Avec l'IA de Notion, aucune commande n'est à lancer : l'essentiel se joue à l'étape 3, dans la précision de la demande.)
1 - Créer le projet 📁
L'outil en ligne de commande de Notion s'installe d'une commande, puis génère un projet vierge : ntn workers new mon-worker
Le dossier obtenu contient déjà tout : la configuration, les dépendances, un exemple fonctionnel, et surtout des instructions destinées à l'assistant de code, dont un skill “/sync” qui construit une synchronisation à partir d'une description.
2 - Donner la documentation à l'assistant 📚
Avant toute demande, l'assistant doit avoir lu la documentation de Notion, publiée dans une version lisible par une machine à l'adresse developers.notion.com/llms.txt, qui recense toutes les pages disponibles. 📖
⚠️ Sans cela, l'assistant écrira du code plausible fondé sur ce qu'il croit savoir, ce qui produit des erreurs difficiles à diagnostiquer pour quelqu'un qui ne lit pas le TypeScript.
3 - Décrire la synchronisation ✍️
La qualité du résultat dépend entièrement de la précision de la demande. Une consigne vague produit un code approximatif 🎯
Voici le format qui fonctionne, à adapter à votre cas : “Crée une synchronisation qui récupère les factures de l'API de mon outil de facturation et les dépose dans une base Notion. Pour chaque facture, je veux le numéro, le nom du client, le montant, la date d'émission, la date d'échéance et le statut de paiement. Le statut doit être une propriété de type sélection avec trois valeurs : Payée, En attente, En retard. Synchronise toutes les heures. Ne récupère que les factures des douze derniers mois.”
Quatre éléments rendent cette demande exploitable, et leur absence explique la plupart des échecs 👇
La source précise, avec le nom de l'outil et l'accès dont vous disposez
La liste exacte des champs, un par un, plutôt que “les informations importantes”
Le type de chaque propriété particulière : une sélection, une date, une case à cocher
La fréquence et le périmètre, qui déterminent directement le coût
Les clés d'API n'ont pas leur place dans cette description ni dans le code : Notion prévoit un mécanisme dédié au stockage des secrets, et l'assistant sait l'utiliser si la documentation lui a été fournie 🔐
4 - Déployer et vérifier 🚀
Le déploiement tient en une commande :
**ntn workers deploy **⌨️
Le code part sur l'infrastructure de Notion, et la synchronisation commence à tourner selon la fréquence définie 🔄
Une précaution s'impose avant de brancher cela sur des données réelles. Un assistant de code produit un résultat plausible, pas un résultat garanti, et un Worker écrit dans vos bases sans supervision. La première exécution se vérifie donc ligne par ligne : les champs sont-ils au bon endroit, les dates correctement interprétées, les doublons absents ?
(En cas d'erreur, le message renvoyé par le terminal se recopie tel quel à l'assistant, qui corrige et redéploie.)
Les réglages importants ⚙️
Trois décisions pèsent plus que tout le reste sur le résultat et sur la facture. 💡
La fréquence. Elle s'exprime en intervalles, de cinq minutes au minimum à sept jours au maximum, et c'est elle qui détermine le coût, puisque chaque exécution consomme des crédits. Par défaut, une synchronisation tourne toutes les 30 minutes. Au quart d'heure, elle s'exécute 96 fois par jour contre une seule fois pour une synchronisation quotidienne, pour un confort que personne ne remarque. La bonne question n'est pas “à quelle vitesse est-ce possible”, mais “à partir de quel retard cela devient-il gênant”.

Qui possède la base. Deux options existent : laisser Notion créer et gérer la base, ou rattacher une base qui existe déjà. La première est plus simple et convient à une nouvelle synchronisation. La seconde s'impose quand la base est déjà reliée à d'autres (le fonctionnement des relations entre bases explique pourquoi on tient à la conserver). Dans ce second cas, le Worker prend le contrôle des colonnes qu'il déclare et peut écraser des lignes existantes : une copie de la base avant le rattachement évite les mauvaises surprises.
Le périmètre récupéré. Synchroniser trois ans d'historique quand six mois suffisent alourdit chaque exécution sans rien apporter. Il vaut mieux commencer étroit et élargir ensuite.
Ce qu'il ne vaut mieux pas confier à l'assistant 🚫
L'assistant écrit le code, il ne prend pas les décisions. Trois points restent de votre ressort :
Le choix de ce qui est synchronisé. Un assistant à qui l'on demande de “rapatrier les données clients” en rapatriera davantage que nécessaire. Les données personnelles qui n'ont rien à faire dans Notion doivent être exclues explicitement 🛡️
La vérification du résultat. Personne d'autre que vous ne sait à quoi doit ressembler une facture correcte dans votre base ✅
Le sens de l'écriture. Une synchronisation va toujours de l'outil externe vers Notion. Un Worker qui écrit dans l'outil source (un webhook ou un outil appelé par un agent) agit sur des données qui ne se restaurent pas toujours. La prudence commande de commencer par une lecture seule 🔒
Questions fréquentes ❓
Faut-il vraiment ne rien connaître au code ? 💻
Avec un assistant externe, il faut savoir ouvrir un terminal, lancer une commande et recopier un message d'erreur. C'est un cran au-dessus de “aucune compétence technique”, mais bien en dessous de “savoir programmer”. (Avec l'IA de Notion, même le terminal disparaît.)
Combien de temps prend une première synchronisation ? ⏱️
Une demi-journée pour la première, en comptant l'installation et les tâtonnements. Les suivantes se comptent en dizaines de minutes, puisque le projet et les réflexes sont déjà là.
Que se passe-t-il si la source change de format ? 🔄
La synchronisation échoue, et il faut la corriger. C'est l'inconvénient de toute intégration, quel que soit l'outil qui la porte.
Peut-on partager le Worker avec le reste de l'équipe ? 👥
Oui, depuis le portail développeur, avec deux niveaux de permission. Les personnes concernées utilisent alors la base synchronisée sans jamais voir le code.
Est-ce que ça consomme des crédits IA ? 🪙
Oui. Gratuits pendant la bêta, les Workers sont facturés en crédits Notion depuis le 15 octobre 2026, et leur consommation apparaît dans le tableau de bord des crédits. Une fréquence raisonnable reste le meilleur moyen de la maîtriser (le fonctionnement des crédits côté agents est détaillé ici).
Pour aller plus loin 🚀
Une fois la première synchronisation en place, les deux autres usages d'un Worker deviennent accessibles avec la même méthode : un outil que l'agent IA de Notion peut appeler, et un webhook qui réagit à un événement externe. Les deux peuvent s'appuyer sur une connexion authentifiée (OAuth) vers un service tiers. 🔗
La formation Boost consacre un module entier aux bases de données avancées, relations et agrégations comprises. C'est la structure sur laquelle une synchronisation vient se poser, et une base mal conçue rend n'importe quelle intégration bancale, quelle que soit la qualité du code.
(Si votre besoin se limite à importer un fichier de temps en temps, l'import de fichiers CSV fait le travail sans aucun développement. 📥)
Allez plus loin sur Notion avec Boost
Tout ce qu'il faut savoir pour utiliser Notion avec aisance, avec Lou Attal, consultante certifiée Notion.
Rejoindre Boost/articles
Lire d'autres articles
/formation
Découvrez la formation Boost
Passez d'une page blanche à une organisation sur mesure.

