Notion : un seul contrat importé

Une fiche cliente Notion possède 37 contrats liés, mais son import ne laisse qu’une association dans le CRM. Le connecteur a pourtant parcouru toutes les réponses et son journal annonce une collecte terminée. Ce blocage pousse le commercial à rattacher les contrats à la main, sans comprendre pourquoi ils disparaissent au passage suivant. Avant d’accuser la limite de pagination, regardez quel identifiant votre transformation utilise pour conserver chaque relation.

En pratique, terminer une lecture ne garantit pas que son contenu traverse correctement le mapping. Dans une réponse de propriété Notion, l’identifiant de l’élément peut désigner la propriété commune à tous les résultats ; l’identifiant de la page liée se trouve un niveau plus bas. Une déduplication appliquée au mauvais champ transforme alors plusieurs contrats distincts en un seul emplacement, même lorsque toutes les pages de résultats ont été reçues.

Notre laboratoire fictif compare ces deux traitements sur 37 références. Le programme Python a réellement passé 62 contrôles : il montre la perte provoquée par la mauvaise clé, récupère les références attendues et sépare deux fiches clientes qui utilisent la même propriété. Il travaille sur des extraits JSON préparés selon la documentation, sans appel à Notion ni modification d’un CRM. Vous pourrez distinguer une lecture tronquée, une transformation qui écrase les éléments et une correspondance métier encore à qualifier.

Ce diagnostic concerne un raccordement Notion à vos données métier dont les relations ne sont plus fidèlement représentées dans l’application consommatrice. Il s’inscrit dans une intégration API entre les outils de travail et le SI. La question concrète est de retrouver les contrats liés au bon client, puis d’expliquer leur représentation attendue dans le CRM avant d’en remplacer les associations.

Dans quel cas : une fiche cliente perd ses contrats

Identifier la relation lue et l’association attendue

Dans ce scénario fictif, une base de clients et une base de contrats sont reliées dans Notion. Le métier utilise cette relation pour retrouver les documents d’un compte ; le CRM doit en recevoir une représentation définie par le projet. Dans le témoin, les 37 contrats sont des pages fictives identifiées séparément. Leur identifiant Notion ne devient pas automatiquement un numéro de contrat ni une clé CRM. Cette seconde correspondance doit être expliquée à partir du modèle effectivement installé.

La première vérification porte sur une référence précise que le commercial voit dans Notion mais ne retrouve pas dans son compte CRM. Conservez l’identité de la fiche source, celle de la propriété et celle de la page liée. Ces trois repères permettent de rechercher où la référence a disparu : réponse partielle, sortie du parseur, transformation vers une association cible ou décision de ne pas l’importer. Un simple total de requêtes réussies ne localise aucune de ces frontières.

Mesurer la perte au moment où elle apparaît

Le coût caché se révèle dans les contrats rattachés au mauvais compte, les échéances recherchées manuellement et les demandes de support rouvertes après une synchronisation. Comptez les références avant et après la transformation, avec le client concerné. Un passage de 37 éléments lus à une seule clé conservée signale une anomalie différente d’une lecture arrêtée à 25 références. Les deux situations peuvent donner une fiche incomplète, mais elles ne demandent pas la même correction.

Une équipe qui importe seulement des liens documentaires n’a pas le même besoin qu’un CRM qui pilote les obligations de chaque contrat. Dans ce second cas, le dossier doit aussi préciser le sens de l’association, les doublons métier possibles et le traitement des contrats retirés. Commencez par qualifier la perte de références ; n’utilisez pas cette réparation comme une autorisation implicite d’activer des suppressions automatiques ou de modifier les statuts contractuels du compte.

Lire les deux identifiants de l’élément de relation

Séparer la propriété et la page qu’elle référence

