Skip to content
Learni
View all tutorials
Outils Productivité

Comment débuter avec Notion étape par étape en 2026

12 minBEGINNER
JavaScriptProductivitéNo-codeNotionAPI

Introduction

Notion révolutionne la gestion de projets en 2026 en combinant notes, tâches, bases de données et wikis dans une interface intuitive. Contrairement à des outils rigides comme Trello ou Evernote, Notion offre une flexibilité infinie : imaginez un Lego numérique où chaque bloc (texte, image, tableau) s'emboîte parfaitement.

Ce tutoriel beginner vous guide de la création d'un workspace à l'intégration API pour automatiser vos workflows. Pourquoi c'est crucial ? 80% des équipes productives utilisent Notion pour centraliser infos, réduisant le temps de recherche de 40%. Vous apprendrez à structurer des pages, créer des databases et coder des scripts Node.js pour interagir via l'API officielle. À la fin, vous aurez un setup actionnable, prêt à scaler. Pas de fluff : chaque étape est copier-collable et testée.

Prérequis

  • Un compte Notion gratuit (inscrivez-vous ici).
  • Node.js 20+ installé (téléchargez-le).
  • Connaissances basiques en JavaScript (variables, fetch).
  • Un éditeur de code comme VS Code.
  • 15 minutes pour setup.

Initialiser le projet Node.js pour l'API Notion

terminal.sh
mkdir notion-tutorial
cd notion-tutorial
npm init -y
npm install @notionhq/client dotenv
npm install -D typescript @types/node ts-node

Ce script crée un projet Node.js dédié aux tests API Notion. @notionhq/client est le SDK officiel pour des appels simplifiés ; dotenv gère les secrets comme le token API. Lancez-le dans un terminal pour un setup instantané, évitant les erreurs de dépendances manquantes.

Obtenir votre token d'intégration Notion

  1. Allez sur my-integrations.notion.com.
  2. Cliquez 'New integration', nommez-la 'Tutorial API' et sélectionnez votre workspace.
  3. Copiez le Internal Integration Token (format secret_...).
  4. Partagez une page ou database de test avec votre intégration (clic droit > 'Connect to integration').
Analogie : Ce token est comme une clé API privée ; sans partage, l'API renverra 404. Gardez-le secret !

Configurer les variables d'environnement

.env
NOTION_API_KEY=secret_votre_token_ici
NOTION_DATABASE_ID=votre_database_id_ici

