Passer au contenu principal
TransactionsContactsRGPDMatchActivitésBreaking
Périmètre de la clé à la création d'un lead, consentement d'un contact existant, adresse renvoyée à la création, biens professionnels, zones en cercle
⚠️ Point de rupture : vérifiez settings.allocation de vos créations de leads, les canaux que vous omettez sur POST /contact, et les pourcentages d’honoraires que vous envoyez à PATCH /sale.
  • Périmètre de votre clé : sur POST Sale, POST Acquisition et POST Rental, settings.allocation.agencyGroupId doit être le groupe de votre clé, et agencyId, s’il est fourni, une agence de GET Agencies. Sinon l’API répond 400, message préfixé du nom de la route (Agency group is not in the authorized scope of this LinkedAPI, Agency is not in the authorized scope of this LinkedAPI), et rien n’est créé. Reprenez les identifiants de GET Agencies, jamais ceux des exemples.
  • Consentement d’un contact existant : sur POST Contact sans journey, quand le contact existe déjà, un canal que vous ne citez pas n’est plus modifié ; seul un false explicite retire un consentement. Si vous comptiez sur l’omission d’un canal pour le retirer, envoyez false. Sur un nouveau contact, rien ne change. Voir Consentement à la prospection.
  • Adresse dans la réponse : POST Sale et POST Rental renvoient transaction.property.addressData et transaction.property.addresses, l’adresse reconnue et enregistrée, au format de GET. Elle n’est pas renvoyée si la fiche est attribuée à une agence que votre clé ne couvre pas.
  • Pourcentage d’honoraires : sur PATCH Sale, hors du mode value, un mandate.commissionPercentage hors de 0 (inclus) à 100 (exclu) est refusé (400). Il faisait jusqu’ici passer le mandat en montant fixe. Renvoyer la valeur déjà enregistrée passe toujours.
En production depuis le 28 octobre, sans changement de votre côté :
  • Nouvelles agences : une agence ouverte dans votre groupe après la création de votre clé entre d’elle-même dans son périmètre. GET Agencies la liste, et ses fiches se lisent et s’écrivent comme celles des autres agences.
  • Durée d’un consentement accordé par PATCH : PATCH Contact applique au courriel et au SMS consent.durationYears, ou trois ans, comme la création. Sans durationYears, il appliquait jusqu’ici le réglage de durée de l’agence.
  • Biens professionnels : property.vatRegime (subject, exempt) et property.propertyTaxResponsibility (owner, tenant), en lecture et en écriture sur les ventes et les locations. Les étiquettes DPE d’un bien professionnel sont gardées telles que transmises, sans calcul depuis les valeurs.
  • Zones en cercle : une zone geometry peut porter center et radius (en km), en écriture sur POST Acquisition et en lecture sur GET Acquisition.
  • Offres d’un match : en charge partagée, une offre saisie dans Avest peut porter la part vendeur des honoraires (data.sellerAgencyCommission). Un PATCH qui ramène agencyCommission sous cette part est refusé (400). Voir Offres d’un match.
  • Activités : un changement d’étape d’une vente fait par Avest seul apparaît dans GET Activities (changeStep, avec data.isAutomatic: true).
  • Recherche en texte libre : « Paris 15 » ou « Lyon 3 » trouvent aussi les fiches du code postal de l’arrondissement.
