Passer au contenu principal
Récupère une vente par son id MongoDB ou son customId métier, avec ses contacts liés.

Endpoint

URL : /external-integration/sale Méthode : GET Authentification : Requiert un token LinkedAPI avec scope externalIntegration (GET) et agencyGroup configuré. Clé requise : toutes les clés (lecture seule suffit). Voir Types de clé.

Headers

Query Parameters

Exactement un des deux paramètres doit être fourni. Pas zéro, pas les deux.
Le customId est sensible à la casse : les références Avest sont en majuscules, et ebzj7515 ne trouve pas la vente EBZJ7515.

Exemple de requête

Logique de fonctionnement

  1. Validation des params : Vérifie qu’un seul des deux paramètres est fourni et valide son format
  2. Recherche scopée : Filtre sur agencyGroup === linkedAPI.agencyGroup ET agency ∈ linkedAPI.agencies
  3. Récupération des contacts : Si vente trouvée, fetch des contacts liés (re-scopés sur les mêmes agences)
  4. Sérialisation : Tous les champs publics renseignés sur la fiche sont retournés. Les champs non renseignés sont absents de la réponse (pas null). Le contact principal de la vente est exposé via sale.mainContact (ID), le détail complet du contact est dans la clé contacts au top-level.

Réponse de succès

Code : 200

Vente trouvée

Vente non trouvée ou hors scope

Une fiche existant dans une autre agencyGroup retourne ce même payload (null). Pas de différenciation possible côté client entre “n’existe pas” et “pas autorisé”.

Champs de la réponse

Top-level sale

Toujours présents (si la vente existe) : Présents uniquement si renseignés (sinon clé absente, pas null) :

property

property.addressData (toujours présent si la vente existe — adresse splittée) : Autres champs property retournés s’ils sont renseignés : mainType (apartment, house, field, building, parking, etc.), developmentType (old / new), size (m²), floor, lotsNumbers, generalCondition, rooms, bedrooms, bathrooms, toilets, kitchenType, livingSurface, usefulSurface, floorSurface, landSurface, fieldSurface, balconyAmount/balconySurface, loggiaAmount/loggiaSurface, terraceAmount/terraceSurface, gardenAmount/gardenSurface, cellarAmount/cellarSurface, atticAmount/atticSurface, parkingType/parkingAmount/parkingSurface, hasElevator, hasPool, hasFireplace, hasArmoredDoor, hasOpticalFiber, hasVMC, propertyTax, isCollectiveOwnership, collectiveMonthlyCost, numberOfLots, heatingType, heatingEnergyType, waterDistributionType, glazingType, DPENumber, DPEEnergyValue, DPEEnergyTag, DPEGESValue, DPEGESTag, DPEDate, availabilityDate, occupancyStatus, sanitationType, isDuplex, hasBeautifulView, hasRoofTop, buildingYear, renovationYear, roomDetails[]. Biens professionnels : vatRegime (subject soumis à TVA, exempt non soumis) et propertyTaxResponsibility (taxe foncière à la charge du bailleur, owner, ou du preneur, tenant).

mandate

Renseigné à partir de l’étape MND. Avant, l’objet peut être présent sans les champs du mandat, avec seulement mandateHistory.

offer (à partir de step OFR)

timeline

Dates renseignées seulement. Peut contenir : mandateSignatureDate, agreementDate, agreementExpirationDate, offerDate, mortgageDeadline, closingDate, estimationDate, estimationStartAt, estimationEndAt.

contacts (top-level)

Liste des contacts liés à la vente (mêmes ObjectIds que dans sale.contacts côté Avest). Chaque contact : Le premier élément de l’array correspond au mainContact retourné au top-level (= vendeur principal).

Réponses d’erreur

  • Aucun paramètre fourni : 400 Bad Request
  • Les deux paramètres fournis : 400 Bad Request
  • id invalide : 400 Bad Request
  • customId invalide : 400 Bad Request
  • LinkedAPI agencyGroup manquant : 400 Bad Request
  • Header Authorization absent, ou IP non whitelistée sur une clé sécurisée : 403 Not authorized to access this resource
  • Token invalide : 401 Invalid bearer token

Notes importantes

  1. Scope strict : La fiche n’est retournée que si elle appartient à la agencyGroup du token ET à une des agencies listées dans le LinkedAPI. Aucune fuite cross-group, même avec un id Mongo connu d’une autre agence.
  2. Pas de différenciation 404 vs 403 : Une fiche hors scope retourne le même null qu’une fiche inexistante. Choix volontaire pour ne pas leak l’existence de fiches d’autres agences.
  3. Contacts re-scopés : Les contacts liés sont eux-mêmes filtrés sur agency ∈ linkedAPI.agencies pour éviter les fuites cross-group.
  4. Idempotence : L’endpoint est purement en lecture. Aucune modification d’état.
  5. Cas d’usage typique : Réception d’une notification de nouveau lead → extraction du customId ou id du mail → appel GET → récupération email/nom/adresse du bien pour automatisation (Make, Zapier, etc.).
  6. Champs absents vs null : les champs non renseignés sur la fiche n’apparaissent pas du tout dans la réponse — ils ne sont pas retournés à null. Côté client, traiter chaque champ comme optionnel.
  7. Cas d’usage pré-remplissage formulaire offre : récupérer le sale via customId → utiliser property.addressData (adresse splittée prête à l’emploi), mandate.price (HAI), mandate.feeResponsibility + mandate.commissionPercentage (charge & % honoraires), property.floor / property.lotsNumbers (étage / lots pour appartements). Récupérer les coordonnées du vendeur via GET /external-integration/contact avec le mainContact.

Rate limits

Cette route est limitée à 500 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 Requests avec header Retry-After (secondes) :
  • Si vous atteignez régulièrement la limite, contactez le support pour évaluer un relèvement sur votre token.