Passer au contenu principal
Récupère un match (rapprochement entre une acquisition et une vente) par son id MongoDB ou son customId métier.

Endpoint

URL : /external-integration/match Méthode : GET Authentification : Requiert un token LinkedAPI avec scope externalIntegration et une clé rattachée à un groupe d’agences. Clé requise : toutes les clés (lecture seule suffit). Voir Types de clé.

Headers

Query Parameters

Exactement un des deux paramètres suivants doit être fourni :
id et customId sont mutuellement exclusifs. Zéro ou plus d’un → 400.

Exemples de requête

Réponse de succès

Code : 200

Match trouvé

Match non trouvé ou hors scope

Champs de la réponse

sale et acquisition valent null s’ils ne sont pas renseignés, et tags vaut []. Les autres champs non renseignés sont absents de la réponse.

Étapes du match

Un match suit un parcours en 7 étapes ordonnées. Chaque étape possède une variante suffixée _NF (« sans suite ») : la mise en relation est close à ce stade précis. Soit 14 valeurs possibles au total.

Comment les interpréter

  • Les étapes sont ordonnées. Pour savoir si un match a progressé, comparez leur rang dans le tableau ci-dessus — jamais les chaînes entre elles.
  • _NF = « sans suite ». step.endsWith('_NF') identifie tous les matchs clos, quelle que soit l’étape où ils se sont arrêtés. Le préfixe indique jusqu’où la mise en relation était allée : MVST_NF = close après la visite, MSND_NF = close dès la proposition.
  • MVST est le signal « visite ». Le match a atteint l’étape visite. Les visites elles-mêmes (dates, annulation) sont des activités : voir Visites & offres.
Ce vocabulaire remplace le vocabulaire d’étapes antérieur, et notamment l’ancien statut unique d’archivage — désormais éclaté en 7 variantes _NF. Une intégration qui testait une valeur d’archivage unique doit passer sur step.endsWith('_NF').

Origines

Champs non exposés

La réponse est une liste blanche stricte : seuls les 8 champs du tableau ci-dessus sont renvoyés. En particulier, ne sont pas exposés par cet endpoint, même s’ils existent côté Avest :
  • les dates clés du match (date de visite, date d’offre, date d’acceptation) — passez par Visites & offres ;
  • les contacts rattachés à la vente et à l’acquisition — passez par GET Contact ;
  • l’historique des propositions et le motif de changement d’étape.

Réponses d’erreur

  • Aucun paramètre fourni : 400 Bad Request
  • Les deux paramètres fournis : 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

  1. Scope : un match hors de votre périmètre autorisé ne sera jamais retourné (match: null). Pas de différenciation possible entre “n’existe pas” et “pas autorisé”.
  2. Croisement : sale et acquisition sont les ObjectIds à utiliser avec GET /external-integration/sale et GET /external-integration/acquisition pour récupérer le détail des transactions rapprochées.
  3. Endpoint en lecture seule. Pour faire avancer l’étape d’une mise en relation, voir PATCH Match.

Rate limits

Cette route est limitée à 500 req / minute par groupe d’agences (bucket dédié).
  • Headers : RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (secondes avant reset).
  • Dépassement → 429 Too Many Requests avec header Retry-After :