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

# PATCH Sale

> Met à jour une vente existante en la ciblant par son identifiant, sans risque de doublon.

Met à jour une vente existante — typiquement pour **faire avancer son étape** — en la ciblant par son **identifiant** plutôt que par contact + adresse.

> [!NOTE]
>
> [POST Sale](https://avest.mintlify.site/endpoints/post-sale.md) retrouve la vente par **contact + adresse**.
> Si l'adresse que vous envoyez ne correspond pas exactement à celle
> enregistrée, une **seconde vente** est créée. Dès que vous connaissez déjà la
> vente, utilisez cette route : le ciblage par identifiant supprime ce risque, et
> il ne relance ni le routage, ni l'allocation, ni les alertes leadgen.

## Endpoint

**URL** : `/external-integration/sale/{saleId}`
**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://avest.mintlify.site/guides/authentification.md).

## Path Parameters

| Paramètre | Type | Requis | Description |
| - | - | - | - |
| `saleId` | String | ✅ | `id` (ObjectId) **ou** `customId` de la vente. |

Les deux formes sont renvoyées en lecture par [GET Sale](https://avest.mintlify.site/endpoints/get-sale.md) et par la recherche. Un `customId` n'est jamais un ObjectId, il n'y a donc pas d'ambiguïté sur la forme.

> [!WARNING]
>
> Si un `customId` correspond à **plusieurs ventes** de votre périmètre, la
> requête est refusée (`400`) au lieu d'en modifier une au hasard. Ciblez alors
> par `id`.

## Body Parameters

Au moins **un** champ. Seuls les champs listés sont modifiables.

| Champ | Type | Description |
| - | - | - |
| `step` | String | Nouvelle étape de la vente (voir ci-dessous). |
| `stepUpdateReason` | String | Motif accompagnant le changement d'étape. Voir « Motifs » ci-dessous. |
| `project` | String | Projet du vendeur (`S\|S`, `S\|L`, `S\|O`, `APT`…). |
| `status` | String | Statut, dépendant de l'étape courante. |
| `fieldValue` | `{ low, high }` | Estimation réalisée sur le terrain. |
| `onlineValue` | `{ low, high }` | Estimation en ligne. |
| `timeline` | Object | Dates officielles du dossier. Voir [Dates de la fiche](#dates-de-la-fiche). |
| `appointment` | Object | Rendez-vous d'estimation. Voir [Poser un rendez-vous](#poser-un-rendez-vous). |
| `property` | Object | Caractéristiques du bien (surface, type, pièces…). |
| `address` | String | Adresse en texte libre, géocodée comme à la création. |
| `owner` | ObjectId | Collaborateur responsable de la fiche. |
| `tags` | ObjectId\[] | Liste **complète** des tags. Voir [Tags](#tags). |
| `mandate` | Object | Mandat (prix, honoraires, type, échéance…). |
| `offer` | Object | Offre acceptée. Enregistrée seulement sur une vente à `MND` ou au-delà ; un changement d'étape vers une autre étape que `OFR`, `AGT`, `MTG` ou `SLD` l'efface. Pour poser une offre, envoyez `step: "OFR"` dans la même requête. |

Dans `mandate` et `offer`, `sellPrice` est le net vendeur et `agencyCommission` un montant en euros, comme sur [POST Sale](https://avest.mintlify.site/endpoints/post-sale.md). Le prix affiché (`price`) se calcule seul : n'envoyez pas le prix honoraires inclus dans `sellPrice`, et n'envoyez pas `price`.

### Part vendeur des honoraires (`mandate` et `offer`)

En charge `both`, `mandate` et `offer` acceptent la part vendeur :

```typescript theme={null}
sellerAgencyCommission?: number;           // Part vendeur, charge "both" seulement
sellerAgencyCommissionPercentage?: number; // [0;100[, part vendeur en %, lue en mode "percentage"
```

Une part vendeur négative, non numérique ou supérieure à `agencyCommission` est refusée (`400`). Sans elle, un nouveau total garde la proportion de la part déjà enregistrée. Elle est vidée dès que la charge n'est plus `both`.

### Honoraires en pourcentage (`mandate`)

`mandate.commissionType` (`percentage` ou `value`) donne le mode des honoraires, et `mandate.commissionPercentage` leur taux en mode `percentage`. Hors du mode `value`, un `commissionPercentage` hors de 0 (inclus) à 100 (exclu) est refusé (`400`), avec le message `mandate.commissionPercentage must be a number between 0 (included) and 100 (excluded)`, sans préfixe de classe. Renvoyer la valeur déjà enregistrée passe toujours. En mode `value`, un `commissionPercentage` transmis est ignoré : Avest le calcule depuis les montants.

### Étapes (`step`)

`STK`, `TRN`, `ARC`, `PQUL`, `QUL`, `CNV`, `RDV`, `DLV`, `MND`, `TARC`, `OFR`, `AGT`, `MTG`, `SLD`.

Le changement d'étape produit les **mêmes effets que depuis l'interface** : activité de changement d'étape, mise à jour de `stepUpdatedAt`, recalcul de la commission, et **clôture des activités à faire** de la fiche quand la nouvelle étape va de `QUL` à `DLV` (rendez-vous compris, visites et offres exceptées). Il peut aussi lancer les séquences d'activités que l'agence a paramétrées pour cette étape (par exemple une série d'appels de qualification). Pour poser un rendez-vous en changeant d'étape, envoyez `step` et `appointment` dans la même requête : le rendez-vous est créé après le changement d'étape et reste ouvert. Contrairement au match, une vente peut revenir en arrière dans le pipeline.

> [!WARNING]
>
> **Une vente active a toujours un responsable.** Dans l'interface, le
> collaborateur qui déplace la fiche en devient responsable ; via l'API, il n'y
> a pas de collaborateur. Pour sortir une vente sans responsable de `STK`,
> `TRN`, `PQUL`, `ARC`, `SLD` ou `TARC`, envoyez `owner` **dans la même
> requête** que `step`. Sans `owner`, l'étape reste inchangée et la réponse est
> quand même un `200` : vérifiez `step` dans la réponse.

> [!WARNING]
>
> **Passer une vente en `STK` (pioche)** retire son responsable et **supprime
> ses activités non clôturées** (tâches, rappels, rendez-vous à venir), y
> compris celles créées via [POST Activity](https://avest.mintlify.site/endpoints/post-activity.md). Les
> visites et offres sont conservées.

> [!WARNING]
>
> **Non modifiables par cette route** : `contacts`, `customId`,
> `parsingCustomId`, `commission` et `state`. Nous préférons refuser un champ
> plutôt que de l'accepter sans l'appliquer — un objet dont **aucune** clé n'est
> modifiable est rejeté, plutôt que de répondre `200` sans rien écrire.

### Motifs (`stepUpdateReason`)

| Valeur | Sens | Accepté vers |
| - | - | - |
| `fakePhone` | Faux numéro | `ARC`, autres étapes |
| `unreachable` | Injoignable | `ARC`, autres étapes |
| `spam` | Spam | `ARC`, autres étapes |
| `noFollowUp` | Sans suite | `ARC`, `TARC`, autres étapes |
| `lostMandate` | Mandat perdu | `ARC`, `TARC`, autres étapes |
| `marketedElsewhere` | Commercialisé ailleurs | `TARC`, autres étapes |
| `soldByOtherAgency` | Vendu par une autre agence | `TARC`, autres étapes |
| `soldByOwner` | Vendu par le propriétaire | `TARC`, autres étapes |
| `saleWithdrawn` | Vente retirée | `TARC`, autres étapes |

Un motif non accepté pour l'étape visée est refusé en `400` (`Invalid stepUpdateReason for step ARC`). `fakePhone` marque aussi les téléphones du contact comme invalides.

## Dates de la fiche

`timeline` porte les dates **officielles** affichées sur la fiche. Ce sont elles que lisent le suivi de dossier et les exports — pas les dates des activités.

| Date | Sens |
| - | - |
| `estimationDate` | Rendez-vous d'estimation. |
| `estimationStartAt` | Heure de début du rendez-vous. |
| `estimationEndAt` | Heure de fin du rendez-vous. |
| `mandateSignatureDate` | Signature du mandat. |
| `offerDate` | Offre acceptée. |
| `agreementDate` | Compromis signé. |
| `mortgageDeadline` | Échéance de la clause suspensive de crédit. |
| `closingDate` | Acte authentique. |
| `agreementExpirationDate` | Expiration du compromis. |

Toutes sont des chaînes de date ISO 8601. Envoyer `null` sur une date l'efface.

```json theme={null}
{
  "timeline": {
    "agreementDate": "2026-09-15T00:00:00.000Z",
    "mortgageDeadline": "2026-10-30T00:00:00.000Z",
    "closingDate": "2026-12-05T00:00:00.000Z"
  }
}
```

## Poser un rendez-vous

`appointment` est le raccourci qui reproduit le geste de l'interface : il renseigne le créneau d'estimation **et** crée l'activité « Rendez-vous estimation » sur la fiche. Le même champ existe sur [POST Sale](https://avest.mintlify.site/endpoints/post-sale.md), où il crée l'activité sans renseigner les dates de la fiche.

| Champ | Type | Requis | Description |
| - | - | - | - |
| `date` | String | ✅ | Date ISO du rendez-vous. |
| `startAt` | String | — | Heure de début (ISO 8601). |
| `endAt` | String | — | Heure de fin (ISO 8601). |
| `note` | String | — | Reportée dans l'activité créée. |

```json theme={null}
{
  "step": "RDV",
  "appointment": {
    "date": "2026-09-01T14:00:00.000Z",
    "endAt": "2026-09-01T15:00:00.000Z",
    "note": "Rendez-vous pris depuis notre outil."
  }
}
```

L'activité créée est renvoyée dans la réponse, sous la clé `activity`.

> [!NOTE]
>
> Contrairement à la création, une **date passée est acceptée** : cette route
> sert aussi à rattraper un rendez-vous déjà tenu.

> [!WARNING]
>
> `appointment.date` et `timeline.estimationDate` écrivent la même date : les
> envoyer tous les deux est refusé. Utilisez `appointment` pour poser le
> rendez-vous (activité comprise), `timeline` seul pour corriger une date sans
> créer d'activité.

## Adresse et bien

`property` accepte les caractéristiques du bien : `mainType`, `developmentType`, `generalCondition`, `size`, `livingSurface`, `landSurface`, `rooms`, `bedrooms`, `floor`, `buildingYear`… — les mêmes champs qu'à la création.

L'adresse ne s'écrit **pas** dans `property` : envoyez `address` en texte libre, elle est géocodée exactement comme à la création.

```json theme={null}
{
  "address": "12 rue des Lilas 31400 Toulouse",
  "property": { "livingSurface": 78, "rooms": 4 }
}
```

> [!WARNING]
>
> L'adresse est située par Google. Si Google ne situe que la ville, la vente
> est enregistrée avec la ville seule, sans numéro ni rue, et la réponse reste
> un succès. Relisez `property.addressData` dans la réponse : sans
> `streetNumber` ni `route`, renvoyez `address` écrite autrement (sans
> complément, sans lieu-dit). `property.addressData` n'est pas modifiable.

## Attribution et tags

`owner` réattribue la fiche. L'utilisateur doit appartenir aux agences de votre clé API — récupérez son ObjectId via [GET Users](https://avest.mintlify.site/endpoints/get-users.md). Sinon la requête est refusée et **rien n'est écrit**.

### Tags

`tags` remplace la liste : les tags absents du tableau sont **retirés** de la vente. Envoyez `[]` pour tout retirer. Chaque identifiant doit correspondre à un tag existant de votre périmètre. Les ajouts et retraits produisent les mêmes entrées d'historique que depuis l'interface.

## Exemple

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

Ciblage par `customId` :

```bash theme={null}
curl -X PATCH "https://api.avest.fr/v1/external-integration/sale/AB12" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldValue": { "low": 285000, "high": 310000 }
  }'
```

La réponse renvoie la vente au format public, identique à [GET Sale](https://avest.mintlify.site/endpoints/get-sale.md) — plus la clé `activity` si un `appointment` a été fourni.

## Concurrence

Si la vente est modifiée simultanément par un agent, la requête est rejouée automatiquement. En cas d'échec persistant, la réponse est `409` avec le code `TRANSACTION_EDIT_CONFLICT` — rejouez la requête.

## Réponses d'erreur

| Message | Cause |
| - | - |
| `ExternalIntegrationUpdateSale : saleId is required` | Identifiant absent. |
| `ExternalIntegrationUpdateSale : No editable field provided. Allowed: …` | Body vide, ou uniquement des champs non modifiables. |
| `ExternalIntegrationUpdateSale : Invalid step. Allowed: …` | Étape hors de la liste. |
| `Invalid stepUpdateReason for step ARC` | Motif non accepté pour l'étape visée (message sans préfixe). |
| `mandate.commissionPercentage must be a number between 0 (included) and 100 (excluded)` | Pourcentage d'honoraires hors plage, hors du mode `value` (message sans préfixe). |
| `ExternalIntegrationUpdateSale : Unable to find sale` | Vente inexistante ou hors de votre périmètre. |
| `ExternalIntegrationUpdateSale : Ambiguous customId: several sales match…` | Plusieurs ventes portent ce `customId` — ciblez par `id`. |
| `ExternalIntegrationUpdateSale : No editable field provided in property` | Objet imbriqué ne contenant aucun champ modifiable. |
| `ExternalIntegrationUpdateSale : Invalid timeline.estimationDate` | Date non conforme à l'ISO 8601. |
| `ExternalIntegrationUpdateSale : appointment.date and timeline.estimationDate cannot both be provided` | Deux sources pour la même date. |
| `ExternalIntegrationUpdateSale : owner is not in the authorized scope of this LinkedAPI` | `owner` hors des agences de la clé. |
| `ExternalIntegrationUpdateSale : Unknown saleTag in the authorized scope: …` | Tag inexistant ou hors de votre périmètre. |

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