TransactionsActivitésPlanningDocumentation
Documentation alignée sur la prod : honoraires, étapes de vente, déduplication, limites de débit
Aucun changement de comportement de l’API : la documentation décrit désormais ce que l’API fait réellement sur les points ci-dessous.
  • Honoraires en euros : agencyCommission est un montant, pas un pourcentage (5 donne 5 €). Le pourcentage se saisit avec commissionType: "percentage" et commissionPercentage. sellPrice est le net vendeur, le prix affiché se calcule seul. Voir POST Sale.
  • Type de mandat : exclusive, semiExclusive ou notExclusive. La valeur simple, que la doc citait, est refusée.
  • Vente créée à l’étape rendez-vous : envoyez settings.step: "RDV" et appointment dans la même requête. Un changement d’étape vers QUL à DLV par PATCH Sale clôt les activités à faire de la fiche, rendez-vous compris, et peut lancer les séquences de l’agence.
  • Activités : sur une vente jusqu’à DLV, créer un appel, une tâche, un message, un email ou un rendez-vous clôt les autres activités à faire. Un owner hors des agences de la clé reçoit 400, et non 403, sur POST comme sur PATCH Activity.
  • Adresse : si Google ne situe que la ville, la vente est enregistrée sans numéro ni rue, et la réponse reste un succès. Contrôlez property.addressData.
  • parsingCustomId est enregistré, mais n’intervient pas dans la déduplication. Voir Déduplication.
  • GET Users liste les collaborateurs de tout le groupe d’agences, sans dire à quelle agence chacun appartient.
  • Déduplication : une acquisition ou une location est retrouvée quelle que soit son étape, et une location archivée est rouverte. Sur une fiche retrouvée, settings.step est ignoré. Voir Déduplication.
  • PATCH Sale : une vente sans responsable ne sort de STK, TRN, PQUL, ARC, SLD ou TARC qu’avec owner dans la même requête, sinon l’étape reste inchangée avec un 200. Passer en STK supprime les activités non clôturées. Les motifs stepUpdateReason sont listés et contrôlés selon l’étape. offer n’est enregistrée qu’à partir de MND.
  • Limites de débit : le compteur d’une route est tenu par groupe d’agences et par chemin exact, et une limite globale de 200 requêtes par 10 secondes s’applique à chaque clé. Voir Authentification.
  • Planning de permanence : weekNumber va jusqu’à 53 les années longues. 2026 en compte 53 (du 28 décembre 2026 au 3 janvier 2027) : alimentez-la, sinon ses leads partent en pioche. Un type de planning inconnu répond 404.
  • Valeurs corrigées : mainType business_assets et lease_transfer ; civilité mr ou mme ; critère acquéreur excluded, bikeShed et mortgage booléens ; valeurs de lecture de GET Acquisition ; énergies solar, geothermal et eau chaude individuelle ; loggiaAmount et loggiaSurface sur le bien.
  • Lecture : GET Users et GET User renvoient aussi les collaborateurs désactivés, sans indicateur ; les transactions de GET Contact sont un résumé ; GET Match renvoie sale et acquisition à null et tags à [] ; sortOrder s’envoie avec sortField.
  • POST Sale : transaction.property est requis, un objet vide suffit. Sinon 400 Invalid transaction : property required. settings.disableAlerts ne coupe que l’email d’alerte : la notification Slack de l’agence part quand même.
  • GET Sale : customId est sensible à la casse. mandate peut être présent avant MND, avec mandateHistory, l’historique des modifications du mandat. property.addressData porte aussi department et region.
  • GET Activities : file vaut null sans fichier stocké par Avest, et file.url peut valoir null. Un document signé électroniquement peut remonter sans lien de téléchargement.
