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

# GET Sale

> Récupère une vente par son id Mongo ou son customId métier, avec ses contacts liés.

Récupère une vente par son `id` MongoDB ou son `customId` métier, avec ses contacts liés.

## Endpoint

**URL** : `/external-integration/sale`
**Méthode** : `GET`
**Authentification** : Requiert un token LinkedAPI avec scope `externalIntegration` (GET) et `agencyGroup` configuré.
**Clé requise** : toutes les clés (lecture seule suffit). Voir [Types de clé](https://avest.mintlify.site/guides/authentification.md).

## Headers

```
Authorization: Bearer {token}
X-Real-IP: {ip_whitelistée}     # Requis uniquement si linkedAPI.secure === true
```

## Query Parameters

| Paramètre | Type | Requis | Description |
| - | - | - | - |
| `id` | ObjectId | ✅ ou ✅\* | Identifiant Mongo de la vente (24 chars hex) |
| `customId` | String | ✅\* ou ✅ | Identifiant métier (ex: `EBZJ7515`), sensible à la casse |

> [!WARNING]
>
> **Exactement un** des deux paramètres doit être fourni. Pas zéro, pas les
> deux.

Le `customId` est sensible à la casse : les références Avest sont en majuscules, et `ebzj7515` ne trouve pas la vente `EBZJ7515`.

## Exemple de requête

```bash theme={null}
GET /external-integration/sale?customId=EBZJ7515
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/sale?id=65b7e0a294432bb64b3737f3
Authorization: Bearer your-linked-api-token
```

## Logique de fonctionnement

1. **Validation des params** : Vérifie qu'un seul des deux paramètres est fourni et valide son format
2. **Recherche scopée** : Filtre sur `agencyGroup === linkedAPI.agencyGroup` ET `agency ∈ linkedAPI.agencies`
3. **Récupération des contacts** : Si vente trouvée, fetch des contacts liés (re-scopés sur les mêmes agences)
4. **Sérialisation** : Tous les champs publics renseignés sur la fiche sont retournés. Les champs **non renseignés sont absents de la réponse** (pas `null`). Le contact principal de la vente est exposé via `sale.mainContact` (ID), le détail complet du contact est dans la clé `contacts` au top-level.

## Réponse de succès

**Code** : `200`

### Vente trouvée

```json theme={null}
{
  "success": true,
  "sale": {
    "id": "6a044cba8db14b3fbd015208",
    "customId": "BCOU2162",
    "agency": "66cc91d475c9fac35c86ed80",
    "agencyGroup": "66cc8a8e75c9fac35c6ecd73",
    "step": "MND",
    "status": "awaitingLaunch",
    "project": "B",
    "property": {
      "mainType": "apartment",
      "developmentType": "old",
      "size": 65,
      "floor": 3,
      "rooms": 3,
      "bedrooms": 2,
      "bathrooms": 1,
      "isCollectiveOwnership": true,
      "addressData": {
        "streetNumber": "3",
        "route": "Avenue Reille",
        "postalCode": "75014",
        "city": "Paris",
        "country": "France",
        "countryCode": "FR",
        "formattedAddress": "3 Av. Reille, 75014 Paris, France"
      }
    },
    "mandate": {
      "price": 252000,
      "sellPrice": 240000,
      "agencyCommission": 12000,
      "type": "notExclusive",
      "referenceNumber": "1729",
      "feeResponsibility": "seller",
      "commissionPercentage": 4.76,
      "commissionType": "value",
      "mandateDuration": 3,
      "maxMandateDuration": 12
    },
    "timeline": {
      "mandateSignatureDate": "2026-05-13T14:59:03.596Z"
    },
    "createdAt": "2026-05-13T10:04:42.139Z",
    "updatedAt": "2026-05-14T09:12:30.004Z",
    "stepUpdatedAt": "2026-05-13T14:59:03.596Z",
    "owner": {
      "id": "6939530d9200187f19a2707d",
      "firstName": "Florian",
      "lastName": "PUJO",
      "picture": "https://cdn.avest.fr/attachment/user/696e2f1adff893e4465d15b3"
    },
    "mainContact": "6a044cadd494814278d1fb84"
  },
  "contacts": [
    {
      "id": "6a044cadd494814278d1fb84",
      "title": "mr",
      "firstName": "Olivier",
      "lastName": "BOYER",
      "isIndividual": true,
      "contactDetails": [
        { "type": "email", "data": "olivier.boyer@example.fr" },
        { "type": "phone", "data": "+33660598726" }
      ]
    }
  ]
}
```

### Vente non trouvée ou hors scope

```json theme={null}
{
  "success": true,
  "sale": null,
  "contacts": []
}
```

> [!NOTE]
>
> Une fiche existant dans une autre `agencyGroup` retourne ce même payload
> (`null`). Pas de différenciation possible côté client entre "n'existe pas" et
> "pas autorisé".

## Champs de la réponse

### Top-level `sale`

Toujours présents (si la vente existe) :

| Champ | Type | Description |
| - | - | - |
| `id` | String | ObjectId Mongo de la vente |
| `customId` | String | Identifiant métier (ex: `EBZJ7515`) |
| `agency` | String | ObjectId de l'agence propriétaire |
| `agencyGroup` | String | ObjectId du groupe d'agences |
| `step` | String | Étape courante de la vente (`QUL`, `CNV`, `RDV`, `MND`, `ARC`, etc.) |
| `createdAt` | ISO 8601 | Date de création de la fiche |
| `updatedAt` | ISO 8601 | Date de dernière modification. À combiner avec `sortField=updatedAt` sur `/search` pour ne resynchroniser que ce qui a changé |
| `stepUpdatedAt` | ISO 8601 | Date du dernier changement d'étape |
| `owner` | Object \| null | Utilisateur Avest responsable du dossier (`id`, `firstName`, `lastName`, `picture` optionnelle) |
| `mainContact` | String \| null | ObjectId du vendeur principal. `null` si la vente n'a aucun contact lié. À utiliser avec `GET /external-integration/contact` pour récupérer email/téléphone. |

Présents uniquement si renseignés (sinon clé absente, pas `null`) :

| Champ | Type | Description |
| - | - | - |
| `status` | String | Statut au sein de l'étape (dépend du `step`) |
| `state` | String | État d'activité (`CONTACTED`, `uncontactedWithDetails`, ...) |
| `project` | String | Projet déclaré (`B` = vendeur, etc.) |
| `parsingCustomId` | String | Identifiant interne d'import |
| `property` | Object | Bien (voir section dédiée) |
| `mandate` | Object | Mandat de vente. Peut être présent avant l'étape `MND`, par exemple réduit à `{ "mandateHistory": [] }` |
| `offer` | Object | Offre acceptée (présent à partir de l'étape `OFR`) |
| `timeline` | Object | Dates clés du dossier (mandat, offre, acte) |
| `fieldValue` | Object | Estimation terrain `{ low, high }` |
| `onlineValue` | Object | Estimation en ligne `{ low, high }` |

### `property`

`property.addressData` (toujours présent si la vente existe — adresse splittée) :

| Champ | Description |
| - | - |
| `streetNumber` | Numéro de rue |
| `route` | Voie |
| `city` | Ville |
| `postalCode` | Code postal |
| `country` | Pays |
| `countryCode` | Code pays ISO 3166-1 alpha-2 |
| `formattedAddress` | Adresse concaténée formatée |
| `department` | Département |
| `region` | Région |

Autres champs `property` retournés s'ils sont renseignés : `mainType` (`apartment`, `house`, `field`, `building`, `parking`, etc.), `developmentType` (`old` / `new`), `size` (m²), `floor`, `lotsNumbers`, `generalCondition`, `rooms`, `bedrooms`, `bathrooms`, `toilets`, `kitchenType`, `livingSurface`, `usefulSurface`, `floorSurface`, `landSurface`, `fieldSurface`, `balconyAmount`/`balconySurface`, `loggiaAmount`/`loggiaSurface`, `terraceAmount`/`terraceSurface`, `gardenAmount`/`gardenSurface`, `cellarAmount`/`cellarSurface`, `atticAmount`/`atticSurface`, `parkingType`/`parkingAmount`/`parkingSurface`, `hasElevator`, `hasPool`, `hasFireplace`, `hasArmoredDoor`, `hasOpticalFiber`, `hasVMC`, `propertyTax`, `isCollectiveOwnership`, `collectiveMonthlyCost`, `numberOfLots`, `heatingType`, `heatingEnergyType`, `waterDistributionType`, `glazingType`, `DPENumber`, `DPEEnergyValue`, `DPEEnergyTag`, `DPEGESValue`, `DPEGESTag`, `DPEDate`, `availabilityDate`, `occupancyStatus`, `sanitationType`, `isDuplex`, `hasBeautifulView`, `hasRoofTop`, `buildingYear`, `renovationYear`, `roomDetails[]`. Biens professionnels : `vatRegime` (`subject` soumis à TVA, `exempt` non soumis) et `propertyTaxResponsibility` (taxe foncière à la charge du bailleur, `owner`, ou du preneur, `tenant`).

### `mandate`

Renseigné à partir de l'étape `MND`. Avant, l'objet peut être présent sans les champs du mandat, avec seulement `mandateHistory`.

| Champ | Description |
| - | - |
| `price` | Prix affiché honoraires inclus (HAI), calculé automatiquement |
| `sellPrice` | Net vendeur |
| `agencyCommission` | Montant des honoraires |
| `feeResponsibility` | `seller` (charge vendeur), `buyer` (charge acquéreur) ou `both` (honoraires partagés) |
| `commissionPercentage` | % d'honoraires : saisi en mode `percentage`, calculé depuis les montants en mode `value`. Base : prix honoraires inclus en charge `seller`, net vendeur en `buyer`, `sellPrice + sellerAgencyCommission` en `both`. |
| `sellerAgencyCommission` | Part vendeur des honoraires, renseignée seulement en charge `both`. La part acquéreur vaut `agencyCommission − sellerAgencyCommission`. |
| `sellerAgencyCommissionPercentage` | Part vendeur en %, sur la même base que `commissionPercentage`, renseignée seulement en charge `both` et avec un `commissionType`. |
| `commissionType` | `value` (montant saisi) ou `percentage` (pourcentage saisi) |
| `type` | `exclusive`, `semiExclusive` ou `notExclusive` |
| `referenceNumber` | Numéro de mandat |
| `mandateDuration` | Durée du mandat en mois |
| `maxMandateDuration` | Durée maximale renouvellements compris (mois) |
| `expirationDate` | Date d'expiration |
| `mandateHistory` | Historique des modifications du net vendeur, des honoraires et du type de mandat : une entrée par modification, avec sa `date` et ses `changes[]` (`field`, `from`, `to`). Tableau vide si le mandat n'a jamais été modifié. |

### `offer` (à partir de step `OFR`)

| Champ | Description |
| - | - |
| `commissionPercentage` | % d'honoraires. En mode `percentage`, c'est la valeur saisie ; sinon, Avest le calcule depuis les montants, arrondi à 2 décimales. Lisez `commissionType` pour connaître le mode, pas la présence du %. |
| `commissionType` | `value` (montant fixe) ou `percentage`. |
| `sellerAgencyCommission` | Part vendeur des honoraires, renseignée seulement en charge `both`. La part acquéreur vaut `agencyCommission − sellerAgencyCommission`. |
| `sellerAgencyCommissionPercentage` | Part vendeur en %, sur la même base que `commissionPercentage`, renseignée seulement en charge `both`. |

### `timeline`

Dates renseignées seulement. Peut contenir : `mandateSignatureDate`, `agreementDate`, `agreementExpirationDate`, `offerDate`, `mortgageDeadline`, `closingDate`, `estimationDate`, `estimationStartAt`, `estimationEndAt`.

### `contacts` (top-level)

Liste des contacts liés à la vente (mêmes ObjectIds que dans `sale.contacts` côté Avest). Chaque contact :

| Champ | Description |
| - | - |
| `id` | ObjectId du contact |
| `firstName`, `lastName` | Nom de la personne (si `isIndividual: true`) |
| `commercialName`, `corporateName` | Si entreprise (`isIndividual: false`) |
| `title` | `mr` / `mme` |
| `isIndividual` | `true` (particulier) ou `false` (entreprise) |
| `contactDetails[]` | Array de `{ type: 'email' \| 'phone', data: string }` |

Le **premier élément** de l'array correspond au `mainContact` retourné au top-level (= vendeur principal).

## Réponses d'erreur

* **Aucun paramètre fourni** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetTransaction : Either id or customId is required"
}
```

* **Les deux paramètres fournis** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetTransaction : Provide either id or customId, not both"
}
```

* **`id` invalide** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetTransaction : Invalid id"
}
```

* **`customId` invalide** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetTransaction : Invalid customId"
}
```

