Endpoint
URL :/external-integration/acquisition
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 acquisition de ce contact, quelle que soit son étape (voir Déduplication)
- Si trouvée : mise à jour de l’acquisition existante
- Si non trouvée : création d’une nouvelle acquisition
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 acquisition via
settings.step. Sur une acquisition retrouvée, l’étape ne change pas : passez par Qualifier un acquéreur
5. Matching (Optionnel)
- Création automatique d’un match entre l’acquisition et une vente existante
- Via référence d’annonce (
ref) ou ID de vente (saleId)
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
settings.matching (ACQUISITION ONLY)
Permet de créer automatiquement un match entre l’acquisition et une vente existante.note
Crée une activité de type “note” liée à la transaction.contact
transaction (TransactionAcquisition)
Projet et identifiant
Niveau d’activité et but
Types de biens recherchés
Zones de recherche
geometry est le polygone qui sert à la recherche et à l’attribution. center et radius décrivent le cercle tracé, pour qu’Avest le rouvre comme tel : transmettez-les avec le polygone de ce cercle, jamais seuls. Un center qui n’est pas un Point, ou un radius nul ou négatif, est refusé (400).
Critères de recherche (RangeValue)
Tous ces champs acceptent un objet{ low?: number, high?: number } :
Critères de nécessité
Ces champs acceptent les valeurs :unnecessary, preferable, essential ou excluded (critère éliminatoire : le bien ne doit pas en avoir, pris en compte par le rapprochement)
Financement
Mandat de recherche
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
Réponses d’erreur
- Settings manquants :
400 Bad Request
- Allocation manquante :
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)
- Project manquant :
400 Bad Request
- Matching mutuellement exclusif :
400 Bad Request
- Matching uniquement pour acquisitions :
400 Bad Request
Fonctionnalité Matching
Le matching permet de lier automatiquement une acquisition à une vente existante, créant ainsi un “match” entre l’acquéreur et le bien.Par référence d’annonce (ref)
- Recherche de l’annonce par référence dans le groupe d’agences
- Si trouvée, récupération de la vente associée
- Création d’un match entre l’acquisition et la vente avec étape
MRQT
Par ID de vente (saleId)
- Recherche directe de la vente par ID
- Si trouvée, création d’un match avec étape
MRQT
Match créé
Lorsqu’un match est créé, il est initialisé avec :- step :
MRQT(Match Request) - owner : L’utilisateur alloué
- agency : L’agence allouée
- Liens vers l’acquisition et la vente
Si un match existe déjà entre l’acquisition et la vente, il n’est pas
recréé : le match existant est réutilisé.
Notes importantes
- Déduplication : Par défaut, si un contact existe avec le même téléphone/email, l’acquisition existante sera mise à jour plutôt que d’en créer une nouvelle.
-
Allocation automatique : Sans
agencyId/userId, le système alloue selon :- Priorité contact : le lead va d’abord au responsable de la fiche la plus récente du contact réellement travaillée par un collaborateur (créée, avancée ou annotée à la main), puis au responsable du contact, sauf s’il ne le détient que par des fiches automatiques jamais touchées
- Zones de recherche (
areas) - Shifts configurés
- Allocation par défaut/random
- Matching : Le match est créé uniquement si la vente est trouvée. En cas d’échec, l’acquisition est quand même créée (tracé dans les steps).
-
Steps : Si
settings.stepn’est pas fourni, l’étape est calculée automatiquement selon leproject. Sans owner attribué, l’étape est forcée àAQUL. - Areas : Les zones de recherche sont utilisées pour l’allocation par zone et les alertes de matching automatique.
-
Identifiant externe :
parsingCustomIdest enregistré sur la fiche et renvoyé en lecture, mais il ne sert pas au dédoublonnage. Pour mettre à jour une acquisition déjà créée, conservez l’idrenvoyé à la création et passez par PATCH Acquisition.
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.