La référence des éléments de propriété distingue l’identifiant commun de propriété et l’identifiant de la page liée. Pour un élément de relation, results[].id désigne la propriété ; results[].relation.id désigne la page référencée. L’objet de métadonnées property_item décrit, lui aussi, la propriété demandée. Ce n’est pas un résultat supplémentaire à importer comme un contrat.

L’extrait fictif suivant ne contient que deux références pour rendre l’emboîtement lisible. Les deux éléments portent la même valeur r%3AaB au niveau de leur identifiant de propriété, mais deux pages différentes dans leur objet relation. Le programme complet applique cette distinction à ses 37 références. Cet extrait ne constitue ni une réponse capturée dans un espace client, ni une validation de tous les champs possibles d’une réponse Notion.

{
  "object": "list",
  "type": "property_item",
  "results": [
    {"object": "property_item", "id": "r%3AaB", "type": "relation",
     "relation": {"id": "00000000-0000-4000-8000-000000000001"}},
    {"object": "property_item", "id": "r%3AaB", "type": "relation",
     "relation": {"id": "00000000-0000-4000-8000-000000000002"}}
  ],
  "has_more": false,
  "next_cursor": null,
  "property_item": {
    "id": "r%3AaB", "type": "relation", "relation": {}, "next_url": null
  }
}

Le contre-exemple du laboratoire range les éléments dans un dictionnaire indexé par leur identifiant extérieur. Chaque contrat réutilise alors la clé de la même propriété et remplace la valeur précédente. À la fin, seule la dernière référence subsiste. Ce comportement est réellement exécuté par une fonction explicitement incorrecte du témoin ; il explique la perte produite par ce choix de clé, sans prétendre que tous les SDK ou connecteurs Notion commettent cette erreur.

Choisir la clé en fonction de l’objet que l’on conserve

Pour dédupliquer les pages liées dans la collection étudiée, le parseur utilise l’identité imbriquée de la référence, tout en gardant le contexte du client et de la propriété. Cela ne suffit pas encore à choisir l’association CRM : cette étape doit distinguer la page Notion, le contrat métier qu’elle représente et l’objet cible connu. Le même mot « identifiant » ne doit pas cacher ces rôles dans une règle de transformation ou dans une table de correspondance.

Le nom affiché de la propriété n’est pas non plus cette identité stable. Le témoin renomme son libellé « Contrats » en « Accords client » et retrouve la même propriété par son identifiant. Dans le raccordement réel, conservez l’identifiant retourné par l’API et qualifiez les changements de type. Une propriété renommée peut continuer à être suivie ; une propriété remplacée ou transformée demande une nouvelle vérification de son sens et de la forme de sa valeur.

Parcourir la propriété qui contient les références

Distinguer l’aperçu d’une page et la lecture de sa relation

La lecture d’une page Notion peut ne renvoyer qu’une partie des références d’une propriété. Pour une relation, le premier seuil à reconnaître est la limite documentée de 25 pages référencées dans cette réponse ; has_more: true indique qu’il en existe davantage. Les limites des propriétés de personnes, des mentions et des calculs ne doivent pas être assimilées sans examen à ce cas de relation.

La lecture d’un élément de propriété fournit la liste paginée correspondant à la relation, via GET /v1/pages/{page_id}/properties/{property_id}. C’est cette valeur qu’il faut parcourir lorsque l’aperçu est insuffisant. Demander davantage de fiches clientes dans une autre requête ne complète pas les références internes d’une fiche déjà reçue. Le journal doit donc distinguer les pages clientes lues et les pages de résultats nécessaires pour une propriété donnée.

Conserver le curseur sans se tromper de niveau JSON

Le parcours de propriété suit next_cursor, transmis comme start_cursor à la demande suivante, jusqu’à la fin indiquée par has_more. L’URL de suite est imbriquée dans property_item.next_url. Le témoin exécute aussi un lecteur volontairement erroné qui cherche cette URL au premier niveau : il s’arrête après ses 20 premiers résultats. Ce second défaut ne doit pas être confondu avec l’écrasement par identifiant, qui n’en conserve qu’un malgré deux réponses fournies.

