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.agencyGroupIddoit être le groupe de votre clé, etagencyId, s’il est fourni, une agence de GET Agencies. Sinon l’API répond400, 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 unfalseexplicite retire un consentement. Si vous comptiez sur l’omission d’un canal pour le retirer, envoyezfalse. Sur un nouveau contact, rien ne change. Voir Consentement à la prospection. - Adresse dans la réponse : POST Sale et POST Rental renvoient
transaction.property.addressDataettransaction.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, unmandate.commissionPercentagehors 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.
- 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. SansdurationYears, il appliquait jusqu’ici le réglage de durée de l’agence. - Biens professionnels :
property.vatRegime(subject,exempt) etproperty.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
geometrypeut portercenteretradius(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). UnPATCHqui ramèneagencyCommissionsous 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, avecdata.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 :
agencyCommissionest un montant, pas un pourcentage (5donne 5 €). Le pourcentage se saisit aveccommissionType: "percentage"etcommissionPercentage.sellPriceest le net vendeur, le prix affiché se calcule seul. Voir POST Sale. - Type de mandat :
exclusive,semiExclusiveounotExclusive. La valeursimple, que la doc citait, est refusée. - Vente créée à l’étape rendez-vous : envoyez
settings.step: "RDV"etappointmentdans la même requête. Un changement d’étape versQULàDLVpar 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. Unownerhors des agences de la clé reçoit400, et non403, 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. parsingCustomIdest 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.stepest ignoré. Voir Déduplication. - PATCH Sale : une vente sans responsable ne sort de
STK,TRN,PQUL,ARC,SLDouTARCqu’avecownerdans la même requête, sinon l’étape reste inchangée avec un200. Passer enSTKsupprime les activités non clôturées. Les motifsstepUpdateReasonsont listés et contrôlés selon l’étape.offern’est enregistrée qu’à partir deMND. - 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 :
weekNumberva jusqu’à53les 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épond404. - Valeurs corrigées :
mainTypebusiness_assetsetlease_transfer; civilitémroumme; critère acquéreurexcluded,bikeShedetmortgagebooléens ; valeurs de lecture de GET Acquisition ; énergiessolar,geothermalet eau chaude individuelle ;loggiaAmountetloggiaSurfacesur 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
saleetacquisitionànullettagsà[];sortOrders’envoie avecsortField. - POST Sale :
transaction.propertyest requis, un objet vide suffit. Sinon400 Invalid transaction : property required.settings.disableAlertsne coupe que l’email d’alerte : la notification Slack de l’agence part quand même. - GET Sale :
customIdest sensible à la casse.mandatepeut être présent avantMND, avecmandateHistory, l’historique des modifications du mandat.property.addressDataporte aussidepartmentetregion. - GET Activities :
filevautnullsans fichier stocké par Avest, etfile.urlpeut valoirnull. 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.dateobligatoire dès qu’un canal est consenti (true, ou annoncé parjourney) surPOST /contactetPATCH /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
phoneest consenti, transmettez la mention affichée à la personne :wordingText(texte exact),wordingVersionetlocale. Les trois parcours annonçant le téléphone, unjourneyles 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
truesur un canal déjà consenti n’est enregistré que si sadateest postérieure au recueil déjà enregistré. Sinon il est ignoré et ne prolonge ni le consentement ni la conservation ;PATCHrenvoie alorsconsentChanged: falsesi aucun autre canal ne change. - Canal retiré puis renvoyé : sur un canal retiré depuis (désinscription, retrait par l’agence,
falsetransmis), untruetransmis rétablit le consentement, y compris le renvoi d’un accord déjà transmis. Ne renvoyez pas un consentement déjà transmis, et ne transmetteztruesur 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.retentionDurationYearsne 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
consentmodifierait un contact supprimé définitivement reçoit409(errorCode: CONTACT_DELETED). - PATCH Match :
MVSTexige une visite active. Sans visite active (ni annulée ni supprimée) sur le match, la requête est refusée en400avecerrorCode: VISIT_DATE_REQUIRED(Visit date required to plan a visit). Créez la visite avec POST une visite : elle fait passer le match enMVST. - Qualifier un acquéreur vers
MVSTexigeoriginMatch.visitStartAt. Sinon l’API répond400(errorCode: VISIT_DATE_REQUIRED), et la fiche n’est pas qualifiée. - Statut des visites :
derivedStatusse calcule sur le jour calendaire de l’agence, dans son fuseau. Une visite du jour resteplannedjusqu’à minuit, heure de l’agence. - Honoraires partagés : en charge
both,mandateetofferportentsellerAgencyCommissionetsellerAgencyCommissionPercentage, en lecture comme en écriture. LecommissionPercentaged’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.
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
DELETEreçoit403. 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.
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, pas401, quand le headerAuthorizationest absent. La doc annonçait401et aucune route ne déclarait de403; l’API renvoie403 Not authorized to access this resource. Les403sont désormais déclarés sur les 31 opérations de la référence.- Le message du
401estInvalid bearer token, pasUnauthorized. 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 non401comme 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/PATCHavec une clé en lecture seule reçoit403 Not authorized to access this resource— la même réponse qu’une requête sans token. Un403sur 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, unownervalide pour la clé mais non rattaché à l’agence de la fiche reçoit400 Activity's sale owner not found. CommeGET /usersne renvoie pas les agences d’un collaborateur, la recommandation est d’omettreownersauf certitude.POST /activity: avec unecompletionDate, ladeadlinerenvoyée vaut la date de réalisation (et nonnullcomme 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.contentest interprété comme du HTML. Un texte brut avec des\ns’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 :
limitsur/contacts,/userset/{transaction}/search,pageSizesur/activitieset/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.
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: truejoue toutes les validations et renvoie les compteurs sans rien écrire. - Vider une semaine est explicite : un
shiftsvide est refusé saufallowEmpty: true. Une agence fermée reste représentable, un tableau vide par bug ne l’est pas. - Collaborateur par identifiant : le
userIdde 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.
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 quePOST /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 :
timelineest modifiable sur la même route — estimation, signature de mandat, offre, compromis, clause suspensive de crédit, acte authentique. - Reste de la fiche :
propertyetaddress(géocodée comme à la création),owner,tags,mandateetoffersont désormais modifiables.contacts,customId,parsingCustomId,commissionetstaterestent réservés à l’interface. - Clôturer une activité : PATCH Activity accepte
completionDate(date ISO pour solder,nullpour rouvrir),reason(résultat de l’appel) etowner. 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.
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
deadlineetcompletionDate. Unedeadlinefuture sanscompletionDatecré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
ownerpermet d’indiquer quel collaborateur a réellement passé l’appel, au lieu de l’attribuer par défaut au responsable de la fiche. L’ownerdoit appartenir aux agences de votre clé. - Ciblage d’une vente par identifiant : PATCH Sale met à jour une vente par son
idou soncustomId.POST /saleidentifie la vente par contact + adresse, et une adresse imparfaite crée un doublon — cette route supprime le risque. - Synchronisation incrémentale :
updatedAtetstepUpdatedAtsont désormais renvoyés dans les réponses de/searchet 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.
deadline, completionDate et owner sont optionnels, et une requête qui ne les envoie pas se comporte comme avant.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
acceptedreste 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.
MOFAn’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
ASRCouAARC.
externalIntegration — aucune migration de clé n’est nécessaire, mais un token en lecture seule reçoit 401. Aucune suppression n’est exposée.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.Le consentement de prospection est désormais transmissible via l’API, et documenté sur une page dédiée : Consentement à la prospection.
- Objet
consentsurPOST /external-integration/contactetPATCH /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 sursaleetrentaldepuis le 11/08). Refusé surPATCH, 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.durationYearsau-delà de 3 est rejeté en400plutôt que raccourci en silence. - Par défaut, aucun consentement : sans objet
consent, le contact est créé sans consentement de prospection. Unconsenttransmis s’applique aussi sur un contact dédupliqué.
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 surstep.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(typesvisit,offer,visitChangeLog,offerChangeLog). Schéma dedatadocumenté sur la nouvelle page Visites & offres. Lecture seule — l’API externe ne permet pas de créer une visite. origind’un match : valeurs documentées (auto_matching,manual,parsing,proposition,visit_receipt). Les exemples annonçaient une valeurleadgenqui n’existe pas.POST /external-integration/acquisition: documentation d’un comportement existant — avecsettings.matching, un match situé avantMRQT(dont toutes les étapes_NF) est remonté àMRQT, ce qui rouvre une mise en relation close.- Corrections : étapes d’acquisition (
ACTCn’existe pas), étape de mandat de location (RMDTet nonRMND), champsingleStoreyde l’acquisition, tri deGET /activities(createdAt, pas la date de visite), casse réelle detypeetlinkedModel(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 :
mandateettimelinedeGET /external-integration/rentalsont actuellement renvoyés vides — correctif à venir.
- Agences :
GET /external-integration/agencies— liste les agences accessibles et le groupe d’agences (pour récupérer lesagencyId). - 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.
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 viaPOST …/sale|acquisition|rental(dédup + allocation). Ne créez jamais un contact puis une transaction séparément.
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.
Ajout de nouveaux endpoints en lecture seule :
- Match :
GET /external-integration/match(paridoucustomId) etGET /external-integration/match/search(parsaleet/ouacquisition). - Activités :
GET /external-integration/activities(pardocument+documentType, paginé 20 par page). - Annonces :
GET /external-integration/ad(paridoureference) etGET /external-integration/ad/search(filtrestransaction,status, paginé 50 par page).