Skip to main content
Utilisez ce guide pour exploiter une copie locale des données d’annonces sélectionnées par vos filtres Immoteur. Il associe un export complet pour le premier snapshot, des notifications en direct pour les mises à jour rapides et des exports delta pour réconcilier les changements dans le temps. Il ne s’agit pas d’une copie non filtrée de toutes les ressources Immoteur. Elle contient les annonces publiquement exportables qui correspondent actuellement aux filtres de votre service. La référence API générée reste la source de vérité pour les schémas de payload.

​
Configurez les deux services et démarrez le receiver

Créez deux services compatibles avec les mêmes filtres : un service de notifications en direct classified-notification-single ou classified-notification-batch, avec onlyNew=false, et un service d’export classified-export. Le service d’export est indispensable au baseline complet comme à la réconciliation delta. Les deux services peuvent viser le même receiver HTTPS, mais restent deux services distincts. Rendez ce receiver opérationnel avant de demander ou planifier le premier export. Si votre receiver limite les IP sources, autorisez les IP d’egress Immoteur avant tout test. Une pause conserve la configuration du service, mais annule ses exports en cours ; ne comptez pas sur la reprise pour livrer un batch déjà constitué pendant la pause. Gardez le handler HTTP minimal : persistez ou mettez la requête en queue, renvoyez 2xx, puis traitez-la dans votre propre worker. Consultez Livraison, tentatives et idempotence des webhooks pour le contrat du receiver, des timeouts, des en-têtes et des réessais.

​
Établissez le premier snapshot avec un export complet

Déclenchez un Export complet depuis le service classified-export pour établir le baseline. Il livre toutes les annonces qui correspondent actuellement aux filtres du service et qui sont publiquement exportables, dans un ou plusieurs chunks. Chaque élément est un snapshot public complet de Classified. Chaque payload de cet export contient le champ obligatoire exportType. Il indique le type effectivement livré pour l’ensemble de l’export et conserve la même valeur dans chaque chunk de données comme dans le message final. Pour un Export complet, sa valeur est full.
Le message final reprend le même exportType et contient un tableau items vide :
Ces extraits illustrent exportType et isComplete, mais ne constituent pas le schéma complet : chaque message contient aussi les champs obligatoires batchId, itemCount et batchCount (batchId vaut null dans le message final). Consultez la référence API générée pour leur contrat exact.

​
Traitez les notifications d’annonces en direct

Utilisez classified-notification-single pour une notification unitaire, ou classified-notification-batch pour un lot de un à dix snapshots Classified complets dont les identifiants sont distincts. Avec onlyNew=false, les deux modes donnent à votre copie locale des mises à jour rapides lorsqu’une annonce est créée ou lorsqu’un champ normalisé éligible change. Le batch reçoit le corps strict { "items": [...] }, sans les champs propres aux exports. Persistez le lot entier avant de répondre 2xx ; en cas d’échec, répondez non-2xx pour que le même événement puisse être réessayé. Persistez un registre de livraison incluant X-Immoteur-Service-Id et X-Immoteur-Event-Id avant d’accuser réception d’une notification en direct. Pour un batch, l’identifiant d’événement et le corps restent stables entre les réessais ; le X-Immoteur-Delivery-Id identifie chaque tentative HTTP. Conservez ce dernier pour le diagnostic, mais ne le prenez pas seul pour clé d’idempotence. Un revisit ne modifiant que meta.lastSeenAt est enregistré pour la réconciliation par export et ne produit pas de notification directe. Utilisez meta.lastModifiedAt pour les changements normalisés de la source et meta.lastSeenAt pour conserver le dernier revisit observé.

​
Réconciliez avec les exports delta

Un Export complet livre toutes les annonces qui correspondent actuellement aux filtres du service et qui sont publiquement exportables. Dans son payload, exportType vaut full.
Planifiez les exports delta tous les sept jours. Lorsqu’un Export delta demandé ne peut pas s’appuyer sur un baseline, notamment parce qu’aucun baseline réussi et compatible n’existe ou que les filtres de sélection ont changé, Immoteur livre un Export complet. Dans ce cas, exportType vaut full dans les chunks de données et dans le message final. Le payload envoyé au receiver n’expose ni le mode demandé ni la raison du repli. La modification de la seule URL de destination du webhook ne remet pas en cause la compatibilité du baseline pour un Export delta.

