Passer au contenu principal
Crée ou met à jour une acquisition (fiche acquéreur) avec déduplication automatique du contact et de la transaction, et possibilité de créer un match avec une vente existante.

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.
Important : ref et saleId sont mutuellement exclusifs. Utilisez l’un OU l’autre, jamais les deux.

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

Les 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)

Processus :
  1. Recherche de l’annonce par référence dans le groupe d’agences
  2. Si trouvée, récupération de la vente associée
  3. Création d’un match entre l’acquisition et la vente avec étape MRQT

Par ID de vente (saleId)

Processus :
  1. Recherche directe de la vente par ID
  2. 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é.
Un match existant peut être remis à l’étape MRQT. Si le match trouvé se situe à une étape antérieure à MRQT — c’est-à-dire MSND (simple proposition) ou n’importe quelle étape « sans suite » _NF — il est remonté à MRQT (nouvelle demande), car la requête est traitée comme une demande entrante de l’acquéreur.Conséquence : reposter une acquisition avec settings.matching sur une mise en relation classée sans suite la rouvre. Un match déjà plus avancé (MCNV, MVST, MNGT, MOFF, MOFA) n’est jamais régressé.Voir Étapes du match.

Notes importantes

  1. 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.
  2. 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
  3. 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).
  4. Steps : Si settings.step n’est pas fourni, l’étape est calculée automatiquement selon le project. Sans owner attribué, l’étape est forcée à AQUL.
  5. Areas : Les zones de recherche sont utilisées pour l’allocation par zone et les alertes de matching automatique.
  6. Identifiant externe : parsingCustomId est 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’id renvoyé à 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 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.