ContactsRGPDMatchTransactionsBreaking
Consentement : date et mention obligatoires ; MVST exige une visite ; honoraires partagés
⚠️ Point de rupture : des requêtes acceptées jusqu’ici sont désormais rejetées en 400.
  • Consentement : consent.date obligatoire dès qu’un canal est consenti (true, ou annoncé par journey) sur POST /contact et PATCH /contact/{contactId}. Il n’est plus daté par défaut à l’instant de l’appel. Erreur : consent.date is required when a channel is granted.
  • Consentement téléphonique : mention obligatoire. Dès que phone est consenti, transmettez la mention affichée à la personne : wordingText (texte exact), wordingVersion et locale. Les trois parcours annonçant le téléphone, un journey les exige aussi, sauf "phone": false. Erreur : consent.wordingText is required when phone is granted (idem pour les deux autres champs).
  • Renvoi d’un consentement : un true sur un canal déjà consenti n’est enregistré que si sa date est postérieure au recueil déjà enregistré. Sinon il est ignoré et ne prolonge ni le consentement ni la conservation ; PATCH renvoie alors consentChanged: false si aucun autre canal ne change.
  • Canal retiré puis renvoyé : sur un canal retiré depuis (désinscription, retrait par l’agence, false transmis), un true transmis rétablit le consentement, y compris le renvoi d’un accord déjà transmis. Ne renvoyez pas un consentement déjà transmis, et ne transmettez true sur un canal retiré que pour un nouvel accord, donné par la personne après son retrait.
  • Appels refusés : un appel refusé n’a créé ni modifié aucun contact. Rejouez vos appels refusés depuis le 21 octobre avec la date de recueil d’origine et la mention.
  • Conservation : consent.retentionDurationYears ne peut que raccourcir la durée réglée par l’agence (au-delà, elle est ramenée à celle-ci, sans erreur), et la fin de conservation part de l’accord le plus récent, et non plus de l’instant de l’appel.
  • Contact supprimé : un PATCH Contact dont le consent modifierait un contact supprimé définitivement reçoit 409 (errorCode: CONTACT_DELETED).
  • PATCH Match : MVST exige une visite active. Sans visite active (ni annulée ni supprimée) sur le match, la requête est refusée en 400 avec errorCode: VISIT_DATE_REQUIRED (Visit date required to plan a visit). Créez la visite avec POST une visite : elle fait passer le match en MVST.
  • Qualifier un acquéreur vers MVST exige originMatch.visitStartAt. Sinon l’API répond 400 (errorCode: VISIT_DATE_REQUIRED), et la fiche n’est pas qualifiée.
  • Statut des visites : derivedStatus se calcule sur le jour calendaire de l’agence, dans son fuseau. Une visite du jour reste planned jusqu’à minuit, heure de l’agence.
  • Honoraires partagés : en charge both, mandate et offer portent sellerAgencyCommission et sellerAgencyCommissionPercentage, en lecture comme en écriture. Le commissionPercentage d’une offre en montant fixe est désormais renvoyé. Voir GET Sale.
  • Attribution : la priorité contact passe par le responsable de la fiche la plus récente du contact réellement travaillée par un collaborateur, puis par le responsable du contact. Voir POST Acquisition.
Voir Consentement à la prospection.
ActivitésEndpoints
Activités : modifier et supprimer une note ; types de clé
Une note créée par erreur ou mal saisie ne se corrigeait que dans l’interface Avest. Elle se gère désormais depuis votre outil.
  • Corriger une note : PATCH Activity accepte content, qui remplace le texte d’une note. Même mise en forme qu’à la création (texte brut ou HTML). Refusé sur tout autre type d’activité.
  • Supprimer une note : nouvelle route DELETE Activity (DELETE /external-integration/activity/{activityId}). Suppression définitive, réservée aux notes. Les tâches, appels et rendez-vous se clôturent, et les visites et offres s’annulent.
  • Types de clé : trois types, lecture seule, lecture-écriture (par défaut) et lecture-écriture + suppression. Le dernier est accordé sur demande, au cas par cas : une suppression est définitive. Sans lui, un DELETE reçoit 403. Voir Types de clé.
  • Connaître sa clé : nouvelle route GET Key (GET /external-integration/key), qui renvoie le type de votre clé et les méthodes qu’elle autorise.
  • Chaque page de route indique désormais la clé requise.