​
Rendez les écritures locales sûres face aux doublons et retards

Stockez chaque snapshot source par identifiant d’annonce, conservez le payload brut et gardez vos propres enrichissements dans des champs ou tables séparés. Ne laissez ni l’ordre d’arrivée, ni la position dans un chunk, ni le delivery ID, ni le nombre de réessais déterminer quel snapshot source prévaut. Lors de l’application d’un snapshot, privilégiez le meta.lastModifiedAt le plus récent. Lorsque le timestamp de modification est identique, vous pouvez conserver le meta.lastSeenAt le plus récent sans écraser des données normalisées plus récentes. status.current est un champ de cycle de vie ; ne déduisez pas une suppression du seul fait qu’un élément manque dans un export ultérieur. Un filtre modifié crée un nouveau périmètre de sélection et n’ordonne pas automatiquement de supprimer des données de votre base.

​
Interprétez la classification des programmes sans confondre les périmètres

Conservez séparément classified.id et propertyId dans votre modèle local. propertyId désigne le regroupement d’annonces qu’Immoteur associe à un bien immobilier. Dans un snapshot Classified, property.isNew et property.isProgram sont deux indicateurs indépendants fondés sur les éléments de la source. isNew signale que le bien est présenté comme neuf ou récent. isProgram signale une classification de programme, de vente sur plan ou d’offre en cours de construction ; l’annonce peut porter soit sur le programme entier, qui peut comprendre plusieurs lots, soit sur un lot identifié, et les deux champs peuvent valoir true. Une valeur false est conservée dans le payload lorsqu’elle est connue. L’absence de l’un de ces champs signifie que la valeur n’a pas pu être déterminée ; elle ne vaut pas false. Dans une ressource Property, Immoteur ne renvoie une valeur que si les valeurs connues de toutes les annonces actuellement rattachées sont concordantes ; aucune valeur connue ou une contradiction entre true et false laisse le champ absent. Une annonce Classified peut décrire le programme entier et son regroupement peut inclure des annonces de lots différents. Ne construisez pas l’historique de prix d’un logement unique en combinant les prix, les surfaces ou les nombres de pièces d’annonces rattachées au même propertyId. Consultez Choisir une ressource API pour le contrat complet et le filtre propertyIsProgram inchangé. Conservez les snapshots source avant vos calculs locaux. Une divergence entre surface habitable et surface de terrain relève d’une analyse distincte de la source et du traitement ; ne déduisez pas la surface habitable à partir de la surface de terrain.

​
Utilisez la copie locale pour l’analyse et l’enrichissement

Une fois les snapshots source stockés, exécutez vos propres analyses, jointures, scores, synchronisations CRM ou enrichissements dans votre base de données. Gardez ces valeurs dérivées séparées du snapshot Immoteur afin qu’une mise à jour source entrante reste un simple upsert et ne crée pas de conflit avec votre travail local.

​
Questions fréquentes des développeurs

​
Cette synchronisation copie-t-elle toutes les données Immoteur ?

Non. Elle copie les données d’annonces publiquement exportables qui correspondent actuellement aux filtres configurés pour votre service. Utilisez la référence API et la configuration du service pour comprendre le payload et la sélection exacts.

​
Puis-je compter sur l’ordre d’arrivée ou recevoir chaque événement une seule fois ?

Non. Les livraisons de webhook peuvent être réessayées et les exports peuvent utiliser plusieurs chunks. Persistez un registre d’idempotence pour les notifications directes et faites les upserts des snapshots par identifiant d’annonce.

​
Quand choisir un export complet ou delta ?

Commencez par un export complet du service classified-export. Gardez un service classified-notification-single ou classified-notification-batch actif, avec onlyNew=false, pour les mises à jour rapides, puis utilisez les exports delta du service d’export pour une réconciliation régulière. Un delta bascule automatiquement vers un export complet sans baseline récent compatible.

​
Dois-je supprimer un enregistrement local absent d’un export ultérieur ?

Pas automatiquement. Un export reflète son périmètre de filtre courant. Gardez les décisions de cycle de vie explicites et utilisez le snapshot d’annonce, notamment status.current, plutôt que d’interpréter une absence comme une instruction de suppression.