Les conventions de pagination de l’API demandent de traiter le curseur comme une valeur opaque. Le laboratoire prépare deux lots de 20 puis 17 références ; ce découpage est choisi pour l’essai et ne décrit pas une taille de réponse garantie. Une réponse courte ne remplace pas l’état de fin. Le parseur vérifie la chaîne des curseurs reçus, sans fabriquer un numéro de page ni interpréter la structure de leur contenu.

Exercice corrigé : retrouver les 37 références sans les écraser

Comparer les sorties réellement produites par les lecteurs

Le programme d’inventaire des identifiants de relation a passé 62 contrôles sous Python 3.14.8, avec la bibliothèque standard. Il produit les extraits fictifs, exécute deux lecteurs incorrects puis le lecteur qui conserve l’identité des pages liées. Le résultat compare 25 références dans l’aperçu, une seule après déduplication extérieure, 20 après arrêt au mauvais niveau et 37 dans la collection correctement parcourue.

python3 -B relation_item_identity_inventory.py
# checks_passed : 62
# observed_local_counts.fixture_contracts : 37
# observed_local_counts.inline_preview : 25
# observed_local_counts.wrong_outer_id : 1
# observed_local_counts.wrong_top_level_next_url : 20
# observed_local_counts.correct_nested_reference_id : 37

L’enveloppe Reply appartient au laboratoire : elle associe une fixture au client, à la propriété, à la version et au curseur de la requête étudiée. Ces informations ne sont pas présentées comme des champs supplémentaires retournés par Notion. L’exercice ne possède aucun token, ne réalise aucune requête REST et n’écrit dans aucun CRM. Il vérifie une transformation locale sur le profil de documentation consulté, pas les accès ni le comportement d’une installation cliente.

Exercer l’interruption et les références répétées

Si la seconde réponse manque alors que la première annonce une suite, le lecteur lève une erreur de pagination interrompue et conserve les 20 identités déjà lues comme diagnostic partiel. Il ne les annonce pas comme une collection terminée. Un second scénario ajoute une référence répétée entre les deux lots : le programme observe 38 éléments bruts et retrouve 37 pages distinctes. Ce doublon est une donnée adversariale de l’essai, pas une promesse sur l’ordre ou l’unicité de chaque réponse native.

Le seuil de recette de ce cas est de zéro référence manquante parmi les 37 identités préparées. Le programme vérifie également les types attendus, les curseurs incohérents et les réponses appartenant à une autre propriété. Le booléen false est un état de fin valide ; sa combinaison avec une suite non nulle est examinée comme une incohérence du profil local. Un nombre ou une chaîne à la place du booléen est refusé, sans inventer un nouvel état de pagination.

Garder la fiche cliente autour de la collection

Éviter la déduplication globale par propriété

Une propriété de relation appartient au schéma utilisé par plusieurs pages clientes. Retrouver le même identifiant de propriété sur ces pages ne signifie donc pas qu’elles partagent une seule collection. Le témoin lit une seconde fiche avec deux références déjà présentes dans la première. Il conserve deux collections distinctes, de tailles 37 et 2, rattachées chacune à sa page source. Une fusion globale par propriété ferait perdre cette séparation avant même que le mapping CRM commence.

La portée d’un doublon doit être définie à l’étape où il est traité. Une référence répétée dans la lecture d’une même relation peut être regroupée pour l’inventaire local. La présence de la même page liée dans deux fiches demande une interprétation métier : est-ce un document partagé, une erreur de rattachement ou une situation autorisée ? Le lecteur conserve les deux contextes pour permettre cette décision. Il n’invente pas une règle d’exclusivité des contrats entre comptes CRM.