ActivitésEndpoints
Activités : les paragraphes d'un texte brut sont conservés
POST /activity : un data.content en texte brut s’affiche désormais avec ses paragraphes. Séparez-les par une ligne vide (\n\n) ; un \n simple reste un retour à la ligne. Le texte est converti en HTML à l’enregistrement — GET /activities renvoie cette version HTML. Un content déjà en HTML est enregistré tel quel : rien à changer si vous suivez la recommandation précédente.
AuthentificationDocumentation
Codes d'erreur d'authentification : la doc dit désormais ce que l'API renvoie vraiment
Aucun changement de comportement de l’API : cinq endroits où la documentation ne décrivait pas la réponse réelle sont corrigés. Si vous déboguez une intégration, ce sont les points qui vous faisaient perdre du temps.
  • 403, pas 401, quand le header Authorization est absent. La doc annonçait 401 et aucune route ne déclarait de 403 ; l’API renvoie 403 Not authorized to access this resource. Les 403 sont désormais déclarés sur les 31 opérations de la référence.
  • Le message du 401 est Invalid bearer token, pas Unauthorized. Les pages de routes montraient un message qui n’a jamais été renvoyé.
  • Une clé sans groupe d’agences reçoit 400 LinkedAPI agencyGroup is required, et non 401 comme l’annonçait le guide Authentification.
  • Les niveaux d’accès sont documentés. Une clé est en lecture seule ou en lecture-écriture : un POST / PATCH avec une clé en lecture seule reçoit 403 Not authorized to access this resource — la même réponse qu’une requête sans token. Un 403 sur vos seules écritures alors que vos lectures passent signifie donc : clé en lecture seule. Voir Authentification.
  • POST /activity : l’attributaire doit appartenir à l’agence du document. La page indiquait « aux agences de votre clé API ». Sur une vente, un owner valide pour la clé mais non rattaché à l’agence de la fiche reçoit 400 Activity's sale owner not found. Comme GET /users ne renvoie pas les agences d’un collaborateur, la recommandation est d’omettre owner sauf certitude.
  • POST /activity : avec une completionDate, la deadline renvoyée vaut la date de réalisation (et non null comme le montrait l’exemple). Un rendez-vous consigné après coup s’affiche désormais à sa date réelle sur la fiche, et non à celle de l’appel API.
  • POST /activity : data.content est interprété comme du HTML. Un texte brut avec des \n s’affiche en un seul bloc ; envoyez <p>…</p><p>…</p> pour obtenir des paragraphes. Les balises acceptées sont listées sur la page.
  • Le champ de taille de page change de nom selon la route : limit sur /contacts, /users et /{transaction}/search, pageSize sur /activities et /ad/search. L’écart est historique et conservé pour ne pas casser les intégrations en place ; il est maintenant signalé sur chaque page concernée.
PlanningEndpoints
Alimenter le planning de permanence depuis votre outil
Si vous tenez déjà vos plannings de permanence dans votre propre outil, vous pouvez les pousser dans Avest au lieu de les ressaisir. Deux routes sur la nouvelle page Planning de permanence.
  • Écrire une semaine : POST /external-integration/agency/{agencyId}/shift-planning/{transaction}. Un appel = une semaine ISO, et le corps décrit son état complet — tout créneau que vous n’envoyez pas est supprimé. Idempotent : rejouer le même corps donne le même résultat. Les autres semaines et les plannings récurrents ne sont jamais touchés.
  • Relire une semaine : la même URL en GET, pour comparer à votre écran ce qui est réellement enregistré, avec le nom des collaborateurs.
  • Simuler : dryRun: true joue toutes les validations et renvoie les compteurs sans rien écrire.
  • Vider une semaine est explicite : un shifts vide est refusé sauf allowEmpty: true. Une agence fermée reste représentable, un tableau vide par bug ne l’est pas.
  • Collaborateur par identifiant : le userId de GET Users, jamais le nom — un rapprochement prénom + nom casse au premier homonyme et affecte les leads à la mauvaise personne sans erreur visible.
  • Warnings : un créneau posé sur un collaborateur exclu de l’attribution est enregistré, mais remonte en warnings — il ne recevra jamais de lead.
Ce planning pilote l’attribution des leads entrants : une semaine non alimentée n’a aucun collaborateur de permanence, et ses leads partent en pioche. L’agence doit être paramétrée en planning semaine par semaine ; en « semaine type », la route refuse l’écriture plutôt que de vous laisser pousser dans le vide. Le POST exige une clé autorisée en écriture.
ActivitésTransactionsEndpoints
Dates de la fiche vendeur, rendez-vous d'estimation et clôture d'activité
Deux manques signalés à l’usage après la livraison précédente, tous deux sur le parcours vendeur piloté depuis un outil tiers.
  • Poser un rendez-vous d’estimation : PATCH Sale accepte appointment — le même champ que POST /sale. Il renseigne le créneau d’estimation et crée l’activité « Rendez-vous estimation ». Jusqu’ici, créer l’activité et passer l’étape à RDV laissait la date officielle de la fiche vide, contrairement à un rendez-vous saisi dans l’interface.
  • Écrire les dates du dossier : timeline est modifiable sur la même route — estimation, signature de mandat, offre, compromis, clause suspensive de crédit, acte authentique.
  • Reste de la fiche : property et address (géocodée comme à la création), owner, tags, mandate et offer sont désormais modifiables. contacts, customId, parsingCustomId, commission et state restent réservés à l’interface.
  • Clôturer une activité : PATCH Activity accepte completionDate (date ISO pour solder, null pour rouvrir), reason (résultat de l’appel) et owner. Un rappel honoré depuis votre outil ne reste plus « à faire » indéfiniment. Rejouer la requête sur une activité déjà close met la date à jour sans rejouer les effets de la clôture.
