> ## 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.

# PATCH Match

> Fait avancer l'étape d'une mise en relation, ou la classe sans suite.

Fait progresser une **mise en relation existante** dans l'entonnoir commercial. C'est la route à utiliser quand votre outil sait qu'un acquéreur a été relancé, s'est déplacé, ou s'est désisté.

## Endpoint

**URL** : `/external-integration/match/{matchId}`
**Méthode** : `PATCH`
**Authentification** : token LinkedAPI avec scope `externalIntegration` en écriture.
**Clé requise** : lecture-écriture. Une clé en lecture seule reçoit `403`. Voir [Types de clé](https://developers.avest.fr/guides/authentification.md).

> [!NOTE]
>
> Seule l'étape est modifiable. Les autres champs du match (rapprochement,
> contacts, tags) ne sont pas éditables via l'API.

## Path Parameters

| Paramètre | Type | Requis | Description |
| - | - | - | - |
| `matchId` | ObjectId | ✅ | ObjectId du match. |

## Body Parameters

| Champ | Type | Requis | Description |
| - | - | - | - |
| `step` | String | ✅ | Étape cible. Voir les règles de transition ci-dessous. |
| `stepUpdateReason` | String | | Raison du changement. **Obligatoire** pour classer sans suite (`_NF`). |

## Règles de transition

L'entonnoir est **à sens unique**. Trois règles :

1. **On peut monter.** Toute étape de poids supérieur à l'étape courante est acceptée (`MSND` → `MCNV`, `MRQT` → `MNGT`…). Les sauts d'étape sont permis. Seule exception : `MVST` exige une visite active (voir ci-dessous).
2. **On peut classer sans suite, sur place.** Depuis `MVST`, seule `MVST_NF` est acceptée — et `stepUpdateReason` devient obligatoire. On ne peut pas classer sans suite à un stade que la mise en relation n'a jamais atteint.
3. **On ne redescend jamais.** Une régression est refusée, et une étape `_NF` est **terminale** : un match classé sans suite ne peut pas être rouvert via l'API (rouvrir ressusciterait ses offres retirées côté Avest).

| Étape courante | `step` demandé | Résultat |
| - | - | - |
| `MSND` | `MVST` | ✅ si le match a une visite active, ❌ sinon |
| `MRQT` | `MRQT_NF` | ✅ accepté (avec `stepUpdateReason`) |
| `MVST` | `MRQT` | ❌ régression refusée |
| `MVST` | `MRQT_NF` | ❌ stade jamais atteint |
| `MVST_NF` | `MVST` | ❌ étape terminale, réouverture impossible |
| n'importe | `MOFA` | ❌ voir ci-dessous |

> [!WARNING]
>
> **`MOFA` et `MOFA_NF` ne sont pas accessibles via l'API.** Passer une mise en
> relation en « offre acceptée » écrit sur la vente, la fait basculer à l'étape
> `OFR` et **classe sans suite toutes les autres mises en relation du bien**.
> Cette action reste dans l'application Avest, au même titre que le statut
> d'offre `accepted`.

## `MVST` exige une visite

Un match ne passe en `MVST` (« Visite planifiée ») que s'il porte **au moins une visite active** (ni annulée ni supprimée). Sans visite, la requête est refusée en `400` et l'étape ne change pas :

```json theme={null}
{
  "success": false,
  "errorCode": "VISIT_DATE_REQUIRED",
  "message": "Visit date required to plan a visit"
}
```

Ce message n'est pas préfixé par `ExternalIntegrationUpdateMatchStep`. Pour planifier une visite, créez-la avec [POST une visite](https://developers.avest.fr/endpoints/match-visits.md) : la date est enregistrée **et** le match passe en `MVST`.

Le détail des 14 étapes est documenté dans [GET Match](https://developers.avest.fr/endpoints/get-match.md).

## Exemple

```bash theme={null}
curl -X PATCH "https://api.avest.fr/v1/external-integration/match/619b46b47e043165f206db1e" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "step": "MNGT" }'
```

```json theme={null}
{
  "success": true,
  "match": {
    "id": "619b46b47e043165f206db1e",
    "customId": "M-2025-001",
    "step": "MNGT",
    "origin": "manual",
    "sale": "619b46b47e043165f206db1b",
    "acquisition": "619b46b47e043165f206db1c",
    "tags": [],
    "createdAt": "2026-05-13T10:04:42.139Z"
  }
}
```

> [!NOTE]
>
> Pour déclarer une visite, utilisez
> [POST une visite](https://developers.avest.fr/endpoints/match-visits.md) : le match passe automatiquement en
> `MVST` **et** la date est enregistrée. Cette route ne pose que l'étape, et
> refuse `MVST` sans visite active.

## Réponses d'erreur

| Message | Cause |
| - | - |
| `ExternalIntegrationUpdateMatchStep : step is required` | `step` absent. |
| `ExternalIntegrationUpdateMatchStep : Invalid step. Allowed: …` | Étape inconnue, ou `MOFA` / `MOFA_NF`. |
| `ExternalIntegrationUpdateMatchStep : Match is already at step MVST` | Aucun changement demandé. |
| `ExternalIntegrationUpdateMatchStep : Step regression from MVST to MRQT is not allowed` | Régression. |
| `ExternalIntegrationUpdateMatchStep : Only MVST_NF can close a match currently at MVST` | Mauvaise variante `_NF`. |
| `ExternalIntegrationUpdateMatchStep : stepUpdateReason is required to close a match` | Clôture sans raison. |
| `ExternalIntegrationUpdateMatchStep : Match is closed at MVST_NF and cannot be reopened through the external API` | Réouverture. |
| `ExternalIntegrationUpdateMatchStep : Unable to find match` | Match inexistant ou hors périmètre. |
| `Visit date required to plan a visit` (`errorCode: VISIT_DATE_REQUIRED`) | `MVST` demandé sans visite active. |

## Rate limits

**100 req / minute par groupe d'agences** (bucket d'écriture).


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