Le contrat d’entrée du lecteur rattache chaque réponse à une page cliente, une propriété, une version et un curseur demandés. Une enveloppe locale qui annonce un autre contexte est refusée. En sortie, la collection conserve la page source et la propriété étudiée. La responsabilité de l’adaptateur est de relier chaque réponse à sa demande d’origine : le JSON de relation ne fournit pas seul toutes ces informations de transport. Dans une exécution parallèle ou en batch, l’ordre d’arrivée des workers ne doit pas décider du client auquel attribuer les références.

Qualifier la visibilité avant de remplacer les associations CRM

Interpréter une relation vide avec son contexte d’accès

La référence des valeurs de propriété précise qu’une connexion doit aussi disposer de l’accès à la base liée. Un accès manquant peut laisser des relations vides ou des calculs incomplets. Un tableau vide ne constitue donc pas, isolément, une instruction de retirer les associations du CRM. Le responsable Notion vérifie le partage et le périmètre attendu avec l’intégrateur, en conservant seulement les accès nécessaires au besoin convenu.

La lecture de propriété demande la capacité de lire le contenu. La documentation distingue un manque de capacité, qui peut produire un HTTP 403, d’une page ou propriété introuvable ou inaccessible, qui peut produire un HTTP 404. Ces situations doivent rester attribuées à leur demande source dans le diagnostic. Une absence de résultat exploitable ou un refus d’accès ne démontre pas qu’un commercial a retiré le contrat de la relation. L’exercice n’effectue aucun de ces contrôles d’accès sur un compte réel.

Importer une relation avec une intention de remplacement explicite

Une lecture terminée dans le témoin fournit les références visibles de ses fixtures ; elle ne certifie pas un instantané atomique d’une base en cours de modification. Le projet doit choisir quelles différences peuvent ajouter un lien, demander une revue ou retirer une association cible. Si une écriture est prévue vers Notion, son contrat mérite aussi attention : la mise à jour d’une relation en remplace la valeur. Compléter une relation à partir d’un aperçu incomplet peut donc en perdre une partie au moment de l’écriture.

Le lecteur publié se limite aux relations. Les propriétés de formule et de rollup possèdent d’autres formes de réponse et d’autres règles de calcul ; un résultat unsupported n’est pas un zéro à importer. Le programme refuse les métadonnées d’un autre type au lieu de les transformer en contrats. Pour transférer un montant ou une échéance calculés, il faut leur recette propre et les données effectivement accessibles. Les codes d’erreur du fichier restent ceux du laboratoire, séparés des statuts HTTP documentés par Notion.

Erreurs fréquentes : clôturer l’import au dernier appel reçu

Contrôler le résultat du parseur et sa correspondance cible

La première erreur consiste à confondre fin de pagination et conservation des éléments. Contre-intuitivement, un journal peut annoncer deux réponses reçues et une lecture finie pendant que le dictionnaire ne contient plus qu’un contrat. Le monitoring doit rapprocher les éléments bruts, les identités distinctes retenues et les associations proposées pour un même client. Un écart important entre ces compteurs désigne un point de transformation à examiner ; il ne suffit pas d’afficher un statut global « import réussi ».

La deuxième erreur est de répéter le traitement sans corriger la clé. Le retry reproduit alors l’écrasement avec les mêmes données, et augmenter la taille des lots peut rendre la perte plus difficile à observer. L’idempotence de l’association CRM doit être définie après qualification de sa source et de son sens. Elle protège un effet métier déterminé ; elle ne restaure pas les références qu’un mauvais index a déjà supprimées de la représentation intermédiaire.

La troisième erreur consiste à réparer le parseur sans revoir les clients touchés. Le runbook doit retrouver les dossiers importés avec l’ancienne règle, comparer les références encore disponibles et proposer une reprise expliquée. La queue conserve le client, la propriété, la version du mapping et le résultat du rapprochement. La latence d’une requête et le délai de résolution d’une fiche incomplète restent des mesures distinctes. Un backoff utile face à une réponse limitante ne remplace pas l’analyse d’un contrat silencieusement perdu dans la transformation.

