Endpoint
URL :/external-integration/sale
Méthode : POST
Authentification : Requiert un token LinkedAPI.
Clé requise : lecture-écriture. Une clé en lecture seule reçoit 403. Voir Types de clé.
Headers
Logique de fonctionnement
1. Déduplication Contact
- Recherche d’un contact existant par téléphone ou email dans le groupe d’agences
- Si trouvé : mise à jour des informations
- Si non trouvé : création d’un nouveau contact
2. Déduplication Transaction
- Si contact existant, recherche d’une vente active à la même adresse
- Si trouvée : mise à jour de la vente existante
- Si non trouvée : création d’une nouvelle vente
3. Allocation
- Attribution automatique d’un utilisateur et d’une agence selon les règles configurées
- Possibilité de forcer l’allocation via
settings.allocation
4. Routing Step
- Calcul automatique de l’étape selon le projet et la configuration de l’agence
- Possibilité de forcer l’étape d’une nouvelle vente via
settings.step. Sur une vente retrouvée par la déduplication, l’étape ne change pas : passez par PATCH Sale
Body Parameters
Structure complète
Détail des paramètres
settings.allocation
Sans
agencyId, l’attribution est automatique, parmi les agences du groupe.
settings.disableAlerts
settings.step
Étapes prospects vendeurs
Étapes mandats de vente (après signature mandat)
appointment (ventes et locations)
Crée une activité de type “meeting” liée à la transaction.
À la création,
appointment crée l’activité « Rendez-vous estimation » mais ne renseigne pas les dates d’estimation de la fiche (timeline).
Créer la vente à l’étape rendez-vous
Si le rendez-vous d’estimation est déjà pris, envoyez dans la même requêtesettings.step: "RDV" et appointment : la vente est créée à l’étape RDV, avec son rendez-vous à venir.
note
Crée une activité de type “note” liée à la transaction.contact
address
transaction (TransactionSale)
Projet et identifiant
Propriété (transaction.property)
transaction.property est requis, même vide : envoyez au moins "property": {}. Sans lui, la requête est refusée (400).
DPE d’un bien professionnel (
mainType office, shop, industry,
business_assets ou lease_transfer) : DPEEnergyTag et DPEGESTag sont
enregistrés tels que vous les transmettez. Avest ne les calcule pas depuis
DPEEnergyValue, DPEGESValue et la surface, dont les seuils sont ceux du
logement : transmettez les étiquettes.Estimations (transaction.fieldValue, transaction.onlineValue)
Mandat (transaction.mandate)
agencyCommission est un montant en euros, jamais un pourcentage : 5 donne 5 € d’honoraires. Pour saisir un pourcentage, envoyez commissionType: "percentage", commissionPercentage et sellPrice : le montant des honoraires est alors calculé. À charge vendeur, le pourcentage porte sur le prix honoraires inclus ; à charge acquéreur, sur le net vendeur. Exemple : { "sellPrice": 505440, "commissionType": "percentage", "commissionPercentage": 2.8, "feeResponsibility": "seller" } donne 14 560 € d’honoraires et un prix affiché de 520 000 €. Sans commissionType, agencyCommission est lu comme un montant et aucun pourcentage n’est calculé.
sellPrice est le net vendeur. Le prix affiché (price) se calcule seul : net vendeur + honoraires. N’envoyez pas le prix honoraires inclus dans sellPrice, et n’envoyez pas price : il n’est pas modifiable.
Offre (transaction.offer)
MND ou au-delà (MND, OFR, AGT, MTG, SLD, TARC) : sur une vente créée à une étape antérieure, elle est ignorée, et la réponse reste un succès.
Les honoraires de l’offre suivent la même règle que ceux du mandat : agencyCommission est un montant, commissionType: "percentage" le fait calculer depuis commissionPercentage (inférieur à 100, montants arrondis à l’euro).
Part vendeur (mandate et offer) : 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.
Timeline (transaction.timeline)
Exemple complet
agencyGroupId et agencyId de l’exemple sont ceux de l’exemple de GET Agencies : remplacez-les par ceux que GET Agencies renvoie pour votre clé, et userId par un collaborateur de cette agence (GET Users liste ceux du groupe).
Réponse de succès
Code :200
transaction.property.addressData est l’adresse reconnue et enregistrée sur le bien, au format de GET Sale ; transaction.property.addresses la contient aussi. Comparez-la à l’address envoyée pour repérer une adresse mal reconnue. Elle n’est pas renvoyée si la fiche est attribuée à une agence que votre clé ne couvre pas, comme sur GET.
Réponses d’erreur
- Settings manquants :
400 Bad Request
- Allocation manquante :
400 Bad Request
- AgencyGroupId manquant :
400 Bad Request
- Groupe d’agences hors du périmètre de votre clé :
400 Bad Request, aucun lead créé
- Agence de votre groupe que votre clé ne couvre pas, ou désactivée :
400 Bad Request, aucun lead créé (une agence d’un autre groupe reçoit, avec le même préfixe,Agency group ID is not the same as the agency group ID)
transaction.propertymanquant :400 Bad Request
- Adresse manquante :
400 Bad Request
- Date de rendez-vous dans le passé :
400 Bad Request
appointmentsur un type non supporté (acquisition) :400 Bad Request
Notes importantes
- Déduplication : Par défaut, si un contact existe avec le même téléphone/email, la vente existante à la même adresse sera mise à jour plutôt que d’en créer une nouvelle.
-
Allocation automatique : Sans
agencyId/userId, le système alloue automatiquement selon les règles configurées (zones, shifts, priorité contact, etc.) -
Activités :
appointmentetnotecréent des activités séparées liées à la transaction. En cas d’erreur sur ces créations, la transaction est quand même créée (notification Slack envoyée). -
Steps : Si
settings.stepn’est pas fourni, l’étape est calculée automatiquement selon leprojectet la configuration de l’agence. -
Identifiant externe :
parsingCustomIdest enregistré sur la fiche et renvoyé en lecture, mais il ne sert pas au dédoublonnage. Deux envois avec le mêmeparsingCustomIdpeuvent créer deux ventes. Pour mettre à jour une vente déjà créée, conservez l’idrenvoyé à la création et passez par PATCH Sale.
Rate limits
Cette route est limitée à 100 req / minute par groupe d’agences (bucket dédié, indépendant des autres routes).- Headers présents sur toutes les réponses :
RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset(secondes avant reset). - Dépassement →
429 Too Many Requestsavec headerRetry-After(secondes) :
- Si vous atteignez régulièrement la limite, contactez le support pour évaluer un relèvement sur votre token.