> ## Documentation Index
> Fetch the complete documentation index at: https://developers.avest.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Historique des évolutions de l'API d'intégration externe Avest.

**2026-11-04**

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](https://developers.avest.fr/endpoints/post-sale.md), [POST Acquisition](https://developers.avest.fr/endpoints/post-acquisition.md) et [POST Rental](https://developers.avest.fr/endpoints/post-rental.md), `settings.allocation.agencyGroupId` doit être le groupe de votre clé, et `agencyId`, s'il est fourni, une agence de [GET Agencies](https://developers.avest.fr/endpoints/get-agencies.md). 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](https://developers.avest.fr/endpoints/post-contact.md) 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](https://developers.avest.fr/guides/consentement.md).
* **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](https://developers.avest.fr/endpoints/patch-sale.md), 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](https://developers.avest.fr/endpoints/get-agencies.md) 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](https://developers.avest.fr/endpoints/patch-contact.md) 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](https://developers.avest.fr/endpoints/post-acquisition.md) et en lecture sur [GET Acquisition](https://developers.avest.fr/endpoints/get-acquisition.md).
* **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](https://developers.avest.fr/endpoints/match-offers.md).
* **Activités** : un changement d'étape d'une vente fait par Avest seul apparaît dans [GET Activities](https://developers.avest.fr/endpoints/get-activities.md) (`changeStep`, avec `data.isAutomatic: true`).
* **Recherche en texte libre** : « Paris 15 » ou « Lyon 3 » trouvent aussi les fiches du code postal de l'arrondissement.

**2026-10-28**

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](https://developers.avest.fr/endpoints/post-sale.md).
* **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](https://developers.avest.fr/endpoints/patch-sale.md) 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](https://developers.avest.fr/endpoints/post-activity.md) comme sur [PATCH Activity](https://developers.avest.fr/endpoints/patch-activity.md).
* **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](https://developers.avest.fr/guides/deduplication.md).
* **[GET Users](https://developers.avest.fr/endpoints/get-users.md)** 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](https://developers.avest.fr/guides/deduplication.md).
* **[PATCH Sale](https://developers.avest.fr/endpoints/patch-sale.md)** : 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](https://developers.avest.fr/guides/authentification.md).
* **[Planning de permanence](https://developers.avest.fr/endpoints/shift-planning.md)** : `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](https://developers.avest.fr/endpoints/get-acquisition.md) ; é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](https://developers.avest.fr/endpoints/get-sale.md)** : `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](https://developers.avest.fr/endpoints/get-activities.md)** : `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.

**2026-10-21**

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](https://developers.avest.fr/endpoints/patch-contact.md) dont le `consent` modifierait un contact supprimé définitivement reçoit `409` (`errorCode: CONTACT_DELETED`).
* **[PATCH Match](https://developers.avest.fr/endpoints/patch-match.md) : `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](https://developers.avest.fr/endpoints/match-visits.md) : elle fait passer le match en `MVST`.
* **[Qualifier un acquéreur](https://developers.avest.fr/endpoints/post-acquisition-qualify.md) 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](https://developers.avest.fr/endpoints/get-sale.md).
* **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](https://developers.avest.fr/endpoints/post-acquisition.md).

Voir [Consentement à la prospection](https://developers.avest.fr/guides/consentement.md).

**2026-09-29**

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](https://developers.avest.fr/endpoints/patch-activity.md) 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](https://developers.avest.fr/endpoints/delete-activity.md) (`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é](https://developers.avest.fr/guides/authentification.md).
* **Connaître sa clé** : nouvelle route [GET Key](https://developers.avest.fr/endpoints/get-key.md) (`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.

**2026-09-18**

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.

**2026-09-14**

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](https://developers.avest.fr/guides/authentification.md).
* **`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.

**2026-09-03**

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](https://developers.avest.fr/endpoints/shift-planning.md).

* **É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](https://developers.avest.fr/endpoints/get-users.md), 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**.

**2026-08-04**

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](https://developers.avest.fr/endpoints/patch-sale.md) 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](https://developers.avest.fr/endpoints/patch-activity.md) 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.

**2026-07-31**

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](https://developers.avest.fr/endpoints/post-activity.md) 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](https://developers.avest.fr/endpoints/patch-sale.md) 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.

**2026-07-30**

É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](https://developers.avest.fr/endpoints/match-visits.md) 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](https://developers.avest.fr/endpoints/match-offers.md) 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](https://developers.avest.fr/endpoints/patch-match.md) 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](https://developers.avest.fr/endpoints/patch-acquisition.md) corrige budget, surfaces et équipements sans re-poster la fiche en leadgen.
* **Qualification** : [POST Qualify](https://developers.avest.fr/endpoints/post-acquisition-qualify.md) 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.

**2026-08-11**

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](https://developers.avest.fr/guides/consentement.md).

**2026-08-07**

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](https://developers.avest.fr/guides/consentement.md).

* **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é.

**2026-07-29**

É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](https://developers.avest.fr/endpoints/get-match.md).
* ⚠️ **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](https://developers.avest.fr/endpoints/visits-offers.md). 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.

**2026-06-30**

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.

**2026-06-29**

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.

**2026-06-29**

É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**.

**2026-06-05**

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).

**2026-06-03**

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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.