Aucun changement de comportement sur l’existant : tous ces champs sont optionnels, et une requête qui ne les envoie pas se comporte comme avant.
ActivitésTransactionsEndpoints
Rappels programmés, auteur d'activité, ciblage de vente et sync incrémentale
Quatre évolutions demandées par les intégrateurs côté vendeur, pour écrire depuis un outil tiers sans ressaisie dans Avest.
  • Rappel programmé : POST Activity accepte deadline et completionDate. Une deadline future sans completionDate crée un rappel « à faire », exactement comme depuis l’interface — c’est la donnée que vous lisez déjà pour construire vos relances du jour.
  • Auteur de l’activité : le champ owner permet d’indiquer quel collaborateur a réellement passé l’appel, au lieu de l’attribuer par défaut au responsable de la fiche. L’owner doit appartenir aux agences de votre clé.
  • Ciblage d’une vente par identifiant : PATCH Sale met à jour une vente par son id ou son customId. POST /sale identifie la vente par contact + adresse, et une adresse imparfaite crée un doublon — cette route supprime le risque.
  • Synchronisation incrémentale : updatedAt et stepUpdatedAt sont désormais renvoyés dans les réponses de /search et de la lecture unitaire. Ils étaient déjà acceptés en tri : vous pouvez maintenant ne resynchroniser que ce qui a changé, et solliciter beaucoup moins l’API.
Aucun changement de comportement sur l’existant : deadline, completionDate et owner sont optionnels, et une requête qui ne les envoie pas se comporte comme avant.
MatchTransactionsEndpoints
Écriture : visites, offres, étapes et qualification
L’API externe savait créer un acquéreur, mais rien piloter ensuite. Neuf routes ouvrent le cycle de vie complet du parcours acquéreur v3.
  • Visites : lister, créer, déplacer, annuler une visite sur une mise en relation. Créer une visite promeut le match à MVST ; annuler la dernière le redescend à MCNV.
  • Offres : lister, créer, faire évoluer une offre. Le statut accepted reste réservé à l’application Avest — il écrit sur la vente et classe sans suite toutes les autres mises en relation du bien.
  • Étape du match : PATCH Match fait avancer une mise en relation. Entonnoir à sens unique : on monte, on classe sans suite sur place (avec raison), on ne redescend ni ne rouvre jamais. MOFA n’est pas accessible via l’API.
  • Critères acquéreur : PATCH Acquisition corrige budget, surfaces et équipements sans re-poster la fiche en leadgen.
  • Qualification : POST Qualify sort une fiche de « à qualifier » vers ASRC ou AARC.
Ces routes exigent l’autorisation en écriture sur le scope externalIntegration — aucune migration de clé n’est nécessaire, mais un token en lecture seule reçoit 401. Aucune suppression n’est exposée.
ContactsRGPD
Consentement : les trois parcours annoncent le SMS
consent.journey : les parcours sale et rental annoncent désormais le SMS, comme acquisition. Les trois parcours annoncent donc les trois canaux (email, phone, sms). Pour ne pas consentir au SMS, énoncez-le : { "journey": "sale", "sms": false }. Voir Consentement à la prospection.
ContactsRGPD
Consentement à la prospection
Le consentement de prospection est désormais transmissible via l’API, et documenté sur une page dédiée : Consentement à la prospection.
  • Objet consent sur POST /external-integration/contact et PATCH /external-integration/contact/{contactId} : consentement par canal (email, phone, sms), date de recueil, mention affichée, durées.
  • Parcours déclaré : consent.journey (sale, rental, acquisition) à la création — vous déclarez la mention vue par la personne, les canaux qu’elle annonce deviennent consentis. Les trois parcours annoncent les trois canaux (le SMS sur sale et rental depuis le 11/08). Refusé sur PATCH, où chaque canal s’énonce explicitement.
  • Durées : téléphone un an, fixé par la réglementation, sans reconduction tacite ; courriel et SMS trois ans par défaut. consent.durationYears au-delà de 3 est rejeté en 400 plutôt que raccourci en silence.
  • Par défaut, aucun consentement : sans objet consent, le contact est créé sans consentement de prospection. Un consent transmis s’applique aussi sur un contact dédupliqué.
