Créer un Notion Worker avec un assistant de code

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. 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, met à jour celles qui ont changé et supprime celles qui ont disparu de la source.

⚠️ 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.

Les prérequis ✅

Quatre choses, dont une seule coûte de l'argent :

1. Un forfait Business ou Enterprise, essai Business compris : les Workers ne sont pas disponibles en dessous (le guide du forfait Business détaille ce que ce niveau ouvre par ailleurs).

1. Un terminal : c'est le vrai obstacle, plus que le code : il n'existe aucune interface graphique pour créer ou déployer un Worker.

2. Node.js en version 22 ou supérieure, avec npm 10 ou supérieur.

3. Un assistant de code, du type Claude Code ou Cursor, capable de lire une documentation en ligne et de modifier des fichiers dans un dossier.

Les quatre étapes 🧭

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 une commande “/sync” qui construit une synchronisation à partir d'une description.

👉 C'est le point le plus souvent ignoré : le projet généré n'est pas un squelette vide, c'est un environnement préparé pour un assistant.

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 👇

1. La source précise, avec le nom de l'outil et l'accès dont vous disposez

2. La liste exacte des champs, un par un, plutôt que “les informations importantes”

3. Le type de chaque propriété particulière : une sélection, une date, une case à cocher

4. 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.)

Capture à réaliser : la base Notion alimentée par la synchronisation, après la première exécution réussie.

Les réglages qui comptent vraiment ⚙️

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. Une synchronisation quotidienne coûte quelques centimes par mois, une synchronisation au quart d'heure plusieurs euros 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).

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 faut pas confier à l'assistant 🚫

L'assistant écrit le code, il ne prend pas les décisions. Trois points restent de votre ressort :

1. 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 🛡️

2. La vérification du résultat. Personne d'autre que vous ne sait à quoi doit ressembler une facture correcte dans votre base ✅

3. Le sens de l'écriture. Une synchronisation qui écrit dans Notion est réversible. Un Worker qui modifie l'outil source ne l'est pas toujours. La prudence commande de commencer par une lecture seule 🔒

Questions fréquentes ❓

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”.

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à.

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.

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.

Les exécutions d'un Worker sont facturées en crédits, mais à un tarif très inférieur à celui d'une action d'agent, puisqu'il s'agit de code prévisible sans raisonnement (les coûts côté agents sont détaillés ici).

Pour aller plus loin 🚀

Une fois la première synchronisation en place, les trois autres usages d'un Worker deviennent accessibles avec la même méthode : un outil que l'agent IA de Notion peut appeler, un webhook qui réagit à un événement externe, ou une connexion authentifiée vers une API tierce. 🔗

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. 📥)