> ## Documentation Index
> Fetch the complete documentation index at: https://developers.avest.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# GET Match

> Récupère un match (rapprochement acquisition / vente) par son id ou son customId.

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é](https://developers.avest.fr/guides/authentification.md).

## Headers

```
Authorization: Bearer {token}
```

## Query Parameters

Exactement **un** des deux paramètres suivants doit être fourni :

| Paramètre | Type | Description |
| - | - | - |
| `id` | ObjectId | Identifiant Mongo du match. |
| `customId` | String | Identifiant métier du match. |

> [!WARNING]
>
> `id` et `customId` sont **mutuellement exclusifs**. Zéro ou plus d'un → `400`.

## Exemples de requête

```bash theme={null}
GET /external-integration/match?id=6a04a0aed4948142783f8cdf
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/match?customId=M-2025-001
Authorization: Bearer your-linked-api-token
```

## Réponse de succès

**Code** : `200`

### Match trouvé

```json theme={null}
{
  "success": true,
  "match": {
    "id": "6a04a0aed4948142783f8cdf",
    "customId": "M-2025-001",
    "step": "MRQT",
    "origin": "manual",
    "sale": "6a044cba8db14b3fbd015208",
    "acquisition": "6a04a0aed4948142783f8ce0",
    "tags": ["66cc8a8e75c9fac35c6ecd80", "66cc8a8e75c9fac35c6ecd81"],
    "createdAt": "2026-05-13T16:02:54.888Z"
  }
}
```

### Match non trouvé ou hors scope

```json theme={null}
{
  "success": true,
  "match": null
}
```

## Champs de la réponse

| Champ | Type | Description |
| - | - | - |
| `id` | String | ObjectId Mongo du match. |
| `customId` | String | Identifiant métier du match. |
| `step` | String | Étape courante du match. Voir « Étapes du match » ci-dessous. |
| `origin` | String | Origine du match. Voir « Origines » ci-dessous. |
| `sale` | String | ObjectId de la vente rapprochée. |
| `acquisition` | String | ObjectId de l'acquisition rapprochée. |
| `tags` | Array | Liste d'ObjectIds des tags rattachés au match. |
| `createdAt` | ISO 8601 | Date de création du match. |

> [!NOTE]
>
> `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.

| Ordre | `step` | Libellé | Variante « sans suite » |
| - | - | - | - |
| 1 | `MSND` | Proposé (rapprochement) | `MSND_NF` |
| 2 | `MRQT` | Nouvelle demande | `MRQT_NF` |
| 3 | `MCNV` | Relance | `MCNV_NF` |
| 4 | `MVST` | Visite | `MVST_NF` |
| 5 | `MNGT` | Intérêt / Négociation | `MNGT_NF` |
| 6 | `MOFF` | Offre formalisée | `MOFF_NF` |
| 7 | `MOFA` | Offre acceptée | `MOFA_NF` |

### 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](https://developers.avest.fr/endpoints/visits-offers.md).

> [!WARNING]
>
> 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

| `origin` | Sens |
| - | - |
| `auto_matching` | Rapprochement automatique. |
| `manual` | Créé manuellement par un utilisateur. |
| `parsing` | Issu de l'analyse d'un email entrant. |
| `proposition` | Issu d'une proposition envoyée à l'acquéreur. |
| `visit_receipt` | Issu d'un bon de visite. |

## 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](https://developers.avest.fr/endpoints/visits-offers.md) ;
* les contacts rattachés à la vente et à l'acquisition — passez par
  [GET Contact](https://developers.avest.fr/endpoints/get-contact.md) ;
* l'historique des propositions et le motif de changement d'étape.

## Réponses d'erreur

* **Aucun paramètre fourni** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetMatch : Either id or customId is required"
}
```

* **Les deux paramètres fournis** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetMatch : Provide either id or customId, not both"
}
```

* **LinkedAPI agencyGroup manquant** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "LinkedAPI agencyGroup is required"
}
```

* **Header `Authorization` absent, ou IP non whitelistée sur une clé sécurisée** : `403 Not authorized to access this resource`

```json theme={null}
{
  "success": false,
  "message": "Not authorized to access this resource"
}
```

* **Token invalide** : `401 Invalid bearer token`

```json theme={null}
{
  "success": false,
  "message": "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](https://developers.avest.fr/endpoints/patch-match.md).

## 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` :

```json theme={null}
{
  "success": false,
  "message": "Rate limit exceeded",
  "retryAfter": 27
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.