Créez ce fichier .env à la racine du projet. Remplacez par vos vraies valeurs : NOTION_API_KEY du dashboard, DATABASE_ID depuis l'URL d'une database Notion (ex: https://notion.so/votreworkspace/abc123?v=... → abc123). Ajoutez .env à .gitignore pour sécurité.

Script TypeScript pour interroger une database

query-database.ts
import { Client } from '@notionhq/client';
import * as dotenv from 'dotenv';

dotenv.config();

const notion = new Client({ auth: process.env.NOTION_API_KEY });

const databaseId = process.env.NOTION_DATABASE_ID || '';

(async () => {
  try {
    const response = await notion.databases.query({
      database_id: databaseId,
    });

    console.log('Pages de la database:', response.results.map((page: any) => ({
      id: page.id,
      title: page.properties.Name?.title[0]?.plain_text || 'Sans titre',
    })));
  } catch (error) {
    console.error('Erreur:', error);
  }
})();

Ce script complet query une database Notion et affiche titres des pages. Exécutez avec npx ts-node query-database.ts. Piège courant : sans partage de la database à l'intégration, erreur 404. Utilisez properties.Name pour le nom standard des tâches.

Créer votre première database via l'interface Notion

  1. Dans Notion, tapez /database et choisissez Database - Inline ou Full page.
  2. Ajoutez propriétés : Name (Titre), Status (Select: Todo, En cours, Fait), Date (Date).
  3. Copiez l'ID depuis l'URL.
Exemple visuel : Une database ressemble à un tableau Excel dynamique. Ajoutez une page test : 'Ma première tâche' > Status 'Todo'. Cela prépare les queries API.

Ajouter une page à la database via API

create-page.ts
import { Client } from '@notionhq/client';
import * as dotenv from 'dotenv';

dotenv.config();

const notion = new Client({ auth: process.env.NOTION_API_KEY });

const databaseId = process.env.NOTION_DATABASE_ID || '';

(async () => {
  try {
    const response = await notion.pages.create({
      parent: { database_id: databaseId },
      properties: {
        Name: {
          title: [{ text: { content: 'Tâche créée par API' } }],
        },
        Status: {
          select: { name: 'Todo' },
        },
        Date: {
          date: { start: new Date().toISOString().split('T')[0] },
        },
      },
    });

    console.log('Page créée:', response.id);
  } catch (error) {
    console.error('Erreur:', error);
  }
})();

Ce code ajoute une nouvelle entrée à votre database avec propriétés standards. Les propriétés doivent matcher exactement celles de la DB (ex: 'Status'). Lancez après query pour vérifier. Évitez les dates invalides pour prévenir les erreurs de validation.

Mettre à jour une page existante

update-page.ts
import { Client } from '@notionhq/client';
import * as dotenv from 'dotenv';

dotenv.config();

const notion = new Client({ auth: process.env.NOTION_API_KEY });

const pageId = 'votre_page_id_ici_récupéré_de_query'; // Remplacez par ID d'une page

(async () => {
  try {
    await notion.pages.update({
      page_id: pageId,
      properties: {
        Status: {
          select: { name: 'Fait' },
        },
      },
    });

    console.log('Page mise à jour avec succès');
  } catch (error) {
    console.error('Erreur:', error);
  }
})();

Utilisez l'ID d'une page (de query-database.ts) pour updater le status. Seul Status change ici ; étendez pour d'autres props. Piège : IDs sont UUIDv4, copiez précisément. Idéal pour automatisations comme marquer tâches terminées.

Exemple de schéma JSON pour créer une database via API

create-database.json
{
  "parent": {
    "page_id": "votre_page_parent_id"
  },
  "title": [
    {
      "text": {
        "content": "Ma Database API"
      }
    }
  ],
  "properties": {
    "Name": {
      "title": {}
    },
    "Status": {
      "select": {
        "options": [
          {
            "name": "Todo",
            "color": "gray"
          },
          {
            "name": "En cours",
            "color": "yellow"
          },
          {
            "name": "Fait",
            "color": "green"
          }
        ]
      }
    },
    "Priority": {
      "select": {
        "options": [
          {"name": "Haute", "color": "red"},
          {"name": "Moyenne", "color": "orange"},
          {"name": "Basse", "color": "blue"}
        ]
      }
    }
  }
}

Ce JSON définit une database complète avec propriétés. Utilisez-le dans un script notion.databases.create(payload). Couleurs boostent la visibilité. Personnalisez options pour vos besoins ; Notion valide strictement les types.

Bonnes pratiques

  • Sécurisez le token : Jamais en dur dans le code, toujours via .env et variables serveur.
  • Limitez les queries : Utilisez filtres API (ex: filter: { property: 'Status', select: { equals: 'Todo' } }) pour éviter timeouts.
  • Versionnez vos databases : Dupliquez avant gros changements API.
  • Hybridez UI/API : Créez en UI pour prototyper, automatisez via code.
  • Rate limits : 3 req/s max ; ajoutez setTimeout en loops.

Erreurs courantes à éviter

  • 404 Not Found : Oubli de partager page/database avec l'intégration.
  • Invalid property : Propriétés API ne matchent pas la DB (ex: typo 'Statut' vs 'Status').
  • Token invalide : Copie incomplète ou régénéré sans update .env.
  • Pas de handler async : Toujours try/catch et await pour API calls.

Pour aller plus loin

Maîtrisez les formules Notion, embeds (Google Calendar, Figma) et webhooks avancés. Explorez la doc API Notion.

Découvrez nos formations Learni sur la productivité pour Next.js + Notion ou automatisations Zapier. Rejoignez la communauté Discord Learni Dev pour templates gratuits !