Passer au contenu principal
Met à jour une vente existante — typiquement pour faire avancer son étape — en la ciblant par son identifiant plutôt que par contact + adresse.
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.
Si un customId correspond à plusieurs ventes de votre périmètre, la requête est refusée (400) au lieu d’en modifier une au hasard. Ciblez alors par id.

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 :
Une part vendeur négative, non numérique ou supérieure à 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.
Une vente active a toujours un responsable. Dans l’interface, le collaborateur qui déplace la fiche en devient responsable ; via l’API, il n’y a pas de collaborateur. Pour sortir une vente sans responsable de STK, TRN, PQUL, ARC, SLD ou TARC, envoyez owner dans la même requête que step. Sans owner, l’étape reste inchangée et la réponse est quand même un 200 : vérifiez step dans la réponse.
Passer une vente en STK (pioche) retire son responsable et supprime ses activités non clôturées (tâches, rappels, rendez-vous à venir), y compris celles créées via POST Activity. Les visites et offres sont conservées.
Non modifiables par cette route : contacts, customId, parsingCustomId, commission et state. Nous préférons refuser un champ plutôt que de l’accepter sans l’appliquer — un objet dont aucune clé n’est modifiable est rejeté, plutôt que de répondre 200 sans rien écrire.

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.
L’activité créée est renvoyée dans la réponse, sous la clé activity.
Contrairement à la création, une date passée est acceptée : cette route sert aussi à rattraper un rendez-vous déjà tenu.
appointment.date et timeline.estimationDate écrivent la même date : les envoyer tous les deux est refusé. Utilisez appointment pour poser le rendez-vous (activité comprise), timeline seul pour corriger une date sans créer d’activité.

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.
L’adresse est située par Google. Si Google ne situe que la ville, la vente est enregistrée avec la ville seule, sans numéro ni rue, et la réponse reste un succès. Relisez property.addressData dans la réponse : sans streetNumber ni route, renvoyez address écrite autrement (sans complément, sans lieu-dit). property.addressData n’est pas modifiable.

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

Ciblage par customId :
La réponse renvoie la vente au format public, identique à GET Sale — plus la clé 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 est 409 avec le code TRANSACTION_EDIT_CONFLICT — rejouez la requête.

Réponses d’erreur

Rate limits

100 req / minute par groupe d’agences (bucket d’écriture).