* **LinkedAPI agencyGroup manquant** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "LinkedAPI agencyGroup is required"
}
```

* **Header `Authorization` absent, ou IP non whitelistée sur une clé sécurisée** : `403 Not authorized to access this resource`

```json theme={null}
{
  "success": false,
  "message": "Not authorized to access this resource"
}
```

* **Token invalide** : `401 Invalid bearer token`

```json theme={null}
{
  "success": false,
  "message": "Invalid bearer token"
}
```

## Notes importantes

1. **Scope strict** : La fiche n'est retournée que si elle appartient à la `agencyGroup` du token ET à une des `agencies` listées dans le LinkedAPI. Aucune fuite cross-group, même avec un `id` Mongo connu d'une autre agence.
2. **Pas de différenciation 404 vs 403** : Une fiche hors scope retourne le même `null` qu'une fiche inexistante. Choix volontaire pour ne pas leak l'existence de fiches d'autres agences.
3. **Contacts re-scopés** : Les contacts liés sont eux-mêmes filtrés sur `agency ∈ linkedAPI.agencies` pour éviter les fuites cross-group.
4. **Idempotence** : L'endpoint est purement en lecture. Aucune modification d'état.
5. **Cas d'usage typique** : Réception d'une notification de nouveau lead → extraction du `customId` ou `id` du mail → appel GET → récupération email/nom/adresse du bien pour automatisation (Make, Zapier, etc.).
6. **Champs absents vs `null`** : les champs non renseignés sur la fiche n'apparaissent **pas du tout** dans la réponse — ils ne sont pas retournés à `null`. Côté client, traiter chaque champ comme optionnel.
7. **Cas d'usage pré-remplissage formulaire offre** : récupérer le sale via `customId` → utiliser `property.addressData` (adresse splittée prête à l'emploi), `mandate.price` (HAI), `mandate.feeResponsibility` + `mandate.commissionPercentage` (charge & % honoraires), `property.floor` / `property.lotsNumbers` (étage / lots pour appartements). Récupérer les coordonnées du vendeur via `GET /external-integration/contact` avec le `mainContact`.

## Rate limits

Cette route est limitée à **500 req / minute par groupe d'agences** (bucket dédié, indépendant des autres routes).

* Headers présents sur **toutes** les réponses : `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (secondes avant reset).
* Dépassement → `429 Too Many Requests` avec header `Retry-After` (secondes) :

```json theme={null}
{
  "success": false,
  "message": "Rate limit exceeded",
  "retryAfter": 27
}
```

* Si vous atteignez régulièrement la limite, contactez le support pour évaluer un relèvement sur votre token.


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