Plan d’action : suivre une référence jusqu’au compte CRM

Commencer par la clé qui a remplacé les autres contrats

La première action est de reprendre une fiche qui n’a conservé qu’une association et de comparer ses identités à trois étapes : lecture de propriété, sortie du parseur et proposition CRM. Le responsable du connecteur explique les clés réellement employées. Le métier confirme ce que représentent les pages liées et les associations attendues. Cette recette se joue d’abord sur des données autorisées, avec une transformation observée sans effet, avant d’ouvrir une correction des dossiers existants.

1. Identifier la page cliente, la propriété de relation et une référence de contrat manquante dans la cible.
2. Comparer les éléments reçus avec les clés conservées par la transformation, notamment l’identifiant extérieur et celui de la page liée.
3. Parcourir la propriété jusqu’à sa fin déclarée et distinguer cet inventaire de l’aperçu de la fiche.
4. Exercer une interruption, un élément répété et deux clients utilisant la même propriété sans mélanger leurs contextes.
5. Qualifier les accès, le mapping métier et l’intention d’ajout ou de retrait avant de proposer des associations CRM.
6. Rapprocher un compte corrigé puis retrouver les autres dossiers traités avec la règle défectueuse pour organiser leur reprise.

Un connecteur Notion adapté à vos objets métier doit également rendre sa version identifiable. Le profil du laboratoire se fonde sur le contrat 2026-03-11 consulté en octobre 2026 ; il refuse une version différente pour éviter une interprétation silencieuse hors de ce périmètre. Ce choix de recette ne décrit pas le support de toutes les versions de l’API. Dans votre installation, vérifiez le paramétrage du client ou du SDK et les formes réellement reçues avant de reprendre le mapping.

Comparer d’autres pertes de sens dans les données lues

Le cas Airtable dont le montant change sans nouvelle date sur le devis montre une sélection qui ne couvre pas toutes les dépendances d’un calcul. Le dossier Dataverse et des codes clients ERP refusés dans une clé alternative examine une autre frontière d’identité. Ces mécanismes ne définissent pas le format des relations Notion ; ils aident à poser la question du rôle exact de chaque valeur avant sa transmission.

Pour le présent incident, la preuve utile reste le chemin d’un contrat connu. Le support retrouve son identifiant de page dans la lecture, son client de rattachement et l’association prévue dans le CRM. Il peut alors distinguer une référence jamais reçue, une référence écrasée par le parseur et une association refusée selon sa règle métier. Cette séparation donne une prochaine action à chaque dossier, sans demander au commercial de recréer des liens qui risquent de disparaître au prochain passage.

Conclusion : conserver le contrat que la propriété désigne

Les 37 contrats du témoin ne manquent pas tous pour la même raison selon le lecteur employé. L’aperçu en expose 25, le mauvais niveau de pagination en conserve 20 et la mauvaise clé d’identifiant n’en laisse qu’un. Le lecteur correct retrouve les 37 références préparées. Ces résultats locaux rendent l’enquête plus précise : la pagination, l’identité de propriété et l’identité de page liée doivent être vérifiées là où chacune intervient.

Une intégration Notion reliée à votre CRM garde ensuite le contexte de la fiche et le sens de son association métier. Le contrat retrouvé n’est pas forcément un contrat à recréer, et une lecture vide reste à interpréter avec ses accès. Le rapprochement du compte cible confirme la correction attendue une fois cette intention établie, avec une responsabilité claire pour les dossiers qui demandent encore une décision.

Pour cadrer cette intégration API de vos données clients, Dawap peut suivre une référence perdue depuis la propriété Notion jusqu’à l’association CRM proposée. Le travail d’expertise précise la clé à conserver, les lectures nécessaires et les comptes concernés par la reprise. Le commercial retrouve ainsi ses contrats rattachés au bon dossier et une explication durable de leur import, au lieu de les ajouter de nouveau après chaque passage du connecteur.