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

# Qualifier un acquéreur

> Fait sortir une fiche acquéreur de « à qualifier » : en recherche, ou archivée.

Qualifie un **prospect acquéreur**. C'est l'action que réalise un agent depuis l'inbox « Prospect acquéreur » : la fiche sort de l'étape `AQUL` (à qualifier) pour passer en recherche ou être archivée.

## Endpoint

**URL** : `/external-integration/acquisition/{acquisitionId}/qualify`
**Méthode** : `POST`
**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).

> [!WARNING]
>
> Cette action a des effets métier : elle **clôt la séquence de relance de
> qualification** de la fiche, et peut faire évoluer la mise en relation
> d'origine. Un traitement en masse éteint donc des relances automatiques
> côté agents.

## Path Parameters

| Paramètre | Type | Requis | Description |
| - | - | - | - |
| `acquisitionId` | ObjectId | ✅ | ObjectId de l'acquisition. |

## Body Parameters

| Champ | Type | Requis | Description |
| - | - | - | - |
| `acquisitionStep` | String | ✅ | `ASRC` (en recherche) ou `AARC` (archivée). Aucune autre valeur. |
| `stepUpdateReason` | String | | Raison d'archivage. Requis pour `AARC` : `noFollowUp` ou `unreachable`. |
| `activityId` | ObjectId | | Tâche de qualification que l'action vient clore. |
| `originMatch` | Object | | `{ matchId, step, visitStartAt?, visitEndAt? }`, mise en relation à l'origine de la demande. |

### `originMatch`

Permet de faire évoluer en même temps la mise en relation qui a généré la demande. `matchId` doit appartenir à l'acquisition qualifiée, et la mise en relation doit être à l'étape `MRQT` (demande). Déjà à l'étape visée, elle reste inchangée.

| Champ | Type | Requis | Description |
| - | - | - | - |
| `matchId` | ObjectId | ✅ | Mise en relation à faire évoluer. |
| `step` | String | ✅ | Étape cible : `MCNV`, `MVST`, `MNGT`, `MOFF`, `MOFA` ou `MRQT_NF`. |
| `visitStartAt` | ISO 8601 | ⚠️ | **Obligatoire si `step` vaut `MVST`.** Début de la visite : Avest crée la visite sur la mise en relation, attribuée à son responsable, comme [POST une visite](https://developers.avest.fr/endpoints/match-visits.md). |
| `visitEndAt` | ISO 8601 | ❌ | Fin de la visite. |

> [!WARNING]
>
> **Changement du 21 octobre 2026.** Viser `MVST` sans `visitStartAt` est
> refusé (`400`) et rien n'est écrit : ni la mise en relation, ni la
> qualification de la fiche. Une mise en relation déjà en `MVST` reste
> inchangée, même sans date.

## Exemple

```bash theme={null}
curl -X POST "https://api.avest.fr/v1/external-integration/acquisition/619b46b47e043165f206db1c/qualify" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "acquisitionStep": "ASRC",
    "originMatch": { "matchId": "619b46b47e043165f206db1e", "step": "MCNV" }
  }'
```

Qualifier la fiche et planifier la visite de la mise en relation d'origine :

```bash theme={null}
curl -X POST "https://api.avest.fr/v1/external-integration/acquisition/619b46b47e043165f206db1c/qualify" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "acquisitionStep": "ASRC",
    "originMatch": { "matchId": "619b46b47e043165f206db1e", "step": "MVST", "visitStartAt": "2026-10-24T14:00:00.000Z" }
  }'
```

Archiver une fiche injoignable :

```bash theme={null}
curl -X POST "https://api.avest.fr/v1/external-integration/acquisition/619b46b47e043165f206db1c/qualify" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "acquisitionStep": "AARC", "stepUpdateReason": "unreachable" }'
```

La réponse renvoie l'acquisition au format public, identique à [GET Acquisition](https://developers.avest.fr/endpoints/get-acquisition.md).

## Réponses d'erreur

| Message | Cause |
| - | - |
| `ExternalIntegrationQualifyAcquisition : acquisitionStep is required` | Champ absent. |
| `ExternalIntegrationQualifyAcquisition : originMatch must be an object` | `originMatch` mal formé (`null`, tableau, chaîne). |
| `ExternalIntegrationQualifyAcquisition : Invalid originMatch.matchId` | ObjectId invalide. |
| `ExternalIntegrationQualifyAcquisition : Unable to find acquisition` | Fiche inexistante ou hors périmètre. |
| `Invalid acquisition step` | `acquisitionStep` autre que `ASRC` / `AARC`. |
| `Invalid stepUpdateReason` | Raison d'archivage inconnue. |
| `Acquisition step too advanced to qualify` | La fiche est déjà en négociation / offre / achat signé (`409`). |
| `Match does not belong to acquisition` | `originMatch.matchId` n'appartient pas à cette fiche. |
| `Visit date required to plan a visit` | `originMatch.step` vaut `MVST` sans `originMatch.visitStartAt` valide (`400`, `errorCode: VISIT_DATE_REQUIRED`). |
| `Invalid origin match step` | `originMatch.step` hors de la liste (`400`). |
| `Le statut de cette demande a changé entre-temps, rafraîchissez la fiche.` | La mise en relation n'est plus à l'étape `MRQT` (`409`). |

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