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

# Offres d'un match

> Lire, créer et faire évoluer les offres rattachées à une mise en relation.

Comme les visites, une offre est un **objet daté rattaché au match**. Ces routes permettent de la lire et de l'écrire directement.

## Endpoints

| Méthode | URL | Rôle |
| - | - | - |
| `GET` | `/external-integration/match/{matchId}/offers` | Lister les offres du match |
| `POST` | `/external-integration/match/{matchId}/offer` | Créer une offre |
| `PATCH` | `/external-integration/match/{matchId}/offer/{activityId}` | Faire évoluer une offre |

**Authentification** : token LinkedAPI avec scope `externalIntegration`. `POST` et `PATCH` exigent l'autorisation en écriture.
**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]
>
> **Le statut `accepted` n'est pas accepté par l'API externe.** Accepter une
> offre écrit sur la vente (prix, honoraires, financement), la fait passer à
> l'étape `OFR` et **classe sans suite toutes les autres mises en relation du
> bien** — y compris des acquéreurs hors de votre périmètre. Cette action reste
> volontairement dans l'application Avest.

> [!WARNING]
>
> Créer une offre promeut automatiquement le match à l'étape `MOFF` s'il était à
> une étape antérieure. Un statut terminal (`rejected`, `withdrawn`,
> `cancelled`) peut à l'inverse classer le match « sans suite ».

## Headers

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

## `GET` — lister les offres

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

```json theme={null}
{
  "success": true,
  "offers": [
    {
      "id": "6a044cba8db14b3fbd015209",
      "type": "offer",
      "owner": "66cc91f05f84c9b212d9ec24",
      "linkedDocument": "619b46b47e043165f206db1e",
      "linkedModel": "match",
      "data": {
        "amount": 250000,
        "sellPrice": 250000,
        "status": "transmitted",
        "offerDate": "2026-08-05T09:00:00.000Z",
        "statusHistory": [{ "status": "transmitted", "date": "2026-08-05T09:00:00.000Z" }]
      },
      "createdAt": "2026-08-05T09:00:00.000Z"
    }
  ]
}
```

Les offres sont triées par `data.offerDate` décroissant.

En charge partagée (`feeResponsibility: both`), une offre saisie dans Avest peut porter la part vendeur des honoraires : `data.sellerAgencyCommission`, et `data.sellerAgencyCommissionPercentage` en mode pourcentage. Ces champs ne s'écrivent pas par l'API.

## `POST` — créer une offre

### Body Parameters

`offerDate` est requis, ainsi qu'**au moins un** de `sellPrice` / `agencyCommission`.

| Champ | Type | Description |
| - | - | - |
| `offerDate` | ISO 8601 | Date de l'offre. **Requis.** |
| `sellPrice` | Number | Prix net vendeur proposé. |
| `agencyCommission` | Number | Honoraires d'agence. |
| `status` | String | Voir le tableau ci-dessous. Défaut : `transmitted`. |
| `feeResponsibility` | String | Charge des honoraires. |
| `financing` | String | Mode de financement. |
| `deposit` | Number | Dépôt de garantie. |
| `counterOfferAmount` | Number | Montant de la contre-proposition. |
| `content` | String | Note libre. |
| `owner` | ObjectId | Agent à qui attribuer l'offre (dans votre périmètre). |

### Statuts d'offre

| Statut | Accepté en externe | Signification |
| - | - | - |
| `transmitted` | ✅ | Offre transmise au vendeur. |
| `received` | ✅ | Offre reçue. |
| `rejected` | ✅ | Offre refusée. |
| `rejected_counter_offer` | ✅ | Refusée avec contre-proposition. |
| `withdrawn` | ✅ | Offre retirée par l'acquéreur. |
| `cancelled` | ✅ | Offre annulée. |
| `accepted` | ❌ | Réservé à l'application Avest. |

### Exemple

```bash theme={null}
curl -X POST "https://api.avest.fr/v1/external-integration/match/619b46b47e043165f206db1e/offer" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "offerDate": "2026-08-05T09:00:00.000Z",
    "sellPrice": 250000,
    "status": "transmitted"
  }'
```

## `PATCH` — faire évoluer une offre

Mêmes champs que le `POST` (tous optionnels, au moins un requis), plus les path parameters `matchId` et `activityId`. `accepted` y est refusé de la même manière.

En charge partagée, des honoraires (`agencyCommission`) inférieurs à la part vendeur enregistrée sont refusés (`400`) et l'offre n'est pas modifiée. Passer `feeResponsibility` à `seller` ou `buyer` efface la part vendeur.

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

## Réponses d'erreur

| Message | Cause |
| - | - |
| `ExternalIntegrationCreateMatchOffer : offerDate is required` | `offerDate` absent. |
| `ExternalIntegrationCreateMatchOffer : sellPrice or agencyCommission is required` | Aucun montant fourni. |
| `ExternalIntegrationCreateMatchOffer : sellPrice must be a number` | Montant envoyé en chaîne. |
| `ExternalIntegrationCreateMatchOffer : status must be one of: transmitted, received, rejected, rejected_counter_offer, withdrawn, cancelled` | `accepted` ou statut inconnu. |
| `ExternalIntegrationUpdateMatchOffer : Invalid activityId` | `activityId` invalide. |
| `ExternalIntegrationCreateMatchOffer : Unable to find match` | Match inexistant ou hors périmètre. |
| `offer.sellerAgencyCommission must not exceed offer.agencyCommission` | `PATCH` qui ramène `agencyCommission` sous la part vendeur enregistrée, en charge partagée. Message sans préfixe de classe. |

## Rate limits

`GET` : **500 req / minute**. `POST` et `PATCH` : **100 req / minute**.


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