Aller au contenu principal

Bonnes pratiques de synchronisation

Ce guide répond aux questions les plus fréquentes que nous recevons lorsqu'un client connecte son système informatique à Stonal et commence à maintenir ses objets, données et documents synchronisés. Il complète les guides ingestion et recherche avec des recommandations pratiques tirées d'intégrations réelles.

Commencez par un chargement initial, puis laissez Stonal l'enrichir​

Avant de pouvoir maintenir quoi que ce soit synchronisé, vous devez réaliser un chargement initial unique qui amorce votre patrimoine dans Stonal. Il vaut la peine de bien comprendre cette première étape en elle-même, car les données ne circulent que dans un seul sens au départ — et parce que vous n'envoyez pas tout.

  1. Vous envoyez vos objets. À l'aide de l'API d'ingestion, vous poussez les objets que vous gérez déjà dans votre propre système : le sommet de la hiérarchie des objets, jusqu'aux lots inclus — BUILDING_GROUP, BUILDING, BUILDING_SECTION et RENTED_UNIT. Vous ne créez pas le contenu physique détaillé des bâtiments (pièces, équipements, plans) à ce stade.
  2. Stonal enrichit votre patrimoine. Stonal numérise les bâtiments et ajoute les objets physiques détaillés sous ce que vous avez envoyé — les LEVEL, les SPACE (pièces), les OPENING, les EQUIPMENT, et les PLAN d'étage. C'est la valeur que Stonal ajoute par-dessus vos données structurelles.
  3. Vous récupérez les données enrichies. Une fois les bâtiments numérisés, vous récupérez ces nouveaux objets — pièces, équipements, plans — avec l' API de recherche et vous stockez de votre côté ceux qui vous intéressent (en conservant l'uid Stonal).

Après ce chargement initial, les deux systèmes disposent de la vue complète et vous passez à la synchronisation continue et bidirectionnelle décrite ci-dessous : vous maintenez vos objets à jour via l'API d'ingestion, et vous récupérez les modifications de Stonal via l'API de recherche.

astuce

N'envoyez que les objets structurels que vous possédez réellement lors du chargement initial. Créer vous-même des pièces ou des équipements duplique ce que Stonal produit en numérisant les bâtiments — laissez l'étape d'enrichissement remplir le détail physique.

À quelle fréquence dois-je synchroniser ?​

Il n'y a pas de règle absolue — la bonne cadence dépend de la rapidité avec laquelle vos données source évoluent et du niveau de fraîcheur requis sur Stonal.

  • Une synchronisation une fois par jour est une bonne valeur par défaut et suffit pour la plupart des cas d'usage (structure des objets, propriétés, contrats).
  • Augmentez la fréquence pour les données qui changent souvent ou que les utilisateurs en aval s'attendent à voir rapidement.
astuce

Choisissez la fréquence la plus basse qui satisfait votre exigence de fraîcheur. Un traitement nocturne par lots est plus simple à exploiter et plus facile à surveiller qu'un flux en quasi-temps réel, et il suffit pour la grande majorité des intégrations.

Dois-je tout envoyer à chaque fois, ou seulement ce qui a changé ?​

N'envoyez que ce qui a changé. Un rechargement complet à chaque exécution est inutilement coûteux et de plus en plus lent à mesure que votre jeu de données grandit.

  1. Chargement initial — importez votre jeu de données complet une seule fois (voir Ingestion des données).
  2. Synchronisation incrémentale — à chaque exécution suivante, ne récupérez que les objets qui ont changé depuis votre dernière exécution avec le filtre de mise à jour différentielle de l'API de recherche (updatedAtAfter), puis réappliquez-les en upsert.
🔎 fetch only assets updated since the last sync
"search": {
    "updatedAtAfter": "2025-09-12T00:00:00"
}

Pour également détecter les objets supprimés depuis votre dernière exécution, ajoutez includeDeleted :

🔎 include deletions in the differential sync
"search": {
    "updatedAtAfter": "2025-09-12T00:00:00",
    "includeDeleted": true
}
astuce

Stockez l'horodatage de chaque synchronisation réussie et utilisez-le comme valeur updatedAtAfter pour l'exécution suivante.

Bonnes pratiques recommandées​

Stockez et utilisez l'uid de l'objet​

Chaque objet créé dans Stonal possède un identifiant unique stable, généré par Stonal : son uid. Il est distinct des identifiants externes que vous fournissez, qui relient l'objet à vos propres systèmes.

  • Continuez à stocker vos propres identifiants externes — c'est ainsi que vous reconnaissez l'objet de votre côté, et vous pouvez en attacher plusieurs par objet.
  • Stockez également l'uid renvoyé par l'API d'ingestion à leurs côtés. L' uid est le moyen le plus fiable de référencer un objet pour les mises à jour, et il est requis pour certaines opérations — par exemple, supprimer un objet et modifier un identifiant externe ne peuvent se faire que par uid.
info

La plupart des opérations d'écriture vous permettent de référencer un objet soit par son uid, soit par l'un de ses identifiants externes. Préférez l'uid lorsque vous en disposez.

Enseignements tirés d'autres intégrations​

  • Ajustez la taille de vos lots. L'API d'ingestion accepte plusieurs objets par requête. Nous recommandons de limiter les lots à pas plus de ~500 éléments et de réaliser quelques tests pour trouver la taille la plus performante pour votre charge utile — la valeur optimale dépend de ce que vous envoyez (objets, propriétés/données, relations) et du poids de chaque élément. Commencez plus petit et augmentez progressivement.
  • Demandez-nous des exemples de requêtes. Si vous n'êtes pas sûr de la façon d'exprimer un import ou une recherche en particulier, contactez le support API — nous nous ferons un plaisir de fournir une requête prête à l'emploi pour votre cas d'usage.
  • Signalez-nous lorsque la documentation n'est pas claire. Vos retours sur ces guides nous aident à les améliorer pour vous et pour le prochain intégrateur.
astuce

Besoin d'aide pour démarrer ? Contactez le support API par e-mail ou Slack — voir Démarrage pour savoir comment obtenir un compte et des identifiants.