MatchActivitésBreaking
Étapes de match, visites et offres
Mise à jour de la documentation suite à l’évolution du parcours acquéreur. Aucun endpoint n’a changé — ce sont les valeurs et les objets renvoyés qui sont désormais documentés.
  • Étapes du match : le vocabulaire complet est enfin documenté — 7 étapes ordonnées (MSND, MRQT, MCNV, MVST, MNGT, MOFF, MOFA), chacune avec une variante _NF (« sans suite »), soit 14 valeurs. Voir Étapes du match.
  • ⚠️ Point de rupture : l’ancien statut d’archivage unique est remplacé par les 7 variantes _NF. Une intégration qui testait une valeur d’archivage unique doit passer sur step.endsWith('_NF').
  • Visites et offres : une visite et une offre sont des activités rattachées au match, lisibles via GET /external-integration/activities?document={matchId}&documentType=match (types visit, offer, visitChangeLog, offerChangeLog). Schéma de data documenté sur la nouvelle page Visites & offres. Lecture seule — l’API externe ne permet pas de créer une visite.
  • origin d’un match : valeurs documentées (auto_matching, manual, parsing, proposition, visit_receipt). Les exemples annonçaient une valeur leadgen qui n’existe pas.
  • POST /external-integration/acquisition : documentation d’un comportement existant — avec settings.matching, un match situé avant MRQT (dont toutes les étapes _NF) est remonté à MRQT, ce qui rouvre une mise en relation close.
  • Corrections : étapes d’acquisition (ACTC n’existe pas), étape de mandat de location (RMDT et non RMND), champ singleStorey de l’acquisition, tri de GET /activities (createdAt, pas la date de visite), casse réelle de type et linkedModel (minuscules), préfixe des messages d’erreur, et retrait du rejet des clés de query inconnues sur les routes qui ne l’appliquent pas.
  • Connu : mandate et timeline de GET /external-integration/rental sont actuellement renvoyés vides — correctif à venir.
Endpoints
Agences + mise à jour de contact
  • Agences : GET /external-integration/agencies — liste les agences accessibles et le groupe d’agences (pour récupérer les agencyId).
  • Contacts : PATCH /external-integration/contact/{contactId} — met à jour les champs d’identité d’un contact (chaque modification est tracée par une activité d’audit). L’édition des coordonnées (email/téléphone) n’est pas supportée pour l’instant.
Endpoints
Création de contact
Nouvel endpoint en écriture :
  • Contacts : POST /external-integration/contact — crée un contact seul (avec déduplication). À n’utiliser qu’en dernier recours : pour démarrer une affaire, créez le contact avec sa transaction via POST …/sale|acquisition|rental (dédup + allocation). Ne créez jamais un contact puis une transaction séparément.
Endpoints
Écriture d'activités
Nouvel endpoint en écriture :
  • Activités : POST /external-integration/activity — crée une activité (note, tâche, appel, message, email, rendez-vous) sur une fiche existante (acquisition, sale, rental, contact). Permet notamment d’écrire une note sur une fiche acquéreur.
Endpoints
Nouveaux endpoints en lecture
Ajout de nouveaux endpoints en lecture seule :
  • Match : GET /external-integration/match (par id ou customId) et GET /external-integration/match/search (par sale et/ou acquisition).
  • Activités : GET /external-integration/activities (par document + documentType, paginé 20 par page).
  • Annonces : GET /external-integration/ad (par id ou reference) et GET /external-integration/ad/search (filtres transaction, status, paginé 50 par page).
Docs
Migration de la documentation
Mise en ligne de la nouvelle documentation de l’API d’intégration externe (ventes, acquisitions, locations, contacts, utilisateurs, recherche de transactions).