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

# Visites d'un match

> Lire, créer, modifier et annuler les visites rattachées à une mise en relation.

Depuis le parcours acquéreur v3, une visite est un **objet daté rattaché au match**, pas une simple date posée sur la fiche. Ces routes permettent de les lire et de les écrire directement, sans passer par la liste générique des activités.

> [!NOTE]
>
> Pour lire les visites, préférez `GET .../visits` à
> [GET Activities](https://developers.avest.fr/endpoints/get-activities.md) : la réponse est déjà filtrée sur
> les visites, triée par date de visite, et enrichie d'un `derivedStatus`.

## Endpoints

| Méthode | URL | Rôle |
| - | - | - |
| `GET` | `/external-integration/match/{matchId}/visits` | Lister les visites du match |
| `POST` | `/external-integration/match/{matchId}/visit` | Créer une visite |
| `PATCH` | `/external-integration/match/{matchId}/visit/{activityId}` | Modifier ou annuler une visite |

**Authentification** : token LinkedAPI avec scope `externalIntegration`. Les routes `POST` et `PATCH` exigent l'autorisation en écriture sur ce scope — un token en lecture seule reçoit `403 Not authorized to access this resource`.
**Clé requise** : `GET` avec toutes les clés ; `POST` et `PATCH` en lecture-écriture (une clé en lecture seule reçoit `403`). Voir [Types de clé](https://developers.avest.fr/guides/authentification.md).

> [!WARNING]
>
> **Écrire une visite déplace le match.** Créer une visite promeut
> automatiquement le match à l'étape `MVST` s'il était à une étape antérieure.
> Annuler la **dernière** visite active le redescend à `MCNV`. Ces effets sont
> volontaires : ils alimentent l'inbox Prospect et les relances des agents.
> [PATCH Match](https://developers.avest.fr/endpoints/patch-match.md) refuse `MVST` sur un match sans visite
> active : pour planifier une visite, créez-la ici.

## Headers

```
Content-Type: application/json
Authorization: Bearer {token}
```

## `GET` — lister les visites

### Path Parameters

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

### Réponse

```json theme={null}
{
  "success": true,
  "visits": [
    {
      "id": "6a044cba8db14b3fbd015208",
      "type": "visit",
      "deadline": "2026-08-04T14:00:00.000Z",
      "completionDate": "2026-08-04T14:00:00.000Z",
      "owner": "66cc91f05f84c9b212d9ec24",
      "linkedDocument": "619b46b47e043165f206db1e",
      "linkedModel": "match",
      "data": {
        "visitStartAt": "2026-08-04T14:00:00.000Z",
        "visitEndAt": "2026-08-04T14:45:00.000Z",
        "isCancelled": false,
        "derivedStatus": "completed"
      },
      "createdAt": "2026-08-01T09:12:00.000Z"
    }
  ]
}
```

Les visites sont triées par `data.visitStartAt` décroissant (la plus récente d'abord).

### `data.derivedStatus`

Calculé par Avest à la lecture, il évite de recalculer l'état côté client :

| Valeur | Signification |
| - | - |
| `planned` | Visite à venir ou du jour même (jour calendaire de l'agence, dans son fuseau), non annulée. Une visite du jour reste `planned` jusqu'à minuit, heure de l'agence, même une fois l'heure passée. |
| `completed` | La visite date d'un jour antérieur, dans le fuseau de l'agence. |
| `cancelled` | `data.isCancelled` vaut `true`. |

## `POST` — créer une visite

### Body Parameters

| Champ | Type | Requis | Description |
| - | - | - | - |
| `visitStartAt` | ISO 8601 | ✅ | Début de la visite. Une date passée crée une visite déjà réalisée. |
| `visitEndAt` | ISO 8601 | | Fin de la visite. |
| `content` | String | | Note libre attachée à la visite. |
| `owner` | ObjectId | | Agent à qui attribuer la visite. Doit appartenir au périmètre du token. |

Si `owner` est absent, la visite est attribuée au **responsable du match**.

### Exemple

```bash theme={null}
curl -X POST "https://api.avest.fr/v1/external-integration/match/619b46b47e043165f206db1e/visit" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "visitStartAt": "2026-08-04T14:00:00.000Z",
    "visitEndAt": "2026-08-04T14:45:00.000Z",
    "content": "Visite accompagnée, acquéreur ponctuel"
  }'
```

Réponse `201` :

```json theme={null}
{
  "success": true,
  "visit": {
    "id": "6a044cba8db14b3fbd015208",
    "type": "visit",
    "data": { "visitStartAt": "2026-08-04T14:00:00.000Z", "isCancelled": false, "derivedStatus": "planned" }
  }
}
```

## `PATCH` — modifier ou annuler une visite

### Path Parameters

| Paramètre | Type | Requis | Description |
| - | - | - | - |
| `matchId` | ObjectId | ✅ | ObjectId du match. |
| `activityId` | ObjectId | ✅ | ObjectId de la visite à modifier. |

### Body Parameters

Au moins **un** champ doit être fourni.

| Champ | Type | Description |
| - | - | - |
| `isCancelled` | Boolean | `true` annule la visite (réversible : renvoyez `false` pour la rouvrir). |
| `visitStartAt` | ISO 8601 | Nouvelle date de début (déplacement de la visite). |
| `visitEndAt` | ISO 8601 | Nouvelle date de fin. |
| `content` | String | Note libre. |
| `owner` | ObjectId | Réattribution à un agent de votre périmètre. |

> [!NOTE]
>
> Il n'y a **pas de suppression** de visite via l'API. L'annulation
> (`isCancelled: true`) couvre le besoin et reste réversible ; elle conserve
> l'historique côté agent.

## Réponses d'erreur

| Message | Cause |
| - | - |
| `ExternalIntegrationCreateMatchVisit : visitStartAt is required` | `visitStartAt` absent au `POST`. |
| `ExternalIntegrationCreateMatchVisit : Invalid visitStartAt` | Date non interprétable. |
| `ExternalIntegrationCreateMatchVisit : Invalid matchId` | `matchId` n'est pas un ObjectId valide. |
| `ExternalIntegrationCreateMatchVisit : Unable to find match` | Match inexistant **ou hors de votre périmètre**. |
| `... : owner is not in the authorized scope of this LinkedAPI` | L'agent visé n'appartient à aucune de vos agences. |
| `ExternalIntegrationUpdateMatchVisit : No editable field provided. Allowed: isCancelled, visitStartAt, visitEndAt, content, owner` | Body vide au `PATCH`. |
| `ExternalIntegrationUpdateMatchVisit : isCancelled must be a boolean` | Type invalide. |

Un match hors périmètre répond « Unable to find match » : aucune différence n'est faite entre « n'existe pas » et « pas autorisé ».

## Rate limits

`GET` : **500 req / minute**. `POST` et `PATCH` : **100 req / minute** (bucket d'écriture partagé avec les autres routes en écriture).

Headers sur toutes les réponses : `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`.


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