POST Sale retrouve la vente par contact + adresse.
Si l’adresse que vous envoyez ne correspond pas exactement à celle
enregistrée, une seconde vente est créée. Dès que vous connaissez déjà la
vente, utilisez cette route : le ciblage par identifiant supprime ce risque, et
il ne relance ni le routage, ni l’allocation, ni les alertes leadgen.
Endpoint
URL :/external-integration/sale/{saleId}
Méthode : PATCH
Authentification : token LinkedAPI avec scope externalIntegration en écriture.
Clé requise : lecture-écriture. Une clé en lecture seule reçoit 403. Voir Types de clé.
Path Parameters
Les deux formes sont renvoyées en lecture par GET Sale et par la recherche. Un
customId n’est jamais un ObjectId, il n’y a donc pas d’ambiguïté sur la forme.
Body Parameters
Au moins un champ. Seuls les champs listés sont modifiables.
Dans
mandate et offer, sellPrice est le net vendeur et agencyCommission un montant en euros, comme sur POST Sale. Le prix affiché (price) se calcule seul : n’envoyez pas le prix honoraires inclus dans sellPrice, et n’envoyez pas price.
Part vendeur des honoraires (mandate et offer)
En charge both, mandate et offer acceptent la part vendeur :
agencyCommission est refusée (400). Sans elle, un nouveau total garde la proportion de la part déjà enregistrée. Elle est vidée dès que la charge n’est plus both.
Honoraires en pourcentage (mandate)
mandate.commissionType (percentage ou value) donne le mode des honoraires, et mandate.commissionPercentage leur taux en mode percentage. Hors du mode value, un commissionPercentage hors de 0 (inclus) à 100 (exclu) est refusé (400), avec le message mandate.commissionPercentage must be a number between 0 (included) and 100 (excluded), sans préfixe de classe. Renvoyer la valeur déjà enregistrée passe toujours. En mode value, un commissionPercentage transmis est ignoré : Avest le calcule depuis les montants.
Étapes (step)
STK, TRN, ARC, PQUL, QUL, CNV, RDV, DLV, MND, TARC, OFR, AGT, MTG, SLD.
Le changement d’étape produit les mêmes effets que depuis l’interface : activité de changement d’étape, mise à jour de stepUpdatedAt, recalcul de la commission, et clôture des activités à faire de la fiche quand la nouvelle étape va de QUL à DLV (rendez-vous compris, visites et offres exceptées). Il peut aussi lancer les séquences d’activités que l’agence a paramétrées pour cette étape (par exemple une série d’appels de qualification). Pour poser un rendez-vous en changeant d’étape, envoyez step et appointment dans la même requête : le rendez-vous est créé après le changement d’étape et reste ouvert. Contrairement au match, une vente peut revenir en arrière dans le pipeline.
Motifs (stepUpdateReason)
Un motif non accepté pour l’étape visée est refusé en
400 (Invalid stepUpdateReason for step ARC). fakePhone marque aussi les téléphones du contact comme invalides.
Dates de la fiche
timeline porte les dates officielles affichées sur la fiche. Ce sont elles que lisent le suivi de dossier et les exports — pas les dates des activités.
Toutes sont des chaînes de date ISO 8601. Envoyer
null sur une date l’efface.
Poser un rendez-vous
appointment est le raccourci qui reproduit le geste de l’interface : il renseigne le créneau d’estimation et crée l’activité « Rendez-vous estimation » sur la fiche. Le même champ existe sur POST Sale, où il crée l’activité sans renseigner les dates de la fiche.
activity.
Contrairement à la création, une date passée est acceptée : cette route
sert aussi à rattraper un rendez-vous déjà tenu.
Adresse et bien
property accepte les caractéristiques du bien : mainType, developmentType, generalCondition, size, livingSurface, landSurface, rooms, bedrooms, floor, buildingYear… — les mêmes champs qu’à la création.
L’adresse ne s’écrit pas dans property : envoyez address en texte libre, elle est géocodée exactement comme à la création.
Attribution et tags
owner réattribue la fiche. L’utilisateur doit appartenir aux agences de votre clé API — récupérez son ObjectId via GET Users. Sinon la requête est refusée et rien n’est écrit.
Tags
tags remplace la liste : les tags absents du tableau sont retirés de la vente. Envoyez [] pour tout retirer. Chaque identifiant doit correspondre à un tag existant de votre périmètre. Les ajouts et retraits produisent les mêmes entrées d’historique que depuis l’interface.
Exemple
customId :
activity si un appointment a été fourni.
Concurrence
Si la vente est modifiée simultanément par un agent, la requête est rejouée automatiquement. En cas d’échec persistant, la réponse est409 avec le code TRANSACTION_EDIT_CONFLICT — rejouez la requête.