Intégration API Notion
Nous développons votre connecteur Notion
Nous branchons Notion à votre produit : le rendez-vous clos écrit le compte-rendu, un statut Validé lance la facture, le site lit ce que l'équipe publie.
- Équipe produit senior
- connecteurs Notion en production
- du cadrage au monitoring
À quoi sert l'API Notion et pourquoi l'intégrer dans votre plateforme ?
Notion est l'outil de connaissance et de suivi léger de référence pour beaucoup d'équipes. Son API permet à votre application d'écrire des pages, de lire une base, ou de réagir quand un statut change. On l'intègre pour que tout cela vive dans votre produit : compte-rendu écrit à la clôture du rendez-vous, statut Validé qui lance la facture ou le SIRH, contenu publié dans Notion et lu par le site au build. Notion reste l'espace d'équipe ; votre application reste la source de vérité. On ne fait pas de Notion un ERP déguisé.
Ce que Notion change dans votre plateforme
Compte-rendu écrit à la clôture du RDV
Le produit crée la page dans la base. Personne ne recopie l'ordre du jour le soir dans un second outil.
Statut Validé qui lance la facture
Le changement de statut déclenche le flux métier. Notion n'est pas la compta : c'est le signal qui part vers votre SI.
Onboarding RH branché sur le SIRH
Une page Validé crée le collaborateur avec l'id métier. Pas de double saisie entre Notion et le SIRH.
Contenu publié dans Notion, lu par le site
L'équipe édite où elle travaille déjà. Le site consomme l'API au build. Un CMS léger, pas un second back-office.
Ce que ça change dans votre produit
La technique au service d'un résultat mesurable : écriture depuis le produit, statut qui lance le métier, CMS sans second back-office.
L'équipe n'ouvre plus un second back-office
Commande et compte-rendu s'écrivent dans Notion depuis le produit. L'info vit où l'équipe travaille déjà.
Le statut Notion déclenche votre SI
Validé lance facture ou SIRH. Ce n'est plus un statut cosmétique, c'est un événement métier.
Le site lit ce que le métier publie
Notion comme CMS léger. Pas de portail éditorial parallèle à maintenir.
Notion reste une projection, pas le SI
Votre produit garde les identifiants et les règles métier. Notion affiche et déclenche ; il ne devient pas un ERP improvisé.
Comment nous livrons votre connecteur Notion
Cadrage
Où Notion entre dans votre produit : comptes rendus, validation, RH, CMS. Bases, token ou OAuth, version d'API. URL webhook définitive avant activation.
Schéma
Schéma aligné sur vos objets métier : data sources, propriétés uniques d'upsert, plafond rich text 2 000. Un connecteur databases 2022 se réécrit ici.
Développement
Connecteur branché sur l'écriture depuis le produit et les webhooks vers le métier. Version figée, file unique, Retry-After, pagination has_more.
Monitoring
429 rate_limited, 529 service_overload, verification_token hors git. Upgrade guidé à chaque changelog.
Ce que l'API apporte à votre plateforme
- Écrire la page depuis le produit
- Compte-rendu, fiche, entrée de base : l'objet métier s'ancre dans Notion avec une propriété unique d'upsert.
- Déclencher le métier sur un statut
- Webhooks de connexion : Validé lance facture ou SIRH. URL HTTPS, token one-shot, pas de poll à 3 req/s.
- Alimenter le site ou le prévisionnel
- Query data sources et blocs enfants. Le site ou le SI lit Notion en projection, avec cache sous le plafond de débit.
- Tenir version et débit en production
- Notion-Version figée (2026-03-11), ~3 req/s, Retry-After. Sans ces garde-fous, le connecteur casse au premier changelog.
Le vocabulaire de l'API Notion
- Notion-Version
- En-tête obligatoire. Sans lui : 400 missing_version. Version courante des guides : 2026-03-11. Le versionnage est le sujet, pas « l'API Notion » en général.
- Data source
- Le nom actuel de ce qui s'appelait database. Les guides 2025-09-03 et 2026-03-11 ont renommé le modèle. Un connecteur databases 2022 est à réécrire.
- 3 req/s
- Par connexion, burst toléré, plus un plafond workspace partagé selon le plan. Une sync naïve de 5 000 pages = ~30 min au mieux. File et cache.
- 529 service_overload
- Même traitement qu'un 429 : Retry-After, jitter, plafond d'essais. Ce n'est pas une erreur métier. Pas de retry sur 401/403.
- verification_token
- One-shot à coller dans le portail webhook. Hors git. Après vérification, changer l'URL recrée l'abonnement : l'URL prod se choisit avant d'activer.
- Rich text 2 000
- Plafond par propriété, URL 2 000. Un contrat HTML collé dans une propriété casse. On tronque ou on passe en blocs enfants.
Les contraintes réelles de l'API Notion
Sans Notion-Version, c'est 400
Un client HTTP nu casse. Le SDK pose l'en-tête, un fetch oublié non. L'upgrade 2026-03-11 change trash/archive et les data sources : tests de contrat JSON à chaque bump.
3 req/s et le plafond workspace
Deux limites, deux reasons dans le 429. Un écran qui « lit Notion en live » a besoin d'un cache. La file unique anticipe, elle ne réagit pas seulement.
L'URL webhook est figée après vérif
Prévoir l'URL définitive (prod) avant d'activer. Recréer l'abonnement n'est pas un rename. Le token one-shot ne se relit pas dans git.
Un PAT n'est pas un produit
Token interne, OAuth public, PAT : trois régimes, trois périmètres. Un PAT ne tient pas un multi-workspace client. Ça se tranche au cadrage.
Webhooks Notion ou polling à 3 req/s ?
Deux façons de réagir à Notion. Le plafond de 3 requêtes par seconde rend le poll naïf visible dès la première base réelle.
| Critère | WebhooksConnexion | Polling3 req/s |
|---|---|---|
| Débit | L'événement utile | ~3 req/s + plafond workspace |
| Délai | Poussée, ACK 2xx | La période du cron |
| 5 000 pages | Pas le sujet du webhook | ~30 min au mieux |
| URL | Figée après vérification | Aucune |
| Schéma | data_source.schema_updated | À relire soi-même |
| Sync initiale | Import borné + webhooks ensuite | Souvent le seul outil, trop lent |
| Le bon cas | Case cochée, facture, SIRH | Reprise ponctuelle, cache |
Les deux cohabitent : un import initial paginé, puis des webhooks. Un poll en live sur un écran utilisateur passe par un cache, pas par l'API à chaque clic.
Ce que nous mesurons sur une intégration Notion
Les autres outils de productivité
Si Notion n'est pas l'espace d'équipe branché à votre produit, ces options se discutent au cadrage.
NotionNous développons votre connecteur NotionCette page
SlackL'alerte et l'action, quand la page Notion n'est pas le bon canal.
JiraLe ticket et le workflow, quand Notion ne suffit plus à tracer.
AirtableLe tableur structuré, quand la base ressemble déjà à une grille.
MetabaseNous développons votre connecteur MetabaseOn combine Notion avec
La stack autour de Notion quand on le branche dans un produit ou un site.
Notion : vos questions
On la branche sur vos touchpoints produit : écriture de page à la clôture du RDV, webhook Validé vers facture ou SIRH, lecture CMS pour le site. Techniquement : Notion-Version figée (2026-03-11), data sources et propriété unique d'upsert, file sous 3 req/s, Retry-After, webhooks avec URL prod avant vérification. La partie sensible n'est pas POST /pages, c'est le parcours produit, la version et le plafond de débit.
Parce que Notion versionne le contrat JSON par date. Sans Notion-Version : 400 missing_version. La version 2026-03-11 change la sémantique trash/archive, les opérations de blocs, et introduit des types transcription / notes. Data source a remplacé database. Un connecteur écrit en 2022 sur « databases » est à réécrire. Nous figeons la version en configuration, posons des tests de contrat, et guidons l'upgrade au changelog, plutôt que de suivre latest en silence.
File unique par connexion, pas deux workers indépendants. Respecter Retry-After, traiter 529 comme 429, ne pas retenter un 401/403. Le plafond workspace s'ajoute : le 429 porte additional_data.rate_limit_reason (public_api_request_rate_limit ou public_api_space_request_rate_limit). Une sync de 5 000 pages prend ~30 min au mieux. Tout écran utilisateur passe par un cache. Les webhooks évitent de poller pour une case cochée.
Ce n'est pas le même métier. Un consultant Notion structure les bases, les vues, les habitudes d'équipe. Un intégrateur (nous) branche l'API sur votre application : écriture depuis l'ERP, webhooks vers la facture, CMS, RAG interne. Les deux se suivent souvent. Si votre besoin est de former l'équipe à Notion, ce n'est pas cette page. Si votre besoin est qu'une page Validé lance un flux dans le SIRH ou le site, si.
Un premier flux utile, typiquement l'écriture d'une page à la clôture d'un rendez-vous avec propriété unique, se livre en deux à trois semaines. Une chaîne complète avec webhooks vers le métier, CMS site, plusieurs data sources et OAuth multi-workspace demande plutôt six à huit semaines. La durée dépend surtout des touchpoints à brancher, du schéma et du volume à paginer. Nous cadrons le périmètre en amont et donnons une estimation ferme avant de commencer.
Un projet d'intégration Notion ?
Parlons-en. 30 minutes pour cadrer où Notion entre dans votre plateforme (compte-rendu, validation, CMS) et vous dire franchement ce que 3 req/s tiennent.
Parler de mon projet Notion